Deep-Linking

Deep Link+ provides a premium user experience while letting advertisers scale retargeting campaigns with accurate analytics. The new deeplinking format enables buyers to submit a primary URL, fallback URL, primary tracking URL, and fallback tracking URL. And since Deep Link+ is built into the SDK, there is no need to pop up browser windows and re-directs that deteriorate the user experience.

Deep-Linking FAQ

1. What is deep-linking?

Deep-links are a way of navigating between apps. On desktop/mobile web, we have URLs. However, these do not exist for mobile apps. So, in order to make their apps accessible from other apps or mobile websites, developers have created deep-links.

2. Does MoPub support deep-linking in their SDKs?

Yes, the vast majority of MoPub inventory supports deep-linking or Deep Link+. See section 3 for details.

MoPub SDK versions 3.9+ now support Deep Link+, a new scheme that enables buyers to supply a retargeting deeplink and a fallback URL if the app is not installed.

Marketplace buyers must be integrated with MoPub’s OpenRTB 2.3 spec in order to leverage Deep Link+.

Server-to-Server partners can target the request ‘displaymanagerver’ to leverage Deep Link+.

3. Which MoPub iOS & Android SDK versions support deep-linking?

  • iOS: SDK versions 1.2.0.0+
  • Android: SDK versions 1.17.0.0+
  • Deep Link+ is supported in SDK version 3.9+

4. How do DSPs generally implement deep-linking/failover logic?

Deep Link+ enables buyers to leverage a specific scheme to implement deep-linking and failover logic:

The new URLs will have the following format:

deeplink+://navigate?
    primaryUrl=PRIMARY_DEEPLINK&
    primaryTrackingUrl=PRIMARY_TRACKER&
    fallbackUrl=FALLBACK_URL
    &fallbackTrackingUrl=FALLBACK_TRACKER

The only required parameter is primaryUrl and if it’s the only one, it would be handled as existing deeplink URLs: doing nothing if the app is missing.

The fallbackUrl can be any supported URI type (e.g., http, traditional deeplink) except for another Deep Link+ URL. To specify multiple tracker URLs (primary or fallback), buyers simply need to repeat the tracker key with any desired tracker URLs. The primaryTrackingURL will be fired if the deeplink is successful (which will be after the user clicks).

For example, here is a Deep Link+ URL whose primary target is the Twitter app, with two (2) primary tracker URLs, a fallback URL directing the user to Twitter’s mobile website if the primary deeplink fails and zero (0) fallback URLs:

deeplink+://navigate?
    primaryUrl=twitter%3A%2F%2Ftimeline&
    primaryTrackingUrl=http%3A%2F%2Fmopub.com%2Fclicktracking&
    primaryTrackingUrl=http%3A%2F%2Fmopub.com%2Fmopubtracking&
    fallbackUrl=http%3A%2F%2Fmobile.twitter.com

For native ads, all demand partners will be able to use Deep Link+ URLs as the main URL in the JSON response on publishers using SDK 3.9+.

  • NOTE: the URL must be properly URL encoded in order for Deep Link+ to work correctly. URLs that are not properly encoded will not work correctly.

In older versions of the SDK, the most standard way to make the deep-link + failover combination work is to use the following path on iOS:

Deeplink flowchart

The above works consistently on iOS. However, this flow isn’t supported explicitly by the Android platform, so DSPs are responsible for making this work and testing.

5. Does MoPub explicitly support deep-linking fallback?

Deep Link+ enables buyers to insert a fallback URL directly in the scheme.

In older versions of the SDK, you will need to ensure your tag supports fallback properly so that if the user clicks on the ad and the app is not installed on the device, the landing page will redirect the user to the appropriate app store.

6. What exactly does MoPub support in terms of deep-linking?

Deep Link+ enables buyers to insert a primary URL and a fallback URL. Additionally, buyers can provide primary tracking URL(s) and fallback tracking URL(s) to monitor which destination the user was actually taken to.

For non-Deep Link+ cases, the MoPub SDK is only responsible for supporting deep-link functionality. This means that if the click URL is a deep-link, our SDK will correctly attempt to take the user to the application. Responsibility for validating the failover and associated JavaScript rests on the DSP. Troubleshooting of the deep-link beyond the “user click” rests on the DSP.

You can test your tags using our SimpleAdsDemo Sample app.

Technology has traditionally failed in providing the ideal user experience — as processing traditional deep-links requires opening up blank browser windows, redirecting users multiple times, and sometimes breaking down completely. Additionally, buyers would lack analytics around when primary URLs worked versus when fallback URLs were required.

Deep Link+ provides a premium user experience while letting advertisers scale retargeting campaigns with accurate analytics. The new deeplinking format enables buyers to submit a primary URL, fallback URL, primary tracking URL, and fallback tracking URL. And since Deep Link+ is built into the SDK, there is no need to pop up browser windows and re-directs that deteriorate the user experience.

