Skip to main content

Quick Start Guide

This guide will help you integrate Cue into your application in under 15 minutes.

💡 Recommendation: This guide shows the modern SSP API approach. For legacy API examples, see the Integration Guide.

Prerequisites​

  • A conversational application (chatbot, AI assistant, etc.)
  • Basic knowledge of REST APIs
  • A Cue account (create one at dashboard.oncue.ad)

Step 1: Get Your API Key​

  1. Log in to the Cue Dashboard
  2. Navigate to API Keys in the sidebar
  3. Click Create New API Key
  4. Give it a descriptive name (e.g., "Production App")
  5. Copy the generated API key (starts with cue_live_ or cue_test_)

Step 2: Make Your First Request​

Test your API key with a simple bid request:

curl -X POST https://app.oncue.ad/api/v1/ssp/bid \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "countryCode": "US",
    "messages": [
      {
        "role": "user",
        "content": "What are some good project management tools?"
      },
      {
        "role": "assistant",
        "content": "I can help you find great project management tools for your startup"
      }
    ]
  }'

This will return a bid response like:

{
  "bid": 2.50,
  "bidId": "550e8400-e29b-41d4-a716-446655440000"
}

Step 3: Integrate into Your App​

JavaScript/Node.js​

async function getContextualAd(messages, countryCode = 'US') {
  // Phase 1: Submit bid
  const bidResponse = await fetch('https://app.oncue.ad/api/v1/ssp/bid', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      countryCode,
      messages
    })
  });

  const bid = await bidResponse.json();
  if (!bid || !bid.bidId) return null;

  // Phase 2: Generate ad (simulate winning auction)
  const adResponse = await fetch(`https://app.oncue.ad/api/v1/ssp/ad/${bid.bidId}`, {
    headers: {
      'X-API-Key': 'YOUR_API_KEY'
    }
  });

  const ad = await adResponse.json();
  return ad;
}

// Usage in your chatbot
const messages = [
  { role: 'user', content: 'What tools can help my team collaborate better?' },
  { role: 'assistant', content: 'I can recommend some great collaboration tools for your team' }
];

const ad = await getContextualAd(messages);

if (ad) {
  console.log(`Ad: ${ad.adText}`);
  console.log(`Click URL: ${ad.redirectUrl}`);
}

Python​

import requests

def get_contextual_ad(messages, country_code='US'):
    # Phase 1: Submit bid
    bid_response = requests.post(
        'https://app.oncue.ad/api/v1/ssp/bid',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': 'YOUR_API_KEY'
        },
        json={
            'countryCode': country_code,
            'messages': messages
        }
    )
    
    bid = bid_response.json()
    if not bid or 'bidId' not in bid:
        return None
    
    # Phase 2: Generate ad (simulate winning auction)
    ad_response = requests.get(
        f'https://app.oncue.ad/api/v1/ssp/ad/{bid["bidId"]}',
        headers={
            'X-API-Key': 'YOUR_API_KEY'
        }
    )
    
    return ad_response.json()

# Usage in your chatbot
messages = [
    {'role': 'user', 'content': 'What tools can help my team collaborate better?'},
    {'role': 'assistant', 'content': 'I can recommend some great collaboration tools for your team'}
]

ad = get_contextual_ad(messages)

if ad:
    print(f"Ad: {ad['adText']}")
    print(f"Click URL: {ad['redirectUrl']}")

Step 4: Handle Ad Clicks​

With the SSP API, click tracking is automatically handled through the redirect URL:

function handleAdClick(redirectUrl) {
  // Simply open the redirect URL - tracking is automatic
  window.open(redirectUrl, '_blank');
}

// Usage
if (ad && ad.redirectUrl) {
  handleAdClick(ad.redirectUrl);
}

The SSP API automatically tracks clicks and analytics when users visit the redirect URL, then redirects them to the advertiser's destination.

Best Practices​

  1. Provide Rich Context: Include multiple conversation turns for better ad matching
  2. Handle No Bids: Always check if bids are returned and have fallback content
  3. Respect User Privacy: Only collect data you need and follow privacy regulations
  4. Test Thoroughly: Test with different conversation contexts in development
  5. Optimize for Speed: The SSP API is designed for fast responses - take advantage of it

Error Handling​

async function getContextualAdSafe(messages, countryCode = 'US') {
  try {
    // Phase 1: Submit bid
    const bidResponse = await fetch('https://app.oncue.ad/api/v1/ssp/bid', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({ countryCode, messages })
    });

    if (!bidResponse.ok) {
      throw new Error(`Bid failed: ${bidResponse.status}`);
    }

    const bid = await bidResponse.json();
    if (!bid || !bid.bidId) return null;

    // Phase 2: Generate ad
    const adResponse = await fetch(`https://app.oncue.ad/api/v1/ssp/ad/${bid.bidId}`, {
      headers: {
        'X-API-Key': 'YOUR_API_KEY'
      }
    });

    if (!adResponse.ok) {
      throw new Error(`Ad generation failed: ${adResponse.status}`);
    }

    const ad = await adResponse.json();
    return ad;
  } catch (error) {
    console.error('Failed to fetch ad:', error);
    return null; // Return null on error
  }
}

What's Next?​

Ready to go live? Make sure to:

  1. Replace test API keys with production keys
  2. Set up proper error handling
  3. Implement analytics tracking
  4. Test with real user conversations