TeadsCTV Homescreen
Teads · Technical Documentation

CTV Homescreen oRTB Integration.

How to integrate with the Teads SSP through OpenRTB for CTV Homescreen native inventory. We are fully compliant with OpenRTB 2.6 and Native Ads API 1.2, combined with the VAST protocol for the video experience.

OpenRTB 2.6 spec Native Ads 1.2 spec
01 · Formats

Supported native asset types.

For a full overview of supported asset types, dimensions, ratios and file-size limits, refer to the dedicated ad-specifications page.

Ad specifications

CTV Homescreen — Ad specifications

Supported image and video asset types, dimensions, ratios and file-size limits.

View the specifications
02 · Bid-request

Bid-request details.

A sample OpenRTB 2.6 bid-request with two native impressions — one video experience and one image experience.

JSON · OpenRTB 2.6 · Bid-requestexpand
{
    "id": "bid-request-id-1234",
    "at": 1,
    "tmax": 1000,
    "app": {
        "id": "ctv-native-app",
        "name": "CTV Native Application",
        "bundle": "com.ctv.native.app",
        "pagecat": ["IAB1"],
        "content": {
            "title": "CTV Native Content",
            "cat": ["IAB1"],
            "genre": "Entertainment",
            "contentrating": "G",
            "context": 1,
            "livestream": 0
        }
    },
    "device": {
        "devicetype": 3,
        "make": "Generic",
        "model": "Smart TV",
        "os": "Android TV",
        "ua": "Mozilla/5.0 (Linux; Android 9; Android TV) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36",
        "ifa": "****",
        "ip": "****",
        "dnt": 0,
        "lmt": 0,
        "geo": { "city": "Los Angeles", "region": "CA", "country": "USA", "zip": "90210" }
    },
    "imp": [
        {
            "id": "impression-id-1234",
            "tagid": "****",
            "bidfloor": 5.0,
            "secure": 1,
            "native": {
                "ver": "1.2",
                "request": {
                    "ver": "1.2",
                    "context": 1,
                    "contextsubtype": 10,
                    "plcmttype": 1,
                    "plcmtcnt": 1,
                    "privacy": 1,
                    "aurlsupport": 0,
                    "eventtrackers": [ { "event": 1, "methods": [1] } ],
                    "assets": [
                        { "id": 128, "required": 0, "img": { "type": 3, "wmin": 1920, "hmin": 496 } },
                        { "id": 129, "required": 1, "video": {
                            "mimes": ["video/mp4"],
                            "minduration": 10,
                            "maxduration": 60,
                            "protocols": [1, 2, 3, 4, 5, 6, 7, 8]
                        } }
                    ]
                }
            }
        },
        {
            "id": "impression-id-5678",
            "tagid": "****",
            "bidfloor": 5.0,
            "secure": 1,
            "native": {
                "ver": "1.2",
                "request": {
                    "ver": "1.2",
                    "context": 1,
                    "contextsubtype": 10,
                    "plcmttype": 1,
                    "plcmtcnt": 1,
                    "privacy": 1,
                    "aurlsupport": 0,
                    "eventtrackers": [ { "event": 1, "methods": [1] } ],
                    "assets": [
                        { "id": 128, "required": 1, "img": { "type": 3, "wmin": 1920, "hmin": 496 } }
                    ]
                }
            }
        }
    ],
    "extension": {
        "supportedAdInteractions": [ "ClickToWeb", "ClickToVideo", "ClickToImage", "ClickToDeeplink" ]
    },
    "regs": { "ext": { "gdpr": 1, "us_privacy": "1---" } },
    "user": { "ext": { "consent": "****", "us_privacy": "1---" } },
    "source": { "tid": "ctv-native-transaction-id" }
}

Multiple impressions

A single bid-request can contain multiple impressions, depending on the number of available slots in a carousel. Here the request covers both video and image experiences, resulting in a separate impression for each asset type in the response.

Placeholder usage

The first impression is designed for a video asset. The secondary image asset serves as a placeholder, displayed while the video is loading to ensure a seamless user experience.

!
Request stringification. In this sample, the imp.native.request field is shown as readable, unescaped JSON for clarity. In production this field must be a properly stringified JSON object.
03 · Bid-response

Bid-response details.

The bid-response returned by Teads for the bid-request above — one bid per impression.

JSON · OpenRTB 2.6 · Bid-responseexpand
{
    "id": "bid-request-id-1234",
    "seatbid": [
        {
            "seat": "teads",
            "bid": [
                {
                    "adm": {
                        "ver": "1.2",
                        "impid": "impression-id-1234",
                        "price": 1234,
                        "assets": [
                            { "id": 128, "required": 0, "img": { "w": 1920, "h": 496, "url": "http://masthead.png" } },
                            { "id": 129, "required": 1, "video": {
                                "vasttag": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"3.0\">[...]</VAST>"
                            } }
                        ],
                        "link": {
                            "url": "https://teads.com",
                            "clicktrackers": [ "https://t.teads.tv/track?action=click" ]
                        },
                        "eventtrackers": []
                    }
                },
                {
                    "adm": {
                        "ver": "1.2",
                        "impid": "impression-id-5678",
                        "price": 1234,
                        "assets": [
                            { "id": 128, "required": 1, "img": { "w": 1920, "h": 496, "url": "http://masthead.png" } }
                        ],
                        "link": {
                            "url": "https://teads.com",
                            "clicktrackers": [ "https://t.teads.tv/track?action=click" ]
                        },
                        "eventtrackers": [
                            { "event": 1, "method": 1, "url": "https://t.teads.tv/track?action=impression" }
                        ]
                    }
                }
            ]
        }
    ]
}

