Skip to content

Connected TV (CTV) Impressions ​

Report connected TV ad impressions from your server so Linkrunner can credit mobile installs from the same household

Use this when your ads play on connected TVs (smart TVs, streaming sticks, set-top boxes, game consoles) and the app is installed on a phone in the same home. This is CTV view-through attribution.

Your server reports each impression with the TV's IP address and user agent. If a phone on that home network installs and opens the app within the view-through window, and nothing else can be credited, Linkrunner credits your impression. Your install postback then carries {touch_type} = impression.

  • A TV ad has no click, and a TV's advertising ID never equals the phone's GAID or IDFA. The two share only the household's public IP address.
  • If your impressions carry the phone's GAID or IDFA, use S2S impressions instead. They match on the device ID and rank above CTV impressions.
  • Linkrunner accepts AppsFlyer's CTV parameter names. See Coming from AppsFlyer.

Before you start ​

CTV is off by default. The advertiser turns on three switches for your partner account, on each app. Changes take up to 5 minutes to apply.

SwitchWhere the advertiser turns it onRejection while off
S2S clicks and impressionsIntegrations → Affiliate Partners → Configurepartner_not_enabled
Connected TV (CTV) impressionsUnder the S2S switch, same page (steps)ctv_not_enabled
View-through, with its windowSettings → Attribution Windows (how)view_through_disabled

Send your advertiser the CTV attribution guide.

How it works ​

A CTV match is probabilistic. The same IP address suggests the same household, not the same person. Linkrunner credits a CTV impression only when all of these hold:

RuleDetail
Same IP addressThe phone installs from the public IP address the impression reported, in practice on the same home Wi-Fi as the TV. Installs over mobile data use the carrier's addresses and don't match.
Android and iOSInstalls on both platforms are credited.
Everything else winsAny click that can be credited, from any source, and any S2S impression matched on the device ID win over every CTV impression.
Inside the windowThe install happens within the view-through window the advertiser set for you: 1 to 24 hours, 24 by default. Your vt_lookback can shorten it, never lengthen it.
Latest impressionIf several impressions match, the most recent one inside its own window wins. Each impression is credited to at most one install.
Not a shared addressIf more than four installs of the app from one IP address in a day have no click or device-ID impression credited, Linkrunner treats it as a shared network (an office, a public hotspot) and stops crediting CTV impressions to its installs.

Postbacks work as for clicks. Your postback templates, event mapping and postback logs apply unchanged.

Set it up ​

Get your S2S token

If you already send S2S clicks or S2S impressions, use the same token and skip this step.

Otherwise, open Settings → S2S Credentials and click Generate token. It starts with lrs2s_ and is shown only once, so store it as a secret on your server. One token covers every app.

S2S Credentials with the Generate token button

Open the advertiser's app

Pick the advertiser's app in the switcher at the top left. Campaigns and the CTV setting are per app.

The app switcher open, with the advertiser's app under Projects and your partner account below it

Create the campaign link

In All Campaigns, click Create Link, name the CTV campaign and click Create Campaign. Other options are in Create a campaign link.

Create Campaign with a CTV campaign name filled in

Copy the CTV impression URL

Once the advertiser turns on CTV for you, your dashboard builds this URL. Copy the CTV impression URL from any of these:

  • The Campaign Created screen, next to the Template URL.
  • The TV icon in the campaign table.
  • The campaign details panel.
Campaign Created with the Template URL, View-through URL and CTV impression URL

It looks like this, plus your own s3 and s4 if your template has them:

https://s2s.linkrunner.io/v1/ctv/impression?d=<link domain>&c=<campaign code>&tid={impression_id}&s2={campaign_id}&ip={device_ip}&ua={device_ua}&impression_time={timestamp_ms}

Fill the macros

Replace each macro in braces with your own value:

  • ip and ua are required. ip is the TV's public IP address, not your ad server's. With server-side ad insertion, use the X-Device-IP and X-Device-User-Agent values your ad server received.
  • tid is your ID for this impression. Make it unique per impression.
  • impression_time is when the impression happened.

Fire it from your server when the ad plays

Call the URL with GET and your token in the X-Linkrunner-Token header. A 200 with "status":"accepted" means the impression is recorded. For other responses, see retries.

Send each impression as it happens. An impression that arrives after the install can't be credited, and impressions older than 24 hours are rejected.

Test it end to end

Send one impression with the public IP address of a test home network. On a phone on that Wi-Fi, install and open the app within the window, without tapping any ad. Check Postback logs for the install postback with your tid and {touch_type} = impression.

Build the URL by hand

