SSP Integration Guide

Overview

Cue provides a conversational advertising platform that integrates with Supply-Side Platforms (SSPs).

Base URLs

https://app.oncue.ad

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

X-API-Key: your-api-key-here

Endpoints

1. Bidding Endpoint

Endpoint: POST /api/v1/ssp/bid

Purpose: Submit a bid for an ad slot in a conversational context.

Performance Requirements:

• Response time: <1000ms>
• Rate limit: 15 requests per second

Request Format:

{
  "countryCode": "US",
  "messages": [
    {"role": "user", "content": "how to make a cake?"},
    {"role": "assistant", "content": "Making a cake is easy..."}
  ]
}

Response Format:

{
  "bid": 1.7,
  "bidId": "a41bd3ea-1234-5678-9abc-def012345678"
}

Example Request:

curl -X POST "https://app.oncue.ad/api/v1/ssp/bid" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "countryCode": "US",
    "messages": [
      {"role": "user", "content": "I need running shoes for my daily jogs"},
      {"role": "assistant", "content": "I can help you find the perfect running shoes. What is your budget range?"}
    ]
  }'

Example Response:

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

2. Ad Generation Endpoint

Endpoint: GET /api/v1/ssp/ad/{bidId}

Purpose: Retrieve ad content after winning an auction.

Performance Requirements:

• Response time: <3000ms>
• Rate limit: 15 requests per second

Request Format:

GET /api/v1/ssp/ad/550e8400-e29b-41d4-a716-446655440000

Response Format:

{
  "adText": "Discover premium running shoes with 30% off today!",
  "redirectUrl": "https://app.oncue.ad/api/v1/click/abc123-def456-ghi789"
}

Example Request:

curl -X GET "https://app.oncue.ad/api/v1/ssp/ad/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: your-api-key-here"

Example Response:

{
  "adText": "Get the best running shoes for your daily workout. Premium quality, 30% off!",
  "redirectUrl": "https://app.oncue.ad/api/v1/click/track123-xyz456-abc789"
}

Click Tracking

How It Works

All ad URLs returned by Cue are internal tracking URLs that:

1. Log the click with full analytics (timestamp, user agent, referrer, etc.)
2. Update campaign metrics in real-time
3. Redirect to the advertiser's destination URL

Tracking URL Format

https://app.oncue.ad/api/v1/click/{trackingId}

Example Click Flow

1. User clicks on ad link: https://app.oncue.ad/api/v1/click/track123-xyz456-abc789
2. Cue logs the click event with analytics
3. Cue updates campaign click metrics
4. Cue redirects user to: https://advertiser.com/running-shoes-landing

Analytics Data Collected

• Click timestamp
• User agent (browser/device info)
• Referrer URL
• Anonymized IP address (last octet removed)
• Campaign ID and impression ID
• Bid amount and auction details

Error Handling

Bidding Errors

No matching campaigns:

null

Invalid request:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Ad Generation Errors

Bid expired or not found:

{
  "statusCode": 404,
  "message": "Bid not found or expired",
  "error": "Not Found"
}

Campaign not found:

{
  "statusCode": 404,
  "message": "Campaign not found",
  "error": "Not Found"
}

Testing

Test Bidding Endpoint

# Test bid request
curl -X POST "http://localhost:3001/api/v1/ssp/bid" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-api-key" \
  -d '{
    "countryCode": "US",
    "messages": [
      {"role": "user", "content": "I want to buy a laptop"},
      {"role": "assistant", "content": "I can help you find the perfect laptop. What will you be using it for?"}
    ]
  }'

Test Ad Generation

# Replace {bidId} with actual bid ID from previous response
curl -X GET "http://localhost:3001/api/v1/ssp/ad/{bidId}" \
  -H "X-API-Key: test-api-key"

Test Click Tracking

# Replace {trackingId} with actual tracking ID from ad response
curl -X GET "http://localhost:3001/api/v1/click/{trackingId}" \
  -H "User-Agent: Mozilla/5.0 (Test Browser)"

Performance Expectations

Metric	Target	Notes
Bid Response Time	<1000ms>	Critical for auction participation
Ad Generation Time	<3000ms>	Called only after winning auction
Click Redirect Time	<200ms>	Fast redirect to advertiser
Uptime	99.9%	High availability required
Error Rate	<1%>	Includes both 4xx and 5xx errors

Rate Limiting

• Bidding: 15 requests per second per API key
• Ad Generation: 15 requests per second per API key
• Click Tracking: No rate limits (user-initiated)

Support

For integration support, please contact:

• Email: support@oncue.ad
• Documentation: https://docs.oncue.ad
• Status Page: https://status.oncue.ad

Deployment Process

Cue follows a gradual deployment process for new SSP integrations:

Period	Traffic	Duration
Testing	1%	24 hours
Ramp-up	10%	24 hours
Full Production	100%	Ongoing

Advanced Features

Bid Floor Support

Cue respects bid floors set by publishers. If your bid is below the floor, it will not participate in the auction.

Geo-Targeting

Cue considers the countryCode parameter for geo-targeted campaigns. Campaigns can be configured to only serve in specific countries.

Budget Management

Cue automatically pauses campaigns when daily or total budgets are exhausted, ensuring you never exceed your spending limits.

Real-Time Metrics

Track your campaign performance in real-time through the Cue dashboard:

• Bid requests and win rates
• Click-through rates
• Conversion tracking
• Cost per acquisition

Troubleshooting

Common Issues

1. Slow bid responses: Check if your campaigns have pre-computed embeddings
2. Low win rates: Review your bid amounts and targeting settings
3. Click tracking failures: Verify your tracking URLs are properly formatted
4. Campaign not serving: Check campaign status and budget availability

Debug Mode

For development, you can enable debug mode by adding a header:

X-Debug: true

This will return additional information about the bidding process and campaign matching.