App link best practices

info

• The following information is only applicable for app links. If custom URIs are used for link-based authentication, none of the information below applies.
• You can find a description of the mobile-only feature prerequisites in the Link channel.
• If your site uses multiple subdomains (such as example.com, www.example.com, and support.example.com), each must serve its own Digital Asset Links and Apple App Site Association files.

Android - Digital Asset Links File

The Digital Asset Links JSON file must be served under a subdomain of your webpage: https://<subdomain>.<yourdomain>/.well-known/assetlinks.json, note that the file has the .json file extension.

The following snippet shows a working example of the file.

DAL example

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "ch.nevis.accessapp",
      "sha256_cert_fingerprints": [
        "91:D7:03:AF:EB:09:57:27:40:91:9E:A7:4F:F1:D1:DD:4A:49:15:27:7E:BC:F3:91:5C:BC:30:F0:32:07:57:B7"
      ]
    }
  }
]

The package_name corresponds to the app identifier. To calculate or obtain the sha256_cert_fingerprints, refer to the official documentation.

If you are using multiple certificates to sign apps with the same app identifier, add the additional certificate hash to the fingerprints array.

Multiple Android applications sharing the same app link domain

If multiple applications are using the same app link domain, extend the digital asset links JSON file with an entry for each app:

Multiple app link applications example

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "<app identifier 1>",
      "sha256_cert_fingerprints": [
        "<certificate fingerprint 1>"
      ]
    }
  },
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "<app identifier 2>",
      "sha256_cert_fingerprints": [
        "<certificate fingerprint 2>"
      ]
    }
  },
  ...
]

Uppercase certificate fingerprint

Ensure that the certificate fingerprint is written in UPPERCASE.

iOS - Apple App Site Association File

iOS app .entitlements file

For every deep link domain the app needs to support, a respective entry in the .entitlements file must exist. This file is created as part of the publication processs.

The Apple App Site Association JSON file must be served under a subdomain of your webpage: https://<subdomain>.<yourdomain>/.well-known/apple-app-site-association, note that the file does not have the .json file extension.

Universal links let users open your app when they tap links to your website within WKWebView and UIWebView views and Safari pages, in addition to links that result in a call to openURL:, such as those that occur in Mail, Messages, and other apps. When a user is browsing your website in Safari and they tap a universal link to a URL in the same domain as the current webpage, iOS respects the user’s most likely intent and opens the link in Safari. If the user taps a universal link to a URL in a different domain, iOS opens the link in your app.

The following snippet shows a working example of an AASA file entry. The appID consists of the Team ID followed by the app identifier.

Simple example

{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "U8KPBF668H.ch.nevis.accessapp"
        ],
        "components": [
          {
            "/": "open",
            "?": { "dispatchTokenResponse": "*" },
            "caseSensitive": false
          }
        ]
      }
    ]
  }
}

With this example, the app link presented on your webpage would be https://<subdomain>.<yourdomain>/open?dispatchTokenResponse=<base64url_payload>.

JSON properties

The complete description of the JSON properties can be found in the official applinks documentation.

Multiple iOS applications sharing the same app link domain

In addition to the prerequisites described for the mobile-only feature, you need to consider the following limitation if multiple applications use the same universal link domain and thus share the same Apple App Association File (AASA) on the backend.

In this particular case, configure all applications in the AASA file in a predefined order in the details array. The order of the apps in the details array determines the order in which the iOS system will open the applications when processing the deep link. See also the next code sample:

Multiple app link applications example

{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "<team id 1>.<bundle id 1>",
          "<team id 2>.<bundle id 2>"
        ],
        "components": [
          {
            "/": "open",
            "?": {
              "dispatchTokenResponse": "*"
            },
            "caseSensitive": false
          }
        ]
      }
    ]
  }
}