Appearance
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.
| Switch | Where the advertiser turns it on | Rejection while off |
|---|---|---|
| S2S clicks and impressions | Integrations → Affiliate Partners → Configure | partner_not_enabled |
| Connected TV (CTV) impressions | Under the S2S switch, same page (steps) | ctv_not_enabled |
| View-through, with its window | Settings → 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:
| Rule | Detail |
|---|---|
| Same IP address | The 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 iOS | Installs on both platforms are credited. |
| Everything else wins | Any click that can be credited, from any source, and any S2S impression matched on the device ID win over every CTV impression. |
| Inside the window | The 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 impression | If several impressions match, the most recent one inside its own window wins. Each impression is credited to at most one install. |
| Not a shared address | If 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.

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.

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.

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.

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:
ipanduaare required.ipis the TV's public IP address, not your ad server's. With server-side ad insertion, use theX-Device-IPandX-Device-User-Agentvalues your ad server received.tidis your ID for this impression. Make it unique per impression.impression_timeis 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=.... Usedif 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:
In All Campaigns, click the columns icon at the right of the toolbar, below Create Link.

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


- 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.
| AppsFlyer | Linkrunner | Notes |
|---|---|---|
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_ip | ip | Either name works. Required |
af_ua | ua | Either name works. Required |
af_xplatform_vt_lookback | vt_lookback | Works 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_category | partner_campaign_id, adset_id, ad_id, site_id, source_platform, device_category | Either name works. Stored with the impression |
af_sub1, af_sub2, af_sub3 | s2, s3, s4 | Either name works. Returned in {s2} to {s4} |
pid, af_xplatform, redirect | Not needed | Ignored 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
429and503, after theRetry-Afterdelay. - Don't retry other
4xxresponses. Fix the request instead. Thereasontells you what's wrong.
The CTV Impression API reference lists every parameter, response and rejection reason.
Troubleshooting
| Response or symptom | What to do |
|---|---|
missing_ip, invalid_ip, datacenter_ip, missing_ua | Send 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_disabled | Ask the advertiser to turn on the missing switch. See Before you start. |
| Accepted, but no installs credited | Check each rule in How it works, and that the impression arrived before the install. |
Need help? Contact support@linkrunner.io