Skip to main content

Universal Links & Android App Links (platform-hosted)

Detour hosts association files for every app you configure in the platform:

  • /.well-known/apple-app-site-association (iOS)
  • /.well-known/assetlinks.json (Android)

That means when you create an App in the Detour dashboard and supply the required app identifiers (package name and signing fingerprint / Apple Team ID and Bundle ID), Detour will serve the correct apple-app-site-association and assetlinks.json on your organization subdomain (for example your-org.godetour.link).

Files are generated from app configuration saved in the dashboard and served for the request host.

  • Purpose: preserve click context when the user does not yet have your app installed.
  • Flow: user clicks https://your-org.godetour.link/app-hash/campaign; Detour records a click and redirects to the store; after install the SDK asks Detour for the original link and — if matched — navigates the user into the app.
  • Trigger: works when the app is not installed at click time. Matching happens after install/first-open (deterministic via Play referrer on Android, or probabilistic fingerprinting otherwise).

Universal Links (iOS) / Android App Links​

  • Purpose: open your app directly when a user clicks a link and the app is already installed. They avoid the browser and deep-link straight into the app.
  • Flow: when the link is clicked, the OS checks the domain association files to verify the domain is associated with your app; if verified, it opens the app immediately (with the URL) instead of loading a web page.
  • Trigger: works only when the app is already installed and the domain is verified on the device.

Key point: Universal/App Links are about direct in-app opening when installed. Deferred links are about preserving link context through install flow.

Custom scheme links are app-defined URLs like myapp://promo/summer.

  • They are not verified by domain association files.
  • They require scheme registration in your app (platform-specific).
  • They are useful as a fallback path when verified Universal/App Links are not available in a given context.
App setup required

Custom scheme links work only if your app is configured for a custom URL scheme:

  • Expo: set expo.scheme in app.json (or app.config.*).
  • Android (native): add <data android:scheme="..."> in your deep-link <intent-filter>.
  • iOS (native): add CFBundleURLTypes in Info.plist.

Custom scheme links are delivered to your app by the OS. Detour can expose parsed link data, but final navigation is fully implemented by your app logic.

What Detour hosts​

Detour serves both association endpoints on every configured Detour host (organization subdomain and attached custom domains):

  • https://<host>/.well-known/apple-app-site-association
  • https://<host>/.well-known/assetlinks.json

Payloads are generated from your app configuration in Dashboard, per request host:

  • iOS (apple-app-site-association): Team ID + Bundle ID + configured path pattern, extended with short-link hash paths.
  • Android (assetlinks.json): package name + SHA-256 certificate fingerprints.

If a given host has no configured entry, Detour returns 404.

What you must configure in Detour dashboard​

To let Detour generate correct association files, add this data to your App configuration:

iOS configuration​

  • Bundle ID (e.g. com.example.myapp)
  • Apple Team ID (from Apple Developer account) — used to generate TEAMID.bundleId entries in the AASA appIDs array

Android configuration​

  • Package name (e.g. com.example.android)
  • SHA-256 signing certificate fingerprint(s) — use the release keystore fingerprint or Google Play Signing fingerprint if Play App Signing is enabled

What you need to update in your app​

Use generated snippets from App configuration tab to update files in your app.

iOS​

Inside your app.json add associatedDomains key under ios config:

{
  "expo": {
    // ... other top-level expo keys ...
    "ios": {
      // ... other iOS-specific config ...
      "associatedDomains": ["applinks:<your-host>"]
    }
  }
}

Android​

Inside your app.json add intentFilters key under android config:

{
  "expo": {
    // ... other top-level expo keys ...
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            {
              "scheme": "https",
              "host": "<your-host>",
              "pathPrefix": "/<hash-included-in-link>"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

When you add short links, include additional pathPrefix entries for each short-link hash.

How verification works​

After Detour hosts the files, devices perform automatic verification:

  • iOS will fetch the AASA file and verify appIDs and paths. Once verified, Universal Links for matching paths will open the app.
  • Android will fetch assetlinks.json and verify the package_name + sha256_cert_fingerprints. If verified, intent filters with autoVerify="true" will cause App Links to open the app.

Universal and App Links used directly in browser won't redirect you to the app (Safari might show you banner to open link in app). To test the behavior click link in some messages or notes application.

You can handle Universal/App Links and custom scheme links yourself using your preferred navigation and linking library. However, Detour is smart enough to return the route for such a link in the same way it returns deferred links. For more details, please see the SDK Usage page.

We are Software Mansion.

Hire us