Deep Linking

How mobile deep linking works 🔗

There are three distinct scenarios. Getting both right is what “deep linking” actually means in practice.

Deeplink Ext 🔗

Improved customer experience for e-commerce campaigns. When a user clicks on an ad, the user is deeplinked directly into the retailer’s app or gracefully fallsback to the app store download page.

Bid Request Parameters 🔗

The extension deeplink and fallback feature will be sent together where supported by Chartboost SDKs.

Bid Request Example:

"ext":
{    
  "deeplink": 1,
  "fallback": 1
}

Bid Response Parameters 🔗

The extension deeplink and fallback urls will utilized prioritized above any creative click through upon user interaction with the ad.

Recommended Both deeplink and fallback params are required for Deeplink function as designed. If any of these fields are missing, the Deeplink workflow will attempt deeplink, fallback and creative click throughs in that ordering. For the best user experience, provide both a deeplink and a fallback url.

Bid Response Example:

"seatbid": [
  {
    "bid": [
      {
        "ext": {
          "deeplink": "deeplinkURL",
          "fallback": "fallbackURL"
        }
      }
    ]
  }
]

Direct deep link (app already installed) 🔗

The user taps the ad, the app is already on the device, and it opens directly on a specific screen — for example a product page, a promo, or a saved cart — instead of the generic home screen. This is driven by a URI the OS knows how to route to the app, e.g. a custom scheme or a Universal/App Link.

myapp://product/12345  
https://www.brand.com/product/12345   (Universal Link / App Link)

Deferred deep link (app NOT installed) 🔗

The user taps the ad, does not have the app, is sent to the App Store / Google Play to install, and on first open is routed to the same intended screen. The intended destination has to “survive” the install — the app store strips the original link, so something has to remember where the user was supposed to go. That “something” is the MMP.

Where the MMP (AppsFlyer) fits in 🔗

An MMP like AppsFlyer sits in the middle of the click. Instead of pointing your creative straight at myapp://product/12345, you point it at an AppsFlyer OneLink / attribution (click) URL. OneLink is a single link that does three jobs at once:

• Routing decision — on tap, AppsFlyer checks the device and app-install status and decides whether to open the app directly, defer through the store, or fall back to a web page.

• Carries the destination — the intended in-app screen travels inside the link as parameters (e.g. af_dp, deep_link_value) and is preserved through the store install so the SDK can deliver it on first open.

• Attribution — the same click is recorded for attribution, tying the install and the in-app event back to your campaign, creative and publisher. One integration, one source of truth.

So the rule of thumb for a DSP is: you pass the AppsFlyer click URL as the click-through, not the raw app URI. AppsFlyer resolves the rest. The raw URI is embedded inside that AppsFlyer link via af_dp / deep_link_value.

The AppsFlyer OneLink, decoded 🔗

A OneLink click URL has a fixed shape: a OneLink subdomain + template ID, followed by query parameters. The parameters fall into three groups — deep-link destination, routing/fallback, and attribution/macros.

https://onelink-subdomain.onelink.me/ABcd?
    pid=loopme_int               // media source (partner id)
    &c=summer_sale               // campaign name
    &af_dp=myapp%3A%2F%2Fproduct%2F12345          // deep link URI (installed users)
    &deep_link_value=product_12345                // destination key (deferred / UDL)
    &deep_link_sub1=US&deep_link_sub2=banner      // extra context (optional)
    &af_web_dp=https%3A%2F%2Fbrand.com%2Fp%2F12345 // web fallback
    &clickid=CB-{AUCTION_ID}     // your unique click id (dedupe / postbacks)
    &idfa={IDFA}&advertising_id={GAID}            // device id macros

Deep-link destination parameters 🔗

Attribution & macro parameters 🔗

These tie the click to your campaign. The Chartboost and LoopMe exchanges substitutes its macros into the URL at serve time; AppsFlyer substitutes its own user-level values. Always supply a unique clickid so clicks can be de-duplicated and matched to postbacks.

Note: exact macro tokens (e.g. {AUCTION_ID}, {APP_BUNDLE}) are defined by the Chartboost exchange spec. Confirm the current token list with your LoopMe/Chartboost integration contact before going live.

Passing the deep link through the Chartboost SDK 🔗

Key fact: the Chartboost OpenRTB 2.6 bid response has no dedicated deep-link field (there is no seatbid.bid.ext.deeplink). The deep link is delivered the same way as any click destination — it lives in the click-through of the ad markup (adm). The Chartboost SDK opens whatever click-through URL the creative carries; if that URL is your AppsFlyer OneLink, deep linking and deferred deep linking work automatically.

