Integration Guide

This document provides a step-by-step technical integration guide for developers implementing the Teads AI Chatbot SDK, enabling real-time communication with Teads’ measurement, content, and marketer endpoints.

---

1. Overview

The Teads AI Chatbot SDK connects chatbots, web clients, or native apps to Teads’ data ecosystem.
It allows partners to:

• Report measurement events (e.g., chatbot load, view, click)
• Fetch publisher (organic) content
• Fetch marketer (paid) content
• Optionally render a paid recommendation widget
• Track viewability and user interactions in compliance with Teads’ reporting framework

All flows share a unified request structure and use query-based GET requests with JSON (vjnc) responses.

---

2. Architecture Overview

Core Components

Component	Description
Teads SDK	Client library integrated into the chatbot or web environment
Partner API	Receives requests for measurement, organic, or paid content
Server Proxy (recommended)	Secure middleware to inject API keys and sanitize requests
Outbrain Content API	Backend provider for organic and paid content feeds
Chatbot Logic Layer	Orchestrates event triggers, data retrieval, and UI updates

Data Flow Diagram

+------------------+       +-------------------+       +-------------------+
|  User Chatbot UI | ---> |  Teads SDK Layer  | ---> | Partner Endpoint   |
| (view, click)    |       |  (event builder)  |       | (Outbrain/Teads)  |
+------------------+       +-------------------+       +-------------------+
        |                           ^                           |
        v                           |                           v
   Chatbot server <------------- Secure Proxy <------------- JSON Response

---

3. API Endpoints

Base URL: https://mv.outbrain.com
Base path: /Multivac/api/platforms
HTTP method: GET
Response format: vjnc (JSON)
Authentication: API key via query param key

---

4. Common Parameters

Parameter	Type	Required	Description
contentUrl	string	✅	URI-encoded canonical page URL (no query params)
key	string	✅	API key provisioned by Teads/Partner
widgetJSId	string	✅	Widget identifier per flow
idx	integer	✅	Slot index (0 for single-slot integrations)
format	string	✅	Response format; must be vjnc
cors	boolean	✅	Must be true for browser/chatbot calls
testMode	boolean	optional	Enables QA mode; disables production reporting

---

5. Integration Steps

Step 1 — SDK Initialization

Embed or import the Teads SDK within your chatbot or frontend system.

import { TeadsSDK } from "teads-ai-chatbot-sdk";

const sdk = new TeadsSDK({
  apiKey: "{YOUR_CONTENT_API_KEY}",
  measurementKey: "{YOUR_MEASUREMENT_API_KEY}",
  widgetIds: {
    measurement: "{YOUR_MEASUREMENT_WIDGET_ID}",
    organic: "{YOUR_ORGANIC_WIDGET_ID}",
    paid: "{YOUR_PAID_WIDGET_ID}"
  }
});

---

Step 2 — Fire Measurement Events

Measurement events are lightweight HTTP GET requests sent whenever a key lifecycle event occurs.

Example events: chatbot_load, unit_load, unit_view, unit_click

sdk.fireMeasurementEvent("chatbot_load", {
  contentUrl: encodeURIComponent(window.location.href),
  testMode: true
});

The SDK handles timing and queuing to ensure delivery within 3 minutes of the triggering action.

---

Step 3 — Fetch Content

a. Publisher (Organic) Content

const organicData = await sdk.fetchContent("publisher", {
  news: "latest",
  newsFrom: "US",
  testMode: true
});

b. Marketer (Paid) Content

const paidData = await sdk.fetchContent("marketer", {
  testMode: true
});

Responses follow the vjnc JSON schema from Outbrain’s Partner API.

---

Step 4 — Render Paid Widget (Optional)

Use this on mobile layouts to render a responsive, single paid recommendation unit.

<div class="OUTBRAIN"
     data-ob-contentUrl="{PAGE_URL}"
     data-widget-id="MB_1"
     data-ob-installation-key="{YOUR_INSTALLATION_KEY}"></div>

<script type="text/javascript" async src="https://widgets.outbrain.com/outbrain.js"></script>

For layout and sizing details, see:
https://developer.outbrain.com/using-js-widget-in-web-mediation/

---

Step 5 — Track Events and Viewability

Widget-level Event: reportServed (required)

Fire once when a unit is rendered on the device. Must trigger within 3 minutes.

sdk.reportServed({ placementId: "widget_1" });

Listing-level Events

Event	Description	Requirement
doc.on-viewed	≥50% in viewport for 1s	✅ Required
doc.pixels	Up to 5 image pixels per listing	✅ Required
doc.jsTrackers	JS trackers client-side only	Optional
doc.clickTrackers	Pixel URLs fired on click	Optional

---

6. Click Handling

Paid recommendations

• Navigate exactly to doc.url (e.g. http://paid.outbrain.com/network/redir)
• Do not modify or append redirects

Organic recommendations

• Option 1: navigate to doc.url directly
• Option 2: open doc.orig_url for the user and ping doc.url in parallel to log the click

window.open(doc.orig_url, "_blank");
fetch(doc.url); // async click registration

---

7. Testing and QA

Always use testMode=true in development.
Validate the following before production rollout:

• ✅ All URLs are HTTPS
• ✅ contentUrl is canonical and encoded
• ✅ Responses conform to vjnc schema
• ✅ All required events fire within 3 minutes
• ✅ Click tracking preserves Partner URLs

Example validation call:

curl -G "https://mv.outbrain.com/Multivac/api/platforms"   --data-urlencode "contentUrl=https%3A%2F%2Fexample.com"   --data-urlencode "key={YOUR_MEASUREMENT_API_KEY}"   --data-urlencode "widgetJSId={YOUR_MEASUREMENT_WIDGET_ID}"   --data-urlencode "extid=chatbot_load"   --data-urlencode "idx=0"   --data-urlencode "format=vjnc"   --data-urlencode "cors=true"   --data-urlencode "testMode=true"

---

8. Security and Performance

• Never expose API keys in frontend code.
• Always use a secure HTTPS proxy to inject or sign API keys.
• Execute pixels and JS trackers asynchronously.
• Minimize redundant requests — throttle repetitive measurement or content fetches.
• Avoid blocking UI threads during network calls.

---

9. Troubleshooting

Issue	Cause	Solution
403 Forbidden	Invalid or missing key	Verify key and widget ID
Empty JSON response	Incorrect idx or missing required params	Check query string
Clicks not tracked	Modified redirect URL	Use doc.url unmodified
Events delayed	Network or timing issue	Fire within 3 minutes
Widget not rendering	Missing outbrain.js or invalid installation key	Check widget markup

---

© 2025 Teads AI Platform. All rights reserved.