Teads · Technical Documentation

CTV Homescreen VAST Integration.

The process to make an ad-request to the Teads SSP for a CTV Homescreen VAST integration. Teads responds with a VAST 3.0 document for both the video and display experiences.

Download PDF

01 · Formats

Supported 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 · Ad request

Supply-tag reference.

Make the ad-request by calling the Teads supply-tag URL with the macros below resolved to their runtime values.

Supply-tag URL

https://a.teads.tv/ctv-native-vast/{{PARTNER_NAME}}/{{PLACEMENT_ID}}
    ?appId={{BUNDLE_ID}}
    &userId={{USER_ID}}
    &ip={{IP}}
    &playerHeight={{PLAYER_HEIGHT}}
    &playerWidth={{PLAYER_WIDTH}}
    &dnt={{DNT}}
    &country={{COUNTRY_CODE}}
    &adslot={{AD_SLOT}}
    &lmt={{LMT}}
    &opt_in={{OPT_IN}}
    &language={{LANGUAGE}}
    &gdpr={{GDPR}}
    &gdpr_consent={{GDPR_CONSENT}}

Field	Description	Type	Note
`{{PARTNER_NAME}}`	Teads partner name	string	Provided by Teads
`{{PLACEMENT_ID}} *`	Teads placement identifier	number	Provided by Teads, per country
`{{BUNDLE_ID}}`	ID of the app on the platform that distributes it	string	—
`{{USER_ID}}`	User identifier	uuid	—
`{{PLAYER_HEIGHT}}`	Ad height requested	int	e.g. 496
`{{PLAYER_WIDTH}}`	Ad width requested	int	e.g. 1920
`{{DNT}}`	Do Not Track — chosen by user	0 or 1	—
`{{COUNTRY_CODE}}`	Device country	string	Three-letter code, e.g. USA (Alpha-3)
`{{AD_SLOT}}`	Placement name	string	URL-encoded version of adslot
`{{LMT}}`	Limit Tracking — chosen by user	0 or 1	1 = LMT, 0 = No LMT
`{{OPT_IN}}`	Opt-in — chosen by user	0 or 1	—
`{{IP}}`	Device IP address	string	—
`{{LANGUAGE}}`	Device language	string	e.g. en-US
`{{GDPR}}`	GDPR enabled	0 or 1	If applicable
`{{GDPR_CONSENT}}`	GDPR consent string	string	If applicable

* PLACEMENT_ID may differ per country — you must be able to send it per country.

Request URL examples

Without GDPR

https://a.teads.tv/ctv-native-vast/myPartnerName/444444
    ?playerWidth=1920&playerHeight=496&ip=203.0.113.33&dnt=0
    &country=AUS&userId=11111111-1111-1111-1111-111111111111
    &adslot=Portal%2FHome&lmt=0&opt_in=true

With GDPR

https://a.teads.tv/ctv-native-vast/myPartnerName/123456
    ?playerWidth=1920&playerHeight=496&ip=203.0.113.31&dnt=0
    &country=AUS&userId=22222222-2222-2222-2222-222222222222
    &adslot=Portal%2FHome&lmt=0&opt_in=true&language=en-US
    &gdpr=1&gdpr_consent=CQZR7kAQ...

03 · Response

Sample response.

Teads responds with a VAST 3.0 document. For video, the asset URL is placed in the <MediaFiles> node as a <MediaFile>. For display images, the asset is placed in the <CompanionAds> node as a <Companion>.

Video response — <MediaFile>

XML · VAST 3.0 · Videoexpand

