Universal links

Universal links are a specific deeplinking protocol available for iOS version 9 and later. 

Here you’ll learn how to set up, test, and track campaigns with universal links.

Before you begin

Here’s what you need to know before getting started. 

Requirements

Helpful information

  • Universal links are constructed differently to the custom URL schemes used in earlier iOS versions and other mobile platforms

Set up universal links

Enable universal links in your Adjust dashboard

  1. Navigate to your app and select your app options caret (^)
  2. Select All Settings > (Settings) Platforms
  3. Enter your app's iOS BUNDLE ID (as assigned by Apple’s App Store)
  4. Select Universal Linking
  5. Enter your APP PREFIX (as listed within your Apple Developer Account Summary) and APP SCHEME (as determined by your app developers)
  6. With all fields filled, a short universal link appears. Example: http://z9pm.adj.st
  7. Select Save
After all fields have been filled, a short universal link will appear in your universal linking module: 

Submit this short universal link to your app developer to continue the integration process.
 

Navigate to your app and select your app options caret (^)

Select All Settings

Select Platforms

Select Universal Linking

Enter your app's iOS BUNDLE ID (as assigned by the Apple App Store)

Enter your APP PREFIX (as listed within your Apple Developer Account Summary) 

Enter your APP SCHEME (as determined by your app developers)

Add support for universal links in your app

To whitelist the app-specific subdomain inside your app, send your short universal link to your app developer. They can follow the instructions in our Github developer guide, or see Apple’s Developer Documentation for more information.

Track campaigns with iOS deeplinks

You can deeplink users into your iOS app using:

  • Universal links
  • Javascript universal links
  • Adjust tracker URLs + deep_link parameter

Note: To use deeplinks with a tracker URL and deep_link parameter for iOS 9 + campaigns, make sure universal links are set up in your dashboard and Xcode project. This lets Adjust translate the tracker into a universal link, to return to the device and open the app.

The best linking method is the one that supports your ad environment, where users interact with your ads.

