Deeplink troubleshooting

There are various factors that can affect your deeplink behavior. If you are experiencing unexpected results from your deeplinks either in testing or production, consult this guide to make sure your setup is correct. 

If after reviewing the steps listed here your issue persists, contact support@adjust.com

General problems

Is my URL syntax and encoding correct?

If your deeplink is not directing you to the specified destination or returning an HTTP 404 error, first check your URL syntax and encoding. 

URLs typically use this syntax: scheme://host:port/path?query-string#fragment-id

Each part of a URL performs a different function and uses specific characters to identify and separate values. The scheme and host are not case sensitive but the path and query-string are. A mistake in the composition of your URL will prevent it from opening as it should.

When setting up your deeplink, pay attention to these conditions:

  • If you add an Adjust parameter to a URL query string already containing query parameters, use an &. Any information after the second ? in a URL is dropped. 
    • E.g.,https://abcd.adj.st/path?path_param=value&adjust_t=abc123
  • If your query string is encoded, start it with a / or ensure it is part of a deeplink parameter 

If your app isn’t already installed and these conditions are not met, the adjust_t parameter is dropped by the browser. Adjust needs this parameter to locate the source of the click; without it, we will return the HTTP 404 error URL not found.

Examples

Depending upon how your URL is set up, your deeplink can have the following behaviors:

Tracker URL + deep_link parameter - opens the app: https://app.adjust.com/r40ncx7?deep_link=adjust%3A%2F%2F%3Fpath

Universal link - opens the app: https://abcd.adj.st/%3Fpath?adjust_t=r40ncx7

Universal link - opens the store: https://abcd.adj.st/?path&adjust_t=r40ncx7

Universal link - is invalid and returns an error: https://abcd.adj.st%3Fpath?adjust_t=r40ncx7

Attribution data and/or campaign levels aren’t showing in the dashboard

If you aren't seeing attribution data or campaign levels from your deeplink tracker URL, it's likely due to a setup problem. Check that device ID parameters and campaign parameters (as applicable) are not being cut off due to encoding errors in fallbacks or callbacks. For instance, there are no spaces in the URL or invalid characters. 

My app is installed but I’m still directed to the store

Typically this behavior means that your deeplink has failed to open the app, and we have redirected to the store as a fallback. To test this, follow these steps:

  1. Follow our testing instructions as an existing user for universal links and trackers with the deep_link parameter
  2. If your test is successful and the app opens, consider what environment the deeplink was clicked from when it failed. Then check to see if any additional parameters are required for that instance. 
    1. For example: if a JSR ulink is clicked from Slack, the adjust_deeplink_js=1 flag should be present. This helps load the scheme from the dashboard before redirecting to the store. If your link does not work even with the js-flag present, then your App Scheme may be incorrectly entered in the dashboard. 
  3. Ensure there are no encoding errors to your fallbacks or callbacks in the tracker URL that might break it.

My deeplink opens the app, but not in the specified destination 

In general, once the app has opened Adjust’s job is done. To test whether it is your link or app setup causing the problem, host the universal link domain (https://abcd.adj.st/) or scheme (myapp://) on a web environment and click it from there. 

If your link does not open in the right place but it does open your app, contact your development team to make sure the paths within the app are set up correctly. 

Troubleshooting universal links

My universal link doesn’t open an installed app

First, check which environment Apple is opening the link from. Redirects to universal links are not allowed by Apple outside of Safari, so you need to host the raw universal link or scheme in a web environment. For example, https://abcd.adj.st/ or myapp://, respectively. With the app installed on your test device, visit the page, and select the deep link. 

If the app opens when the raw scheme/universal link is selected, check to see if there are some unencoded callbacks or fallbacks that break the original, full-length URL. They will cause parameters to be dropped. Dropped parameters will result in the complete tracker or universal link to not work as intended.

Another item to check is the following target attribute:

target=“_blank”

This may lead to the app opening during a test, but not outside of a testing environment.

For example, your HTML code may look similar to the following containing the target=“_blank” attribute:

<a href="https://abcd.adj.st" target="_blank">Universal Link to App</a>

To resolve this issue, remove the attribute, as in the following example:

<a href="https://abcd.adj.st">Universal Link to App</a>

If the app does not open, either the universal link or scheme is not properly associated with your app.

If the app does not open, the universal link or scheme may not be properly associated with your app. Ensure your app’s iOS bundle ID and App Prefix in Adjust Dashboard, under All Settings > Platform and… > Universal Linking. If correctly set up and your app still does not open, consult your developer to further investigate the universal link or scheme app association.

App Prefix field in the Universal Linking section

Can I use universal links in email campaigns? 

Unfortunately, iOS does not allow redirection to universal links and therefore any environment using SFSafariViewController is impacted.

I’m having issues with JSR deeplinks in Safari for iOS 12.2 and 12.3

For iOS 12.2 and 12.3, JSR universal links do not always open properly when clicked in a Safari environment. This specifically affects instances where the referrer HTTP header isn’t readable: for instance, when using incognito mode. 

For Safari campaigns, we therefore recommended using raw universal links. Although this won't work for email campaigns with wrapped URLs.

From iOS 13+, this issue does not apply as we can fallback to the scheme. However, this leads to an additional pop-up.

Troubleshooting deeplinks with tracker + deep_link parameter

My deeplink isn't working from a Facebook post

Campaigns run through Facebook posts have to use an Adjust tracker URL with a deeplink parameter appended. In addition, the deeplink parameter must have a path appended to it, or the user will be taken to the store (even if the app is installed). The path provided does not need to be valid. 

Example of a parameter with appended path: https://app.adjust.com/abc123?deeplink=adjust%3A%2F%2Fsuch_path

Troubleshooting deferred deeplinks

Deferred deeplinking not opening the app in the right place after install  

When your deferred deeplink doesn’t take you to the right path within the app after install, first check to see whether this path actually exists. You can do this by performing this test.  

If you are taken to the correct path as an existing user, but not as a new user, inspect your device via the Testing Console and make sure you were attributed to the click. If you were not, forget the device via the Testing Console and try again. 

If you were attributed to the click, inspect your device to check it includes a deeplink parameter. If it does not, make sure there are no encoding issues or special characters that are cutting off the URL before the deeplink parameter.

Finally, if a deeplink parameter is included then make sure the path is present as you’d expect. If it's not, the deeplink path has been cut off for some reason. Reach out to support@adjust.com for further assistance. 

My deferred deeplink doesnt work after forgetting the device

Sometimes when testing, the deferred deeplink is persisted for some time after the click - even after forgetting the device via the Testing Console.

If this happens, your test may look like this:

  1. You clicked the deeplink, installed the app, and opened it

  2. You uninstalled the app

  3. You forget the device via the Testing Console

  4. You run another test (click, install, open) and the deferred deeplink does not work  

In this situation, uninstall the app again, forget your device via the Testing Console, and then rerun the test. After doing this, the deferred deeplink should once again work as expected.

On this topic