<VAST version="3.0">
  <Ad id="****">
    <InLine>
      <AdSystem>Teads Technology</AdSystem>
      <AdTitle><![CDATA[ CTV 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 id="****" adId="****">
          <Linear>
            <Duration>00:00:20</Duration>
            <TrackingEvents>
              <Tracking event="start"><![CDATA[ https://t2.teads.tv/track?action=start&... ]]></Tracking>
              <Tracking event="firstQuartile"><![CDATA[ ... ]]></Tracking>
              <Tracking event="midpoint"><![CDATA[ ... ]]></Tracking>
              <Tracking event="thirdQuartile"><![CDATA[ ... ]]></Tracking>
              <Tracking event="complete"><![CDATA[ ... ]]></Tracking>
              <!-- + mute, unmute, pause, rewind, resume, expand, collapse, close, skip -->
            </TrackingEvents>
            <VideoClicks>
              <ClickThrough><![CDATA[ https://www.myWebsite.com ]]></ClickThrough>
              <ClickTracking><![CDATA[ https://t2.teads.tv/track?action=click&... ]]></ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4" width="1920" height="496">
                <![CDATA[ https://static.teads.tv/ctv-native-assets/.../MastheadVideo-1920x496.MP4 ]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Image response — <CompanionAds>

XML · VAST 3.0 · Displayexpand

<VAST version="3.0">
  <Ad id="****">
    <InLine>
      <AdSystem>Teads Technology</AdSystem>
      <AdTitle><![CDATA[ CTV Homescreen Display ]]></AdTitle>
      <Error><![CDATA[ https://t2.teads.tv/track?action=error-vast&gid=****&code=[ERRORCODE]&... ]]></Error>
      <Impression><![CDATA[ https://t2.teads.tv/track?action=impression&gid=****&... ]]></Impression>
      <Impression><![CDATA[ https://ad.doubleclick.net/ddm/trackimp/...;gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_755};... ]]></Impression>
      <Impression><![CDATA[ https://pixel.adsafeprotected.com/rfw/st/.../skeleton.gif?gdpr=${GDPR}&... ]]></Impression>
      <Creatives>
        <Creative id="****" adId="****">
          <Linear>
            <Duration>00:00:30</Duration>
            <TrackingEvents>
              <Tracking event="start"><![CDATA[ https://t2.teads.tv/track?action=start&gid=****&... ]]></Tracking>
              <Tracking event="firstQuartile"><![CDATA[ ... ]]></Tracking>
              <Tracking event="midpoint"><![CDATA[ ... ]]></Tracking>
              <Tracking event="thirdQuartile"><![CDATA[ ... ]]></Tracking>
              <Tracking event="complete"><![CDATA[ ... ]]></Tracking>
            </TrackingEvents>
            <VideoClicks>
              <ClickThrough><![CDATA[ ?appGroupId=youtube&contentTarget=... ]]></ClickThrough>
              <ClickTracking><![CDATA[ https://t2.teads.tv/track?action=click&... ]]></ClickTracking>
              <ClickTracking><![CDATA[ https://ad.doubleclick.net/ddm/trackclk/... ]]></ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" type="" width="0" height="0"><![CDATA[ ]]></MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
        <Creative>
          <CompanionAds>
            <Companion width="1920" height="496">
              <StaticResource creativeType="image/jpeg">
                <![CDATA[ https://static.teads.tv/ctv-native-assets/.../MastheadDisplay-1920x496.jpg ]]>
              </StaticResource>
              <CompanionClickThrough><![CDATA[ ?appGroupId=youtube&contentTarget=... ]]></CompanionClickThrough>
              <CompanionClickTracking><![CDATA[ https://t2.teads.tv/track?action=click&... ]]></CompanionClickTracking>
              <CompanionClickTracking><![CDATA[ https://ad.doubleclick.net/ddm/trackclk/... ]]></CompanionClickTracking>
            </Companion>
          </CompanionAds>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

04 · User interactions

Call to actions.

Set the <ClickThrough> value according to the expected behavior upon a user click.

Click to Web

Redirects the user to the advertiser's website.

<ClickThrough><![CDATA[ https://www.placeholder.com ]]></ClickThrough>

Click to Video

Displays a video on the TV screen.

<ClickThrough><![CDATA[ https://www.partner.com/creative.mp4 ]]></ClickThrough>

Click to Image

Displays an image on the TV screen.

<ClickThrough><![CDATA[ https://www.partner.com/creative.jpeg ]]></ClickThrough>

Click to Deeplink

Launches a specific application on the TV.

?appGroupId=<appGroupId>&contentTarget=<contentTarget>

Supported deeplink apps

YouTubeYouTube TVApple TVAmazon PrimeDisney+

Deeplink format. Use URL-encoded values for both appGroupId and contentTarget. Example: ?appGroupId=youtube&contentTarget=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DMtsgjlE-LHg

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 · 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