Skip to main content

SDKs

Official client libraries for integrating Cue into your applications.

JavaScript/TypeScript SDK​

Installation​

npm install @cue/sdk
# or
yarn add @cue/sdk
# or
pnpm add @cue/sdk

Basic Usage​

import { CueAds } from '@cue/sdk';

const cue = new CueAds({
  apiKey: 'your-api-key',
  environment: 'production' // or 'development'
});

// Request an ad
const ad = await cue.requestAd({
  context: {
    conversation: "User discussing project management tools",
    userQuery: "What are some good options for small teams?"
  },
  placement: {
    type: 'inline',
    position: 'after_response'
  }
});

if (ad) {
  console.log(ad.content.headline);
  console.log(ad.content.description);
}

Advanced Configuration​

const cue = new CueAds({
  apiKey: 'your-api-key',
  environment: 'production',
  options: {
    timeout: 5000,
    retries: 3,
    cache: true,
    cacheTTL: 300000, // 5 minutes
    baseUrl: 'https://api.oncue.ad/api/v1'
  }
});

React Integration​

import { useCueAd } from '@cue/sdk/react';

function ChatMessage({ conversation, userQuery }) {
  const { ad, loading, error } = useCueAd({
    context: { conversation, userQuery },
    placement: { type: 'inline', position: 'after_response' }
  });

  if (loading) return <div>Loading ad...</div>;
  if (error) return null;
  if (!ad) return null;

  return (
    <div className="ad-container" onClick={() => ad.click()}>
      <h4>{ad.content.headline}</h4>
      <p>{ad.content.description}</p>
      <button>{ad.content.callToAction}</button>
    </div>
  );
}

Python SDK​

Installation​

pip install cue-ads

Basic Usage​

from cue_ads import CueAds

cue = CueAds(api_key='your-api-key')

# Request an ad
ad = cue.request_ad(
    context={
        'conversation': 'User discussing project management tools',
        'user_query': 'What are some good options for small teams?'
    },
    placement={
        'type': 'inline',
        'position': 'after_response'
    }
)

if ad:
    print(ad.content.headline)
    print(ad.content.description)

Async Usage​

import asyncio
from cue_ads import AsyncCueAds

async def main():
    cue = AsyncCueAds(api_key='your-api-key')
    
    ad = await cue.request_ad(
        context={'conversation': '...', 'user_query': '...'},
        placement={'type': 'inline', 'position': 'after_response'}
    )
    
    if ad:
        print(f"Ad: {ad.content.headline}")

asyncio.run(main())

Django Integration​

# models.py
from django.db import models
from cue_ads import CueAds

class ChatMessage(models.Model):
    conversation_id = models.CharField(max_length=100)
    message = models.TextField()
    user_query = models.TextField()
    
    def get_contextual_ad(self):
        cue = CueAds(api_key=settings.CUE_API_KEY)
        return cue.request_ad(
            context={
                'conversation': self.message,
                'user_query': self.user_query
            },
            placement={'type': 'inline', 'position': 'after_response'}
        )

# views.py
from django.shortcuts import render
from .models import ChatMessage

def chat_view(request, conversation_id):
    messages = ChatMessage.objects.filter(conversation_id=conversation_id)
    latest_message = messages.last()
    
    ad = latest_message.get_contextual_ad() if latest_message else None
    
    return render(request, 'chat.html', {
        'messages': messages,
        'ad': ad
    })

Go SDK​

Installation​

go get github.com/cue-ai/cue-go

Basic Usage​

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/cue-ai/cue-go"
)

func main() {
    client := cue.NewClient("your-api-key")
    
    ad, err := client.RequestAd(context.Background(), &cue.AdRequest{
        Context: &cue.Context{
            Conversation: "User discussing project management tools",
            UserQuery:    "What are some good options for small teams?",
        },
        Placement: &cue.Placement{
            Type:     "inline",
            Position: "after_response",
        },
    })
    
    if err != nil {
        log.Fatal(err)
    }
    
    if ad != nil {
        fmt.Printf("Ad: %s - %s\n", ad.Content.Headline, ad.Content.Description)
    }
}

Gin Framework Integration​

package main

import (
    "net/http"
    
    "github.com/gin-gonic/gin"
    "github.com/cue-ai/cue-go"
)

func main() {
    r := gin.Default()
    cueClient := cue.NewClient("your-api-key")
    
    r.POST("/chat", func(c *gin.Context) {
        var req struct {
            Conversation string `json:"conversation"`
            UserQuery    string `json:"user_query"`
        }
        
        if err := c.ShouldBindJSON(&req); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        
        ad, err := cueClient.RequestAd(c.Request.Context(), &cue.AdRequest{
            Context: &cue.Context{
                Conversation: req.Conversation,
                UserQuery:    req.UserQuery,
            },
            Placement: &cue.Placement{
                Type:     "inline",
                Position: "after_response",
            },
        })
        
        if err != nil {
            c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
            return
        }
        
        c.JSON(http.StatusOK, gin.H{"ad": ad})
    })
    
    r.Run()
}

Java SDK​

Installation​

Maven​

<dependency>
    <groupId>ai.cue</groupId>
    <artifactId>cue-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle​

implementation 'ai.cue:cue-java-sdk:1.0.0'

Basic Usage​

import ai.cue.CueAds;
import ai.cue.model.AdRequest;
import ai.cue.model.Context;
import ai.cue.model.Placement;
import ai.cue.model.Ad;

public class ChatBot {
    private final CueAds cueAds;
    
    public ChatBot(String apiKey) {
        this.cueAds = new CueAds(apiKey);
    }
    
