Migration to SSP API

This guide helps you migrate from the legacy Ad Serving API to the new SSP Bidding API.

Why Migrate?

The SSP API offers several advantages over the legacy API:

• Better Performance: Two-phase design with fast bidding (<1000ms>) and flexible ad serving
• Industry Standard: Compatible with Supply-Side Platforms and RTB protocols
• Improved Tracking: Enhanced click tracking with comprehensive analytics
• Future-Proof: Built for modern programmatic advertising ecosystems

Key Differences

API Structure

Aspect	Legacy API	SSP API
Phases	Single request/response	Two-phase (bid + ad)
Endpoint	/ad-serving/request	/ssp/bid + /ssp/ad/{bidId}
Request Format	Complex nested object	Simple message array
Response Format	Full ad details	Bid amount + ID
Click Tracking	/ad-serving/click/{adId}	/click/{trackingId}
Rate Limiting	1,000 req/min	15 req/sec

Request Format Changes

Legacy API Request

{
  "context": {
    "conversation": "I'm looking for running shoes",
    "userQuery": "What are good running shoes?",
    "metadata": {
      "userAgent": "...",
      "sessionId": "...",
      "userId": "..."
    }
  },
  "placement": {
    "type": "inline",
    "position": "after_response",
    "dimensions": {
      "width": 300,
      "height": 250
    }
  },
  "preferences": {
    "adFormat": "text",
    "maxAds": 1,
    "categories": ["sports"],
    "excludeCategories": ["gambling"]
  }
}

SSP API Request

{
  "countryCode": "US",
  "messages": [
    {
      "role": "user",
      "content": "I'm looking for running shoes"
    },
    {
      "role": "assistant",
      "content": "I can help you find great running shoes. What's your budget?"
    }
  ]
}

Response Format Changes

Legacy API Response

{
  "ads": [
    {
      "id": "ad-789",
      "campaignId": "campaign-123",
      "type": "text",
      "content": {
        "headline": "Best Running Shoes",
        "description": "Premium quality shoes for daily runs",
        "callToAction": "Shop Now",
        "landingUrl": "https://example.com"
      },
      "tracking": {
        "impressionUrl": "https://app.oncue.ad/api/v1/ad-serving/impression/ad-789",
        "clickUrl": "https://app.oncue.ad/api/v1/ad-serving/click/ad-789"
      },
      "metadata": {
        "relevanceScore": 0.92,
        "bidAmount": 2.45,
        "category": "sports"
      }
    }
  ],
  "requestId": "req-abc123",
  "timestamp": "2024-01-15T10:30:00Z"
}

SSP API Response (Bid Phase)

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

SSP API Response (Ad Phase)

{
  "adText": "Best Running Shoes - Premium quality shoes for daily runs",
  "redirectUrl": "https://app.oncue.ad/api/v1/click/track123-xyz456-abc789"
}

Migration Steps

Step 1: Update Endpoints

Replace the single legacy endpoint with two SSP endpoints:

Before (Legacy)

const response = await fetch('https://app.oncue.ad/api/v1/ad-serving/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    context: { conversation, userQuery },
    placement: { type: 'inline', position: 'after_response' }
  })
});

After (SSP)

// 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': apiKey
  },
  body: JSON.stringify({
    countryCode: 'US',
    messages: [
      { role: 'user', content: userQuery },
      { role: 'assistant', content: assistantResponse }
    ]
  })
});

const bid = await bidResponse.json();

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

Step 2: Update Authentication

Change from Bearer token to X-API-Key header:

Before

'Authorization': `Bearer ${apiKey}`

After

'X-API-Key': apiKey

Step 3: Update Request Format

Transform your conversation data to the new message format:

Before

function createLegacyRequest(conversation, userQuery) {
  return {
    context: {
      conversation: conversation,
      userQuery: userQuery
    },
    placement: {
      type: 'inline',
      position: 'after_response'
    }
  };
}

After

function createSSPRequest(messages, countryCode = 'US') {
  return {
    countryCode: countryCode,
    messages: messages.map(msg => ({
      role: msg.role, // 'user' or 'assistant'
      content: msg.content
    }))
  };
}

Step 4: Update Response Handling

Adapt your code to handle the two-phase response:

Before

const response = await requestAd(context);
if (response.ads && response.ads.length > 0) {
  const ad = response.ads[0];
  displayAd(ad);
  trackImpression(ad.id);
}

After