Video events

The first impression represents a video experience, defined using an embedded VAST object (below). All video-related events, such as impression tracking and progression, are specified within the VAST structure.

Image events

The second impression delivers the requested image experience. Unlike video assets, images are not declared via VAST — their associated events, such as impression tracking, are specified in the eventtrackers field.

!
Adm stringification. The seatbid.bid.adm field is shown as readable, unescaped JSON for clarity. In production this field must be a properly stringified JSON object.

Embedded VAST for the video experience

XML · VAST 3.0 · Videoexpand
<?xml version="1.0" encoding="UTF-8"?>
<VAST version="3.0">
  <Ad id="****">
    <InLine>
      <AdSystem>Teads Technology</AdSystem>
      <AdTitle><![CDATA[Homescreen Video]]></AdTitle>
      <Error><![CDATA[https://t2.teads.tv/track?action=error-vast]]></Error>
      <Impression><![CDATA[https://t2.teads.tv/track?action=impression]]></Impression>
      <Creatives>
        <Creative adId="****" id="****">
          <Linear>
            <Duration>00:00:30</Duration>
            <TrackingEvents>
              <Tracking event="start"><![CDATA[https://t2.teads.tv/track?action=start]]></Tracking>
              <Tracking event="firstQuartile"><![CDATA[https://t2.teads.tv/track?action=firstQuartile]]></Tracking>
              <Tracking event="midpoint"><![CDATA[https://t2.teads.tv/track?action=midpoint]]></Tracking>
              <Tracking event="thirdQuartile"><![CDATA[https://t2.teads.tv/track?action=thirdQuartile]]></Tracking>
              <Tracking event="complete"><![CDATA[https://t2.teads.tv/track?action=complete]]></Tracking>
            </TrackingEvents>
            <VideoClicks>
              <ClickTracking><![CDATA[https://t2.teads.tv/track?action=click]]></ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile bitrate="816192" delivery="progressive" height="496" id="****"
                         maintainAspectRatio="true" scalable="true" type="video/mp4" width="1920">
                <![CDATA[http://masthead.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
      <Extensions>
        <Extension type="****"/>
      </Extensions>
    </InLine>
  </Ad>
</VAST>
04 · User interactions

Ad interactions.

The bid-response contains, in the adm.link.url field, a URL that defines one of the ad-interaction types below. The expected behavior upon a user click is:

Click to Web

Redirects the user to the advertiser's website.

ClickToWeb

Click to Image

Displays an image on the TV screen.

ClickToImage

Click to Video

Displays a video on the TV screen.

ClickToVideo

Click to Deeplink

Launches a specific application on the TV.

ClickToDeeplink

Declaring supported interactions

Platforms that do not support all interaction types must declare their supported interactions within the bid-request extension (root level):

JSON · Bid-request extension
{
    "ext": {
        "supportedAdInteractions": [
            "ClickToWeb",
            "ClickToVideo",
            "ClickToImage",
            "ClickToDeeplink"
        ]
    }
}
!
Notes. If the field is not set, we assume that all interactions are available. If the field is set to an empty array, no interactions are available.
05 · Brand safety

Creative approval — optional.

Teads offers an optional in-house creative-approval tool for brand-safety compliance. Assets can be reviewed through our proprietary system if required by platform guidelines or advertiser preferences. Creative delivery will not begin until assets have been validated.

06 · Onboarding

Additional questions.

To begin working together, here are some questions we would need to resolve:

  1. 1
    How many creative slots does your carousel contain, and what are the standard dimensions/formats supported?What is the display duration for each image experience in the carousel rotation?
  2. 2
    What are the technical constraints for video experiences (maximum duration, file-size limits, supported codecs)?
  3. 3
    How do you handle carousel rotation — do you cycle through the same content or trigger new bid-requests for fresh inventory?
  4. 4
    Do you implement any caching mechanisms on your platform, and if so, what are the cache duration / eviction policies?
  5. 5
    Are you VAST compliant? Which VAST events do you support? We support this exhaustive list: impression, start, firstQuartile, midpoint, thirdQuartile, complete, click.
  6. 6
    How do you handle video loading states? Do you display a default placeholder or require advertisers to provide loading assets?
  7. 7
    What targeting data is available in bid-requests (device.ip and device.geo fields)?
  8. 8
    How do you handle user consent management? Are you GDPR/CCPA compliant, and do you respect Do-Not-Track signals (device.dnt field)?
  9. 9
    What app-bundle-id will be passed (app.bundle field)?
  10. 10
    What are your QPS (Queries Per Second) capabilities and expected response timeouts?
  11. 11
    What types of ad interactions do you support?
07 · Integration roadmap

Integration steps.

The full integration roadmap — from technical alignment to global availability — is detailed in a dedicated document.

Roadmap

Standard integration timeline

Step-by-step onboarding: alignment, technical exchange, setup, device testing, test campaign, production and global availability.

View the integration steps