This article will help you understand and troubleshoot common errors when you implement App links or Universal links.
On this page
- Common setup errors for App Link implementation
- Common setup errors for Universal Link implementation
Common setup errors for App Link implementation
These are the common setup errors for Android App links and how to fix them.
Web errors
- Host attribute formed properly: Ensure the host is a well formed URL such as google.com or www.google.com.
- Missing digital asset links JSON file: It should be found for each unique hostname housed in the intent filters. For example, https://[domain.name]/.well-known/assetlinks.json.
- Note: This error could also come up if the JSON file is not crawled by Google. For example, when crawler access is denied in the robots.txt file. You may check the JSON file URL to determine if that’s the case.
- Wrong app package name in digital asset links JSON: This package name should match the application ID declared in the app’s build.gradle file, and the app should be available in the Google Play Store.
- Wrong app fingerprint (sha256_cert_fingerprints) in the digital asset links JSON. Learn more about how to troubleshoot this error.
- Incorrect content-type in the digital asset links JSON: The content-type should be “application/json” for all web domains.
- Digital asset links JSON is only accessible on http:// instead of https://: No matter if the app declares http:// or https:// as the App Link, the JSON must always be hosted on https:// for security purposes.
- Digital asset links JSON file is only accessible only via redirects: This file must be directly accessible to verify ownership of the app, without any 301/302 redirects.
- Robots.txt file is blocking crawling access to /.well-known/assetlinks.json: This file must be accessible by bots.
App errors
- Missing <data> tag that includes the android:scheme attribute in the manifest of the app
- Missing ACTION_VIEW intent action attribute within the the intent filter (android.intent.action.VIEW)
- Missing DEFAULT & BROWSABLE categories as attributes within the intent filter (android.intent.category.DEFAULT & android.intent.category.BROWSABLE)
- Missing android:autoVerify=”true” attribute in the intent filter
- Inclusion of redirect URLs: All URLs must take users directly to the app.
- Logically contradicted App Links declaration: Overlapping App Links URL, for example: https://example.com/ triggers activity X, and https://example.com/Y triggers activity Y. With this condition, the Android system will display an app-selection dialog (breaking the App link). This is not currently detected by the deeplink validator, and it is not a recommended implementation.
Common setup errors for Universal Link implementation
These are the common setup errors for iOS Universal links and how to fix them.
Web errors
- Missing association file on the web domain: If the site uses multiple subdomains (such as example.com, www.example.com, or support.example.com), each requires its own entry in the Associated Domains Entitlement, and each must serve its own apple-app-site-association file.
- Hosting the association file in the wrong place: The association file has to be hosted on the same domain as your universal link. No redirects are allowed. For example, if your universal link is https://photo.google.com/album, your association file has to be at https://photo.google.com/.well-known/apple-app-site-association or https://photo.google.com/apple-app-site-association.
- Note: /.well-known/ is the preferred method.
- Addition of .json extension to the Apple App Site Association (AASA) file: Exclude .json as apple-app-site-association.json is incorrect.
- Serving association file with content-type of MIME plain/text: It must have application/json.
- Exceeding file size limits: The association file must be smaller than 128KB (uncompressed size).
- Incorrect App ID configuration: App ID must be generated by Team ID and Bundle ID joined with dot (.) .
- Having a robots.txt or other mechanism on the domain blocking crawl access to the association file
- Logically contradicted Universal Links declaration: The “paths” key will be handled in order.
Example 1
https://apple.com/wwdc/ will trigger Universal Links.
{
"appID": "ABCD1234.com.apple.wwdc",
"paths": [ "*", "NOT /wwdc/*" ]
},
Example 2
Universal links for the second app (EFGH5678.com.apple.wwdc) never works.
{
"appID": "ABCD1234.com.apple.wwdc",
"paths": [ "*" ]
},
{
"appID": "EFGH5678.com.apple.wwdc",
"paths": [ "/wwdc/news/", "/videos/wwdc/2015/*"]
}
App errors
- Using custom scheme: Use https or http.
- Missing applinks: prefix: The format for all associated domains should resemble applinks:yourdomain.com.
- Improper configuration of associated domains: For example, .google.com matches www.google.com but doesn’t match google.com. If you want to declare association for both google.com and the sub domains (such as www.google.com), you should declare applinks:*.google.com and applinks:google.com.
Note: The deep link validator will not do app-level checks on AASA json file validity.
Best practices
- Test on your phone: Send the URL to our phone where the app is installed. Click on the link using an app without a built-in browser (Google Keep may be a great tool to test this).
- If the app is opened, it’s a valid Universal Link.
- If the app is not opened, or if there is a confirmation dialog to open the app, you don’t have a valid Universal Link.
- The app would not open on Appify in this case.
- If the app is being used for an App Campaign for engagement, the ad would be disapproved in this case.