The only exception is that non-native ads on Android with Deep Link+ will still require a browser window to open.

  • Marketplace Buyers must be integrated with MoPub’s OpenRTB 2.3 spec in order to leverage Deep Link+. Reference the OpenRTB 2.3 spec for information on how to target inventory supporting Deep Link+
  • Server-to-server partners can target the request imp.banner.displaymanagerver field, which sends the MoPub SDK version field, to leverage Deep Link+. The value must be 3.9+.
  • As with any URL, each parameter value will have to be URL properly- encoded to avoid escaping to the next value. Improperly encoded URLs will fail.
  • The fallback cannot be another Deep Link+ URL per MoPub policy. This is in place to prevent malicious behavior. Note: we recommend the fallback URL linking to an app download page or website, as the creative will not go anywhere if both primary and fallback URLs fail.
  • Deep Link+ will not work with the mopubnativebrowser (That is, mopubnativebrowser://navigate?url=Deep Link+:// will not work)
  • The Deep Link+ scheme can be returned at the end of a redirect chain, so a buyer can use a standard click URL that redirects through their servers and returns a Deep Link+ scheme in the 302 or window.location redirect

10. When does a browser window open?

If the buyer places the Deep Link+ scheme directly as the click target for the ad, no web browsers will be opened, except to open the fallback destination, if that’s a web page.

If the advertiser uses a standard link as the click target and then redirects to Deep Link+, the behavior is as follows:

  • iOS:
    • 302 redirect to Deep Link+: no empty browser windows open (preferred way for integrating with redirect)
    • window.location or other javascript redirect: Not supported on iOS
  • Android:
    • 302 redirect to Deep Link+: empty browser windows opens briefly and closes for non-native ads. Native ads do not flash window. (preferred way for integrating with redirect)
    • window.location or other javascript redirect: empty browser windows opens briefly and closes for non-native ads. Native ads do not flash window.
{
    "bidid": "abc1234",
    "cur": "USD",
    "id": "1234567890",
    "seatbid": [{
        "seat": "xyz123456",
        "bid": [{
            "ext": {
                "duration": 30,
                "crtype": "VAST 2.0",
                "imptrackers": [
                    "http://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
                    "http://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
                ],
                "nurls": [
                    "http://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
                    "http://nurl2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
                ]
            },
            "id": "12345678",
            "adid": "314",
            "cat": [
                "IAB1-6"
            ],
            "adm": "<VAST version=\"2.0\">   <Ad id=\"2049384\">      <InLine>         <AdSystem>Advertiser</AdSystem>         <AdTitle>Advertiser||CPM|1x1|RON|CT|||A35-64|Tab|V|D|P|Tablet Pre-roll ShareGraph-BizNwsFi</AdTitle>         <Impression><![CDATA[http://rcdna.gwallet.com/default/0.gif]]></Impression>         <Impression><![CDATA[http://ad.mopub.net/ad/N6036.287481.mopub.COM/B8089590.4;sz=1x1;kw=guestexperience;ord=1399664690999?]]></Impression>         <Creatives>            <Creative id=\"340991\">               <Linear>                  <Duration>00:00:30</Duration>                  <TrackingEvents>                     <Tracking event=\"start\"><![CDATA[http://ru.gwallet.com/r1/vastp/.4gugofxbz353djo9bnmjfmizzncp993kapqwt675bcuubyi881srknoacmb6jur5j5bx6qtwsyehkqmma6m9amhxe84wdurr57rcep869qe8gixiyz71n4ppkqokw7xk7nrhu7skby1tiyfnc1dttztah6s6nf8xiikabgwkyn7p3x1oan3ghmqt95pme9xd9rk7deb74zxqa8upepbqczwjhco8u6yew3qgjewihofsgw1y7jyqi1rppwoyjiuyi76yxjkab6qf7pzqup83gu6x87nxc66dhn3zugwox1wdaimgoxjcnqzzn3t1sjfhn7ge1dcrz1depco1zj7iiqj6bmr6sry4gwxi9imyh4fpkpkt41jo55cj3ppcgn3m/b2049384c340991S15t1]]></Tracking>                     <Tracking event=\"firstQuartile\"><![CDATA[http://ru.gwallet.com/r1/vastp/.4gugofxbz353djo9bnmjfmizzncp993kapqwt675bcuubyi881srknoacmb6jur5j5bx6qtwsyehkqmma6m9amhxe84wdurr57rcep869qe8gixiyz71n4ppkqokw7xk7nrhu7skby1tiyfnc1dttztah6s6nf8xiikabgwkyn7p3x1oan3ghmqt95pme9xd9rk7deb74zxqa8upepbqczwjhco8u6yew3qgjewihofsgw1y7jyqi1rppwoyjiuyi76yxjkab6qf7pzqup83gu6x87nxc66dhn3zugwox1wdaimgoxjcnqzzn3t1sjfhn7ge1dcrz1depco1zj7iiqj6bmr6sry4gwxi9imyh4fpkpkt41jo55cj3ppcgn3m/b2049384c340991S15t2]]></Tracking>                     <Tracking event=\"midpoint\"><![CDATA[http://ru.gwallet.com/r1/vastp/.4gugofxbz353djo9bnmjfmizzncp993kapqwt675bcuubyi881srknoacmb6jur5j5bx6qtwsyehkqmma6m9amhxe84wdurr57rcep869qe8gixiyz71n4ppkqokw7xk7nrhu7skby1tiyfnc1dttztah6s6nf8xiikabgwkyn7p3x1oan3ghmqt95pme9xd9rk7deb74zxqa8upepbqczwjhco8u6yew3qgjewihofsgw1y7jyqi1rppwoyjiuyi76yxjkab6qf7pzqup83gu6x87nxc66dhn3zugwox1wdaimgoxjcnqzzn3t1sjfhn7ge1dcrz1depco1zj7iiqj6bmr6sry4gwxi9imyh4fpkpkt41jo55cj3ppcgn3m/b2049384c340991S15t3]]></Tracking>                     <Tracking event=\"thirdQuartile\"><![CDATA[http://ru.gwallet.com/r1/vastp/.4gugofxbz353djo9bnmjfmizzncp993kapqwt675bcuubyi881srknoacmb6jur5j5bx6qtwsyehkqmma6m9amhxe84wdurr57rcep869qe8gixiyz71n4ppkqokw7xk7nrhu7skby1tiyfnc1dttztah6s6nf8xiikabgwkyn7p3x1oan3ghmqt95pme9xd9rk7deb74zxqa8upepbqczwjhco8u6yew3qgjewihofsgw1y7jyqi1rppwoyjiuyi76yxjkab6qf7pzqup83gu6x87nxc66dhn3zugwox1wdaimgoxjcnqzzn3t1sjfhn7ge1dcrz1depco1zj7iiqj6bmr6sry4gwxi9imyh4fpkpkt41jo55cj3ppcgn3m/b2049384c340991S15t4]]></Tracking>                     <Tracking event=\"complete\"><![CDATA[http://ru.gwallet.com/r1/vastp/.4gugofxbz353djo9bnmjfmizzncp993kapqwt675bcuubyi881srknoacmb6jur5j5bx6qtwsyehkqmma6m9amhxe84wdurr57rcep869qe8gixiyz71n4ppkqokw7xk7nrhu7skby1tiyfnc1dttztah6s6nf8xiikabgwkyn7p3x1oan3ghmqt95pme9xd9rk7deb74zxqa8upepbqczwjhco8u6yew3qgjewihofsgw1y7jyqi1rppwoyjiuyi76yxjkab6qf7pzqup83gu6x87nxc66dhn3zugwox1wdaimgoxjcnqzzn3t1sjfhn7ge1dcrz1depco1zj7iiqj6bmr6sry4gwxi9imyh4fpkpkt41jo55cj3ppcgn3m/b2049384c340991S15t5]]></Tracking>                  </TrackingEvents>                  <VideoClicks>                     <ClickThrough><![CDATA[deeplink+://navigate?primaryUrl=twitter%3A%2F%2Ftimeline&primaryTrackingUrl=http%3A%2F%2Fmopub.com%2Fclicktracking&primaryTrackingUrl=http%3A%2F%2Fmopub.com%2Fmopubtracking&fallbackUrl=http%3A%2F%2Fmobile.twitter.com]]></ClickThrough>                  </VideoClicks>                  <MediaFiles>                     <MediaFile bitrate=\"408\" delivery=\"progressive\" height=\"240\" type=\"video/mp4\" width=\"320\"><![CDATA[http://i.r1-cdn.net/34/09/91/340991-340949-102329Schwab_TS_Q114_GE_Preroll_mopub.mp4]]></MediaFile>                  </MediaFiles>               </Linear>            </Creative>         </Creatives>      </InLine>   </Ad></VAST>",
            "adomain": [
                "advertiserdomain.com"
            ],
            "bundle": "com.foo.mygame",
            "attr": [
                6
            ],
            "cid": "campaign111",
            "crid": "101409",
            "h": 320,
            "w": 480,
            "impid": "1",
            "price": 0.999
        }]
    }]
}

Changelog

  • February 22, 2016
    • Added documentation for Server-to-Server partners
  • November 10, 2015
    • Updated Deep Link+ URL format from ‘Deep Link+://navigate’ to ‘deeplink’+://navigate’

Last updated October 10, 2018

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2018 MoPub Inc.