Therefore the deep link = the AppsFlyer click URL placed in the click-through of your **adm. Build the OneLink, URL-encode it, and drop it into the correct click-through slot for the creative type.

Where the click-through lives, by creative type 🔗

Example — HTML / MRAID bid response 🔗

The OneLink sits in the <a href>. Everything else is a standard Chartboost banner/MRAID response.

{
  "id": "9d55...", "cur": "USD",
  "seatbid": [{ "seat": "loopme_dsp", "bid": [{
    "id": "rtb-9d55...",
    "impid": "05f23...",            // must match imp.id
    "price": 15.26,
    "adomain": ["brand.com"],
    "bundle": "123456789",          // advertised app store id / package
    "crid": "loopme:dl_12345",
    "mtype": 1,
    "burl": "https://track.loopme.com/imp?ai=${AUCTION_ID}&p=${AUCTION_PRICE}",
    "adm": "<!DOCTYPE html><html><body>
       <a href=\"https://brand.onelink.me/ABcd?pid=loopme_int
          &c=summer_sale&af_dp=myapp%3A%2F%2Fproduct%2F12345
          &deep_link_value=product_12345
          &af_web_dp=https%3A%2F%2Fbrand.com%2Fp%2F12345
          &clickid=CB-${AUCTION_ID}&advertising_id=${GAID}\">
          <img src=\"https://cdn.brand.com/ad.jpg\"/></a>
       </body></html>",
    "ext": { "crtype": "MRAID 2.0",
             "imptrackers": ["https://track.loopme.com/imp?..."] }
  }]}]
}

4.3 Example — VAST video bid response 🔗

The OneLink goes in <ClickThrough> (and, if there is an end card, in <CompanionClickThrough>). URL-encode the link inside the CDATA.

<VAST version="3.0"><Ad><InLine>
  <AdSystem>LoopMe</AdSystem><AdTitle>summer_sale</AdTitle>
  <Impression><![CDATA[https://track.loopme.com/imp?...]]></Impression>
  <Creatives><Creative><Linear>
    <Duration>00:00:15</Duration>
    <MediaFiles><MediaFile type="video/mp4" delivery="progressive"
       width="568" height="320"><![CDATA[https://cdn/video.mp4]]>
    </MediaFile></MediaFiles>
    <VideoClicks>
      <ClickThrough><![CDATA[https://brand.onelink.me/ABcd?pid=loopme_int
        &c=summer_sale&af_dp=myapp%3A%2F%2Fproduct%2F12345
        &deep_link_value=product_12345
        &af_web_dp=https%3A%2F%2Fbrand.com%2Fp%2F12345
        &clickid=CB-${AUCTION_ID}]]></ClickThrough>
    </VideoClicks>
  </Linear></Creative></Creatives>
</InLine></Ad></VAST>

Step-by-step integration checklist 🔗

1. Get the OneLink template from the advertiser/MMP. The advertiser sets up the OneLink in AppsFlyer and shares the subdomain + template ID and the agreed pid for your traffic.

2. Build the deep-link destination. Encode the app URI into af_dp and set deep_link_value (+ any deep_link_sub*). Add af_web_dp as a web fallback.

3. Append attribution + macros. Add pid, c, clickid, device-ID and exchange macros.

4. URL-encode the whole OneLink before embedding it in the creative (double-check the encoding when it is nested inside JSON or CDATA).

5. Place it in the click-through for the creative type: <a href> / mraid.open for HTML-MRAID, <ClickThrough> for VAST.

6. Set the required bid fields Chartboost expects: id, impid, price, adomain, crid, bundle, mtype, ext.crtype, plus burl or ext.imptrackers for impression tracking.

7. Test both paths: app installed = direct deep link; app not installed = store then deferred deep link on first open.

Testing & validation 🔗

• Installed-user (direct) test: with the advertised app installed, tap the creative in a Chartboost test placement — the app must open on the target screen, not the home screen.

• Deferred test: uninstall the app, tap the creative, install from the store, open the app — first launch must land on the same target screen.

• Attribution check: confirm the click and install appear in AppsFlyer attributed to pid=loopme_int with your clickid and campaign.

• Encoding check: decode the click-through URL from the live adm and confirm af_dp / deep_link_value survived JSON/CDATA nesting intact.

• Fallback check: on a device/OS where the app can’t open, confirm the user lands on af_web_dp rather than a dead screen.

Common mistakes to avoid 🔗