Here, you can see which setup is best suited for your campaign.

    Ad environmentRecommendation

    Chrome browser

    Universal link
    Tracker + deep_link parameter

    Safari browserUniversal link
    Tracker + deep_link parameter
    Facebook NewsfeedUniversal link
    Javascript universal link
    Tracker + deep_link parameter

    Note: Must append path
    Facebook browserUniversal link
    Javascript universal link
    Tracker + deep_link parameter

    Facebook Messenger

    Universal link
    Javascript universal link
    Tracker + deep_link parameter

    Note: Must append path

    Facebook Messenger browserUniversal link
    Javascript universal link (append path)
    Tracker + deep_link parameter (append path)
    InstagramTracker + deep_link parameter

    Note: Universal linking must be implemented in the app

    Gmail

    Universal link

    Apple Mail

    Universal link
    Tracker + deep_link parameter

    Slack

    Universal link

    WhatsApp

    Universal link
    Tracker + deep_link parameter

    Snapchat message

    Universal link
    Javascript universal link
    Tracker + deep_link parameter

    Note: Must append js flag

    Deeplink with SFSafariViewController

    Universal link
    Javascript universal link

    Note: Must append js flag

      Note: Universal links are not supported in the following app environments: Pinterest, Telegram, Twitter, and WeChat

      Create a universal link

      Short universal links with an Adjust tracker appended are the standard format of our universal links. They are short, tidy, and work in web campaigns.

      A short universal link without a tracker appended will only work for users with iOS 9+ and who already have your app installed.  

      Note: iOS does not allow redirects to universal links. This means wrapping your universal link in another URL won't work. If you wish to wrap your universal links, use our JSR solution.

      To set up your universal link, you can use our Deeplink Generator. This saves time and prevents errors. You can find the Deeplink Generator in the Adjust dashboard by selecting Menu > Deeplink Generator.

      If you want to manually set up your universal link, follow these steps.

      Navigate to your app and select your app's options caret (^)

      Select All Settings

      Select Platforms

      Select Universal Linking

      In this example, the short universal link token is: u7f3.adj.st

      Identify the Adjust tracker token to be used for campaign tracking or create an Adjust tracker URL for your new campaign. (This token should be the lowest level of segmentation, as defined by your Adjust campaign structure parameters). To find an existing token, navigate to your app and select your app's options caret (^)...

      Then select Tracker URLs

      In this example, the tracker token is: bkrn68

      In a plain text file, add https:// to your short universal link token

      Append the Adjust tracker token to the URL with the adjust_t parameter. Remember to begin your query string with a ?

      Add your in-app path, if applicable

      Append additional key-value pairings, if necessary. These will be custom to your app and your campaign.


      In the Adjust dashboard
      1. Find your app and select your app's options caret (^)
      2. Select All Settings > (Settings) Platforms > Universal Linking
      3. Copy your Short Universal Link
      4. Find or create a tracker URL to use
      5. Copy your tracker token
      In your preferred text editor

      1. Add https:// to your short universal link 
      https://z9pm.adj.st/
      2. Add a ? and append your tracker token to the URL with the adjust_t parameter
      https://z9pm.adj.st/?adjust_t=klm012
      3. Add your in-app path (if applicable) 
      https://z9pm.adj.st/my/path?adjust_t=klm012
      4. Add any other Adjust parameters (if applicable) 
      ​https://z9pm.adj.st/my/path?adjust_t=klm012&adjust_campaign=Getaway_Vacation_Campaign_2-0&adjust_adgroup=35-42&adjust_creative=island_sunset
      
      Well done! Your universal link is ready to use.

      Adding in-app paths

      If your universal link path already includes query parameters, avoid using ? to append Adjust parameters. When two ? characters are used in a URL, any information after the second will be dropped by the browser, which may result in an HTTP 404 error if your app is not installed. You can use the example below to confirm your setup, or check our Troubleshooting guide for more information.
       

      Correct: https://z9pm.adj.st/my?path=location&client=name&adjust_t=klm012

      Incorrect: https://z9pm.adj.st/my?path=location&client=name?adjust_t=klm012

      Create multi-platform universal links

      A multi-platform universal link will deeplink all of your app users with a single Adjust URL. Setup depends on how you've configured your apps within the Adjust dashboard.

      For apps separated by platform in Adjust

      In the Adjust dashboard

      1. Find your iOS app and select your app's options caret (^)
      2. Select All Settings > (Settings) > Platforms > Universal Link
      3. Copy your Short Universal Link
      4. Find the custom URI to include in your tracker URL. This is the specific location or landing page within your Android app you want to deeplink users to. Example: ​myamazingapp://super/exclusive/promotion​ 
      5. Encode your custom URI
      6. Find or create the tracker tokens to be used for campaign tracking. Likely, this will be one tracker token for Android and one tracker token for iOS. Example: abc123 and 987xyz
      In your preferred text editor

      1. Add https:// to your short universal link   
      https://z9pm.adj.st/
      2. Add ? and append your tracker tokens, separated by a single underscore, to the URL with the adjust_t parameter 
      https://z9pm.adj.st?adjust_t=abc123_987xyz
      3. Add your in-app path (if applicable)
      https://z9pm.adj.st/my/path?adjust_t=abc123_987xyz
      4. Append the adjust_deeplink parameter and the encoded custom URI
      https://z9pm.adj.st/my/path?adjust_t=abc123_987xyz&adjust_deeplink=myamazingapp%3A%2F%2Fsuper%2Fexclusive%2Fpromotion
      5. Add additional Adjust parameters (if applicable)

      Well done, your tracker URL will now deeplink all of your app's users.

      Navigate to your app and select your app's options caret (^)

      Select All Settings

      Select Select Platforms

      Select Universal Linking

      Find your iOS app's short universal link token. In our example, the short universal link token is u7f3.adj.st

      Identify the custom URI that you want to include in your tracker URL. This will be a specific location or landing page within your Android app. In our example, the custom URI is: myamazingapp://super/exclusive/promotion

      All custom URIs must be encoded to ensure that no data is lost. An encoded URI will appear as follows: myamazingapp%3A%2F%2Fsuper%2Fexclusive%2Fpromotion

      Identify the Adjust tracker tokens to be used for campaign tracking or create an Adjust tracker URL for your new campaign. More than likely, this will be one tracker token for Android and one tracker token for iOS. To reduce the number of characters in your Adjust tracker URL, you may want to use the lowest sublevel (creative level) tracker URL generated within the Adjust dashboard.

      In a plain text file, add https:// to your short universal link token

      Append the Adjust tracker tokens to the URL with the adjust_t parameter, separating each token with a single underscore. Remember to begin your query string with a ?

      Add your in-app path, if applicable

      Append the adjust_deeplink parameter and the encoded custom URI. (Then append additional key-value pairings, if necessary. These will be custom to your app and your campaign.)

      For apps configured as multi-platform in Adjust

      In the dashboard

      1. Find your app and select your app's options caret (^)
      2. Select All Settings > (Settings) Platforms > Universal Link
      3. Copy your short universal link 
      4. Find the custom URI to include in your tracker URL
      5. Encode your custom URI
      6. Find or create the tracker tokens to be used for campaign tracking

      In your preferred text editor

      1. Add https:// to your short universal link

        https://z9pm.adj.st/
      2. Add a ? and append your tracker tokens to the URL with the adjust_t parameter

        https://z9pm.adj.st/?adjust_t=abc123
      3. Add your in-app path (if applicable)

        https://z9pm.adj.st/my/path?adjust_t=abc123
      4. Append the adjust_deeplink parameter and encoded custom URI

        https://z9pm.adj.st/my/path?adjust_t=abc123&adjust_deeplink=myamazingapp%3A%2F%2Fsuper%2Fexclusive%2Fpromotion
      5. Add additional Adjust parameters (if applicable)

      Good job! Your URL will now deeplink all of your multi-platform app's users.
       

      User-added image User-added image User-added image User-added image User-added image User-added image User-added image User-added image User-added image User-added image User-added image User-added image

      Navigate to your app and select your app's options caret (^)

      Select All Settings

      Select Select Platforms

      Select Universal Linking

      Find your iOS app's short universal link. In our example, the short universal link token is u7f3.adj.st

      Identify the custom URI that you want to include in your tracker URL. This will be a specific location or landing page within your Android app. In our example, the custom URI is: myamazingapp://super/exclusive/promotion

      All custom URIs must be encoded to ensure that no data is lost. An encoded URI will appear as follows: myamazingapp%3A%2F%2Fsuper%2Fexclusive%2Fpromotion

      Identify the Adjust tracker token to be used for campaign tracking or create an Adjust tracker URL for your new campaign. To reduce the number of characters in your Adjust tracker URL, you may want to use the lowest sublevel (creative level) tracker URL generated within the Adjust dashboard.

      In a plain text file, add https:// to your short universal link token

      Append the Adjust tracker tokens to the URL with the adjust_t parameter, separating each token with a single underscore. Remember to begin your query string with a ?

      Add your in-app path, if applicable

      Append the adjust_deeplink parameter and the encoded custom URI. (Then, append additional key-value pairings, if necessary. These will be custom to your app and your campaign.)

      Create Javascript universal links

      Javascript universal links (JSR) are used when a click and HTTP redirect happen outside of supported environments, like in an email campaign. Normally, universal links break in this instance and send all users to the store, even if they have the app installed. 

      Universal linking must be set up in your app and dashboard for JSR to work.

      For iOS 11 and later

      To add the JSR linking parameter to your tracker, follow these steps. 

      1. Find the universal link you want to use. Example: https://ab12.adj.st/?adjust_t=abc123
      2. Encode your universal link
      3. Append your encoded universal link after this: https://app.adjust.com/jsr?url=
      Example:
      https://app.adjust.com/jsr?url=https%3A%2F%2Fab12.adj.st%2F%3Fadjust_t%3Dabc123

      For iOS 10.3 and earlier

      To target users in Safari webview or iOS versions earlier than 11, you can add the following flag to your JSR universal link: adjust_deeplink_js=1. The flag works as a fallback, prompting the link to open via a scheme and directing users either to the store (if they don't have the app installed) or to a pop-up inviting them to open the page in your app. 

      Example:

      https://app.adjust.com/jsr?url=https%3A%2F%2F6s45.adj.st%2F%3Fadjust_t%3D1uhwo6%26adjust_deeplink_js%3D1
      

      Attribute users from Safari Smart App Banners

      Safari Smart App Banners automatically determine whether your app is supported on a user’s device and don't display if it’s not. After tapping the banner, it detects whether your app is already installed on the users device. If it is, users are deeplinked to the designated in-app page. If it isn't, users are first routed via the App Store to download and install the app before being deeplinked.

      To set up click attribution for Smart App Banners, add your deeplink to the app-argument parameter of the banner HTML tag. 

      Your complete banner will like this:

      <meta name="apple-itunes-app" content="app-id=myAppStoreID, affiliate-data=myAffiliateData, app-argument=myapp://landing_page">
      

      For more information on setting up Smart App Banners, check Apple's developer guide

      Note: Adjust only reattributes users to Safari Smart App Banners if the user already has the app installed. Users who install after being redirected to the App Store are attributed as organic (or another valid attribution source).

      Test your universal link

      To check that your universal link is set up correctly, test it in different scenarios. Since universal links have to be opened in Safari or Chrome, host your links in a web environment for testing. If during testing you encounter problems, check our Troubleshooting guide for more information.

      As an existing user

      To test your universal link as an existing user, follow these steps.  

      1. Create a test web page that’s easily accessible from your test device
      2. Add your raw universal link to the test webpage
      3. Add your complete universal link to the test webpage
      4. Use TestFlight to load the new build of the app on your device or install a debug version of the app with xCode. Then, open your test webpage in the browser.
      5. Click on your universal link. Once the new app build has been installed, you should automatically be deeplinked into your app.

      If your app installs and opens automatically on the correct page, you're ready to track campaigns with it.

      If the app does not open, verify that your integration is correct by clicking on the short universal link (Example: https://z9pm.adj.st). If the link fails and returns the HTTP 404 error URL not found, revisit our integration instructions.

      Note: To test JSR links, its best practice to always use the specific environment where the campaign will run.

      As a new user (deferred deeplinking)

      To test your universal link as a new user, follow these steps.

      1. Uninstall the app completely from the device (empty app trash if applicable)
      2. Run forget_device via the Testing Console in the Adjust dashboard
      3. Create a test web page that’s easily accessible from your test device
      4. Add your universal link to the test webpage
      5. Add your universal link token to the test webpage
      6. Click your deeplink tracker URL and wait to be redirected to the app store
      7. Download the app and open it - this will trigger an install in Adjust
      8. At app open, you will be deeplinked to the specific location written in your custom URI scheme

      If you are deeplinked after opening the app then your Adjust setup is complete.

      If your universal link doesn’t work with the app uninstalled, but does with the app installed, check the App Scheme entered in the Adjust dashboard is correct. You can find this by selecting All Settings > Platforms > Universal Linking.

      On this topic