    public Ad getContextualAd(String conversation, String userQuery) {
        Context context = Context.builder()
            .conversation(conversation)
            .userQuery(userQuery)
            .build();
            
        Placement placement = Placement.builder()
            .type("inline")
            .position("after_response")
            .build();
            
        AdRequest request = AdRequest.builder()
            .context(context)
            .placement(placement)
            .build();
            
        return cueAds.requestAd(request);
    }
}

Spring Boot Integration​

@RestController
@RequestMapping("/api/chat")
public class ChatController {
    
    @Autowired
    private CueAds cueAds;
    
    @PostMapping("/message")
    public ResponseEntity<ChatResponse> handleMessage(@RequestBody ChatRequest request) {
        // Process the chat message
        String response = chatService.processMessage(request.getMessage());
        
        // Get contextual ad
        Ad ad = cueAds.requestAd(AdRequest.builder()
            .context(Context.builder()
                .conversation(request.getConversation())
                .userQuery(request.getMessage())
                .build())
            .placement(Placement.builder()
                .type("inline")
                .position("after_response")
                .build())
            .build());
            
        return ResponseEntity.ok(ChatResponse.builder()
            .message(response)
            .ad(ad)
            .build());
    }
}

@Configuration
public class CueConfig {
    
    @Bean
    public CueAds cueAds(@Value("${cue.api-key}") String apiKey) {
        return new CueAds(apiKey);
    }
}

PHP SDK​

Installation​

composer require cue-ai/cue-php

Basic Usage​

<?php
use CueAi\CueAds;

$cue = new CueAds('your-api-key');

$ad = $cue->requestAd([
    'context' => [
        'conversation' => 'User discussing project management tools',
        'userQuery' => 'What are some good options for small teams?'
    ],
    'placement' => [
        'type' => 'inline',
        'position' => 'after_response'
    ]
]);

if ($ad) {
    echo "Ad: " . $ad->content->headline . " - " . $ad->content->description;
}
?>

Laravel Integration​

// config/services.php
return [
    'cue' => [
        'api_key' => env('CUE_API_KEY'),
    ],
];

// app/Services/CueService.php
<?php
namespace App\Services;

use CueAi\CueAds;

class CueService
{
    private $cue;
    
    public function __construct()
    {
        $this->cue = new CueAds(config('services.cue.api_key'));
    }
    
    public function getContextualAd(string $conversation, string $userQuery)
    {
        return $this->cue->requestAd([
            'context' => [
                'conversation' => $conversation,
                'userQuery' => $userQuery
            ],
            'placement' => [
                'type' => 'inline',
                'position' => 'after_response'
            ]
        ]);
    }
}

// app/Http/Controllers/ChatController.php
<?php
namespace App\Http\Controllers;

use App\Services\CueService;
use Illuminate\Http\Request;

class ChatController extends Controller
{
    private $cueService;
    
    public function __construct(CueService $cueService)
    {
        $this->cueService = $cueService;
    }
    
    public function handleMessage(Request $request)
    {
        $conversation = $request->input('conversation');
        $userQuery = $request->input('user_query');
        
        $ad = $this->cueService->getContextualAd($conversation, $userQuery);
        
        return response()->json(['ad' => $ad]);
    }
}
?>

Ruby SDK​

Installation​

gem install cue_ads

Basic Usage​

require 'cue_ads'

cue = CueAds::Client.new(api_key: 'your-api-key')

ad = cue.request_ad(
  context: {
    conversation: 'User discussing project management tools',
    user_query: 'What are some good options for small teams?'
  },
  placement: {
    type: 'inline',
    position: 'after_response'
  }
)

if ad
  puts "Ad: #{ad.content.headline} - #{ad.content.description}"
end

Rails Integration​

# Gemfile
gem 'cue_ads'

# config/initializers/cue.rb
CueAds.configure do |config|
  config.api_key = Rails.application.credentials.cue_api_key
  config.environment = Rails.env.production? ? 'production' : 'development'
end

# app/controllers/chat_controller.rb
class ChatController < ApplicationController
  def create
    conversation = params[:conversation]
    user_query = params[:user_query]
    
    ad = CueAds::Client.new.request_ad(
      context: {
        conversation: conversation,
        user_query: user_query
      },
      placement: {
        type: 'inline',
        position: 'after_response'
      }
    )
    
    render json: { ad: ad }
  end
end

Error Handling​

All SDKs provide consistent error handling:

// JavaScript
try {
  const ad = await cue.requestAd(context, placement);
} catch (error) {
  if (error instanceof CueApiError) {
    console.error('API Error:', error.message, error.statusCode);
  } else if (error instanceof CueTimeoutError) {
    console.error('Request timed out');
  } else {
    console.error('Unexpected error:', error);
  }
}
# Python
from cue_ads.exceptions import CueApiError, CueTimeoutError

try:
    ad = cue.request_ad(context, placement)
except CueApiError as e:
    print(f"API Error: {e.message} (Status: {e.status_code})")
except CueTimeoutError:
    print("Request timed out")
except Exception as e:
    print(f"Unexpected error: {e}")

Best Practices​

  1. API Key Security: Never expose API keys in client-side code
  2. Error Handling: Always handle potential errors gracefully
  3. Caching: Implement caching for similar requests to improve performance
  4. Timeout Configuration: Set appropriate timeouts for your use case
  5. Rate Limiting: Respect API rate limits and implement retry logic
  6. Testing: Use test/development API keys during development

Support​

For SDK-specific issues:

For general support: support@oncue.ad