Start from the Template URL on the Campaign Created screen, for example https://app.example.com/?c=OgWmhiSXhG&tid={click_id}&s2={campaign_id}. Send its parameters to https://s2s.linkrunner.io/v1/ctv/impression/<app_id> and add ip, ua and impression_time:

http
GET https://s2s.linkrunner.io/v1/ctv/impression/com.example.app?c=OgWmhiSXhG&tid={impression_id}&ip={device_ip}&ua={device_ua}&impression_time={timestamp_ms}&source_platform={platform}
X-Linkrunner-Token: <your_token>
  • <app_id> is the Android package name (com.example.app) or App Store ID (id1234567890). Either finds the same app, and both its Android and iOS installs are matched.
  • Or use the tracking link's domain: https://s2s.linkrunner.io/v1/ctv/impression?d=app.example.com&c=.... Use d if the advertiser's test and live apps share an app ID and the same campaign code.

See your results ​

In the campaign table, CTV installs count under Installs and View Through Attribution. Accepted impressions appear in the Impressions column, which is off by default. Turn it on once per app and it stays on:

  1. In All Campaigns, click the columns icon at the right of the toolbar, below Create Link.

    The Edit Columns icon at the right of the campaign toolbar, below Create Link

  2. Tick Impressions and click Save. Keep View Through Attribution ticked as well.

    Edit Columns with Impressions ticked and the Save button at the top

Campaign table with Impressions, Installs and View Through Attribution for two CTV campaigns and one click campaign

  • A TV-only campaign has no clicks.
  • A new campaign can show impressions before its first install. Installs count on the day they happen, so a household that saw the ad late at night can install the next day.
  • A TV impression belongs to neither Android nor iOS. A view filtered to one platform hides CTV impressions but still shows that platform's credited installs. Clear the filter to see them.

Authenticate your requests ​

Use the same partner token as S2S impressions. Send it in the X-Linkrunner-Token header, or as the lr_token query parameter if your ad server can only fire a URL. Without a valid token, the request is rejected with 401 and missing_token or invalid_token. The API reference has cURL, Node.js and Python examples.

Coming from AppsFlyer ​

You can reuse your AppsFlyer cross-platform CTV template. Change the host and c, add a unique tid, and add your token.

AppsFlyerLinkrunnerNotes
impressions.onelink.me/<template_id>s2s.linkrunner.io/v1/ctv/impression/<app_id>Linkrunner uses the Android package name or App Store ID, not a OneLink template
c (campaign name)c (campaign code)Use the c value from your Linkrunner tracking link, not a campaign name
tid (or clickid)Required. Send a unique ID per impression
af_ipipEither name works. Required
af_uauaEither name works. Required
af_xplatform_vt_lookbackvt_lookbackWorks as is. 1h to 24h, or 1d. Longer values are capped at 24 hours. af_viewthrough_lookback also works
af_c_id, af_adset_id, af_ad_id, af_siteid, af_source_platform, af_source_device_categorypartner_campaign_id, adset_id, ad_id, site_id, source_platform, device_categoryEither name works. Stored with the impression
af_sub1, af_sub2, af_sub3s2, s3, s4Either name works. Returned in {s2} to {s4}
pid, af_xplatform, redirectNot neededIgnored if present

For example, the first template becomes the second, with your token in the X-Linkrunner-Token header:

https://impressions.onelink.me/AbCd?pid=xyz_int&c=summer&af_xplatform=true&af_xplatform_vt_lookback=24h&af_ip={ip}&af_ua={ua}&af_siteid={site}&redirect=false
https://s2s.linkrunner.io/v1/ctv/impression/com.example.app?c=OgWmhiSXhG&tid={impression_id}&af_xplatform=true&af_xplatform_vt_lookback=24h&af_ip={ip}&af_ua={ua}&af_siteid={site}

Retries ​

Retrying is safe. The same tid for the same campaign always returns the same impression_id and is stored once.

  • Retry 429 and 503, after the Retry-After delay.
  • Don't retry other 4xx responses. Fix the request instead. The reason tells you what's wrong.

The CTV Impression API reference lists every parameter, response and rejection reason.

Troubleshooting ​

Response or symptomWhat to do
missing_ip, invalid_ip, datacenter_ip, missing_uaSend the TV's own public IP address and user agent, not your ad server's. Private (192.168.x.x, 10.x.x.x), carrier-grade NAT (100.64.0.0/10), loopback and cloud or hosting addresses are rejected.
partner_not_enabled, ctv_not_enabled, view_through_disabledAsk the advertiser to turn on the missing switch. See Before you start.
Accepted, but no installs creditedCheck each rule in How it works, and that the impression arrived before the install.

Need help? Contact support@linkrunner.io

Need help? Contact support@linkrunner.io