Deep Linking

How mobile deep linking works 🔗

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

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 🔗