🔗Universal Links

Associate your website domain with your app so that links open directly in your app instead of a browser.

What are Universal Links

Universal Links associate your website domain directly with your app - no third-party service required. When a user taps a link to your website, the device recognizes it as a deep link and opens your app instead of a browser, navigating them directly to the right page or content.

If the app is not installed on the device, the link opens normally in the browser, so your website always works as a fallback.

Setups differ between iOS and Android. Use the sections below to follow the correct setup for your platform, or complete both if your app supports both platforms.

iOS

Prerequisites

• An Apple Developer account.

• Your iOS app is already published in the Natively Dashboard.

App Capabilities Configuration

App capabilities define what system-level features your app is allowed to use on iOS. Before Natively can include Universal Links in your build, the Associated Domains capability must be explicitly enabled in your Apple Developer account for your app's Bundle ID.

1. Open your Apple Developer account and navigate to Certificates, IDs & Profiles > Identifiers.

2. Select your app's Bundle ID.

3. Scroll down the Capabilities list and enable Associated Domains.

4. Click Save and confirm.

apple-app-site-association

For Universal Links to work, your website must host a special verification file called the Apple App Site Association (AASA) file. This file tells iOS that your website and app are associated, allowing links to your domain to open in your app instead of a browser.

Download AASA template

apple-app-site-association

308B

Open

The webcredentials section is required if you are using Social Auth in your app. Without it, OAuth authentication will not work correctly on iOS.

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "TEAM_ID.BUNDLE_ID",
                "paths": [
                    "*"
                ]
            }
        ]
    },
    "webcredentials": {
        "apps": [
            "TEAM_ID.BUNDLE_ID"
        ]
    }
}

Replace TEAM_ID with your Apple Team ID and BUNDLE_ID with your iOS app's Bundle ID.

Your Apple Team ID is located in your Apple Developer account under Membership details.

Team ID under Membership Detail

Bundle ID from App Store Connect iOS app

On iOS 14 and later, Apple's CDN retrieves and caches the AASA file. When your app is installed, devices immediately download the file from the CDN. Devices check for updates approximately once per week after the app is installed. To download a newer version of the AASA file, reinstall the app. There is no direct CDN invalidation option.

It is up to third-party web browsers to enable Universal Links functionality. Universal Links may not be enabled in every web browser. Safari implements all of the functionality described in this page. For information about other browsers, check with the browser's vendor.

Android

Prerequisites

• Your Android app is already published in the Natively Dashboard.

• Your app is uploaded to the Google Play Console - required to access the Upload key SHA-256 certificate fingerprints.

assetlinks.json

For Android App Links to work, your website must host a Digital Asset Links file. This file tells Android that your website and app are associated, allowing links to your domain to open in your app instead of a browser.

Download assetlinks.json template

assetlinks.json

287B