const bid = await submitBid(messages, countryCode);
if (bid && bid.bidId) {
  // Simulate winning the auction
  const ad = await generateAd(bid.bidId);
  if (ad) {
    displayAd(ad);
    // Click tracking is handled automatically via redirectUrl
  }
}

Step 5: Update Click Tracking

The SSP API handles click tracking automatically through redirect URLs:

Before

function handleAdClick(adId) {
  fetch(`https://app.oncue.ad/api/v1/ad-serving/click/${adId}`)
    .then(response => response.json())
    .then(data => {
      window.open(data.redirectUrl, '_blank');
    });
}

After

function handleAdClick(redirectUrl) {
  // Simply use the redirect URL directly
  window.open(redirectUrl, '_blank');
}

Complete Migration Example

Here's a complete example showing the migration:

Legacy Implementation

class LegacyAdService {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://app.oncue.ad/api/v1';
  }

  async requestAd(conversation, userQuery) {
    const response = await fetch(`${this.baseUrl}/ad-serving/request`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify({
        context: { conversation, userQuery },
        placement: { type: 'inline', position: 'after_response' }
      })
    });

    const data = await response.json();
    return data.ads[0] || null;
  }

  async trackClick(adId) {
    const response = await fetch(`${this.baseUrl}/ad-serving/click/${adId}`);
    const data = await response.json();
    return data.redirectUrl;
  }
}

SSP Implementation

class SSPAdService {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://app.oncue.ad/api/v1';
  }

  async submitBid(messages, countryCode = 'US') {
    const response = await fetch(`${this.baseUrl}/ssp/bid`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': this.apiKey
      },
      body: JSON.stringify({ countryCode, messages })
    });

    if (!response.ok) return null;
    return await response.json();
  }

  async generateAd(bidId) {
    const response = await fetch(`${this.baseUrl}/ssp/ad/${bidId}`, {
      headers: {
        'X-API-Key': this.apiKey
      }
    });

    if (!response.ok) return null;
    return await response.json();
  }

  async requestAd(messages, countryCode = 'US') {
    const bid = await this.submitBid(messages, countryCode);
    if (!bid || !bid.bidId) return null;

    // In a real SSP integration, you would only call generateAd 
    // if you win the auction
    return await this.generateAd(bid.bidId);
  }
}

Migration Checklist

• Update API endpoints from /ad-serving/request to /ssp/bid and /ssp/ad/{bidId}
• Change authentication from Bearer token to X-API-Key header
• Convert request format from nested objects to message arrays
• Update response handling for two-phase flow
• Replace click tracking with direct redirect URL usage
• Update rate limiting logic (15 req/sec vs 1,000 req/min)
• Test the integration with development endpoints
• Update error handling for new response formats
• Monitor performance improvements
• Remove legacy API code after successful migration

Testing Your Migration

1. Test Bidding Endpoint

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": "I need running shoes"},
      {"role": "assistant", "content": "I can help you find running shoes"}
    ]
  }'

2. Test Ad Generation

curl -X GET "https://app.oncue.ad/api/v1/ssp/ad/{bidId}" \
  -H "X-API-Key: your-api-key"

3. Test Click Tracking

curl -X GET "https://app.oncue.ad/api/v1/click/{trackingId}" \
  -H "User-Agent: Mozilla/5.0 (Test Browser)"

Timeline

• Now: SSP API available for testing
• Q2 2024: Legacy API marked as deprecated
• Q4 2024: Legacy API support ends
• Q1 2025: Legacy API removed

Support

If you need help with migration:

• Documentation: SSP API Reference
• Email: support@oncue.ad
• Migration Support: We offer free migration assistance for existing customers

Frequently Asked Questions

Q: Will the legacy API stop working immediately?

A: No, the legacy API will continue to work during the deprecation period. However, new features and optimizations will only be available in the SSP API.

Q: Do I need to change my campaign setup?

A: No, your existing campaigns will work with both APIs. The SSP API uses the same campaign matching logic.

Q: What if I can't complete the migration by the deadline?

A: Contact our support team at support@oncue.ad - we can provide additional assistance or discuss timeline extensions.

Q: Are there performance improvements with the SSP API?

A: Yes, the SSP API is designed for faster bidding responses and better scalability. You should see improved response times and higher throughput.

Q: Do I need to update my analytics tracking?

A: The SSP API provides the same analytics data through the new click tracking system. Your existing metrics will continue to work.