Open

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "BUNDLE_ID",
      "sha256_cert_fingerprints": [
        "APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

Replace BUNDLE_ID with your app's Bundle ID. As for the SHA256 fingerprints:

• APP_SIGNING_KEY_SHA256 — your App signing key SHA-256 certificate fingerprint.

• UPLOAD_KEY_SHA256 — your Upload key SHA-256 certificate fingerprint.

Both can be found in your Google Play Console app page under Protected With Play > Play Store protection > Protect app signing key > Manage Play App Signing.

If you don't see the Upload key certificate content, you need to upload your app first.

Google Play Console Manage Play app signing

SHA-256 fingerprints

Website setup

Before proceeding, make sure you have already created and configured your verification files for iOS and Android.

Once your files are ready, follow the instructions below for your platform to host them on your website.

General

To make Universal Links work, your website needs to host two special files at specific locations that Apple and Google can access to verify your domain.

Upload the relevant file(s) for your platform::

• apple-app-site-association - required for iOS, must be accessible at https://yourdomain.com/.well-known/apple-app-site-association

• assetlinks.json - required for Android, must be accessible at https://yourdomain.com/.well-known/assetlinks.json

Files must be publicly accessible without any redirects.

Files must be served with the content type application/json. If the content type is incorrect, Apple and Google might not be able to verify your domain even if the files are accessible.

If you are unsure how to host files on your website, check the other tabs for platform-specific instructions.

Bubble.io

1. Open your Bubble project.

2. Go to the Settings > SEO / metatags.

3. Scroll down and find the Hosting files in the root directory section.

4. For iOS: set the name to .well-known/apple-app-site-association and upload your AASA file.

5. For Android: set the name to .well-known/assetlinks.json and upload your assetlinks.json file.

6. Publish the changes.

AI Agents

Lovable, Replit, and Base44 all use React/Vite under the hood, which copies everything in the public/ folder to the build output root as-is. This means you can host the verification files simply by asking your AI assistant to create them at the correct paths.

Copy your configured file content from the iOS or Android sections above, paste it into the placeholder at the end of the copied text, then send it to your AI agent.

For the iOS app, copy the line below and paste it into your AI agent:

Create a file at public/.well-known/apple-app-site-association with the following content: [paste your configured apple-app-site-association content here]

For the Android app, copy the line below and paste it into your AI agent:

Create a file at public/.well-known/assetlinks.json with the following content: [paste your configured assetlinks.json content here]

Once published, the files will be automatically accessible on your domain.

How to verify?

Once your verification files are hosted, confirm everything is configured correctly before proceeding to the Natively Dashboard Setup.

Both tools check the live hosted files, not your local copies. Make sure you have published your changes before running the verification.

iOS

AASA Validator | BranchBranch

Use the Branch AASA Validator to verify your apple-app-site-association file. Enter the following details to confirm the file is accessible, correctly served, and valid:

• Domain - your website domain.

Android

Statement List Generator and Tester  |  Google Digital Asset Links  |  Google for DevelopersGoogle for Developers

Use the Google Digital Asset Links tool to verify your assetlinks.json file. Enter the following details to confirm the file is correctly hosted and your app is properly associated with your domain:

• Hosting site domain - your website domain.

• App package name - your app's Bundle ID.

• App package fingerprint (SHA256) - either your app signing key or upload key SHA256 fingerprint from the Google Play Console.

Checking via Android device settings

You can also verify directly on your Android device. Go to Settings > Apps > [your app] > Open by default (also called Supported web addresses on some devices):

• If the toggles are enabled or the link is present but there are no toggles (behavior depends on Android vendor) - Android Universal Links are correctly configured.

• If the toggles are present but disabled - the assetlinks.json is incorrect or couldn't be verified by Android. The app is configured for deep links, but Android couldn't confirm domain ownership.

Natively Dashboard Setup

Before proceeding, make sure your verification files are hosted and accessible. You can confirm this using the tools in the How to verify section above. If there are any issues with your files, Natively Dashboard will indicate a configuration problem, and the feature cannot be enabled until they are resolved.

1. Open your Natively app dashboard and navigate to Features > Deep Links > Universal Links.

2. Toggle the feature to Enabled.

3. Enter your Associated Domain - your website domain (e.g. yourdomain.com).

4. Click Save.

5. Rebuild your app(s).

You must rebuild your app for these changes to take effect.

Natively will prefill the Associated Domain with your app's URL configured in the Natively Dashboard. You can modify it if your deep links domain differs from your app's main URL.

Troubleshooting

Website Links are opening in a browser instead of the app

Most commonly caused by one of the following:

• Verification files are not correctly hosted or formatted.

• The Associated Domain in the Natively Dashboard doesn't match the domain where your files are hosted.

• App not rebuilt after enabling the feature.

Universal Links are not working after updating the AASA file

Apple's CDN caches the AASA file and checks for updates approximately once per week. To force a refresh, reinstall the app on your device.

Universal Links are not working in third-party browsers

Third-party browsers may not support Deep Links on either platform. On iOS, Universal Links are only guaranteed to work in Safari. On Android, behavior varies by browser - some browsers, like Samsung Internet, may not open the app correctly, while others, like Firefox on the same device, may work fine. If Universal Links are not working in a specific browser, check with the browser's vendor for more information.

Android app not opening from an Associated Domain link

Check the following:

• The file is served with the content type application/json .

• The file is accessible without any redirects.

• Both SHA-256 fingerprints (app signing key and upload key) are present in the file; if either one is missing, the app will not open.

• The package name matches your app's Bundle ID exactly.

iOS app not opening from an Associated Domain link

Check the following:

• The file is served with the content type application/json .

• The file is accessible without any redirects.

• Both applinks and webcredentials sections are present and correctly formatted.

• The Team ID and Bundle ID are correct.