Deep Linking

1What is Deep Linking?#

Deep Linking allows external sources (browsers, SMS, emails, social media, push notifications, QR codes) to open your app directly to a specific page instead of the homepage.

Your app supports two kinds, and they are NOT equally easy:

1. ⚡ Custom Scheme (myapp://path) - works immediately, nothing to set up. Best for push notifications and QR codes.

1. 🌐 https:// links (https://mysite.com/page) - needs ONE file uploaded to your website. Without it Android keeps the link in the browser and your app never opens. This is the single most common reason deep links 'do not work'.

Both are covered below. If you only need something working today, use the custom scheme.

2How Custom Scheme URLs Work#

When a custom scheme link is tapped (e.g., myapp://products/shoes), the app:

1. Receives the custom scheme URL
2. Automatically maps it to your website URL
3. Opens the WebView to the correct page

✅ The scheme is derived from your App Name (lowercase, letters only).

✅ Example mapping:
myapp://products/shoes
→ https://mysite.com/products/shoes

The path segments after the scheme are preserved and appended to your website domain.

Custom scheme format:
  <appname>://<path>

Examples:
  myshop://cart
  → https://myshop.com/cart

  puma://in/en/help
  → https://in.puma.com/in/en/help

3https:// links - one file must go on your website#

This is the part people miss, so read it before testing.

Appwright puts your domain in the app automatically. But Android will NOT open your app from an https:// link until your WEBSITE proves the app belongs to you. On Android 12 and newer, an unproven link just opens the browser - no dialog, no choice. That is why a link can look like it 'does nothing'.

The proof is one small file. Appwright already made it for you: after you build, look in Downloads for assetlinks.json. It contains your package name and your app's signing fingerprint.

Upload it to your website at EXACTLY this address (the folder name starts with a dot):

https://yoursite.com/.well-known/assetlinks.json

Rules — all four must be true:
  1. Served over https (not http)
  2. Content-Type: application/json
  3. NO redirect (a redirect to www breaks it)
  4. Reachable publicly — no login, no Cloudflare challenge

Check it from any computer:
  curl -i https://yoursite.com/.well-known/assetlinks.json

4Publishing on Google Play? Use Play's fingerprint#

Google Play re-signs your app with ITS own key. So the fingerprint inside the assetlinks.json Appwright generated - which is your local key - will not match what users actually install from Play.

If you publish on Play, replace the fingerprint:

1. Play Console → your app → Test and release → Setup → App integrity
2. Copy the SHA-256 from 'App signing key certificate'
3. Put that value in assetlinks.json and re-upload it

You can list BOTH fingerprints in the same file - the local one for APKs you share directly, and Play's for Play installs. That way both work.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourapp.name",
    "sha256_cert_fingerprints": [
      "AA:BB:...",   // your local key (direct APK)
      "11:22:..."    // Play App Signing key
    ]
  }
}]

5Check whether Android accepted it#

After uploading the file, REINSTALL the app (Android only checks at install time, and it can take a minute).

The command below tells you the truth. Look for your domain with 'verified'. If it says 'legacy_failure' or the domain is missing, the file is not being read correctly - go back and check the four rules.

# Does Android consider your domain verified?
adb shell pm get-app-links com.yourapp.name

# Force a re-check without reinstalling (Android 12+):
adb shell pm verify-app-links --re-verify com.yourapp.name

# Google's own checker (open in a browser):
https://digitalassetlinks.googleapis.com/v1/statements:list?
  source.web.site=https://yoursite.com&
  relation=delegate_permission/common.handle_all_urls

6Why it usually fails#

In order of how often each one is the cause:

1. The file is not uploaded, or is at the wrong path. It must be /.well-known/assetlinks.json - with the dot.

1. www vs no-www. Android treats https://example.com and https://www.example.com as DIFFERENT domains. Appwright registers the exact host from your Website URL. If you use both, put the file on both, and tell us which host you entered.

1. A redirect. Many hosts redirect the apex domain to www. That breaks verification even though the file loads in a browser.

1. Published on Play but using the local fingerprint - see the previous step.

1. Not reinstalled after uploading. Android checks at install time.

Custom scheme links (myapp://...) need NONE of this and always work - use them for push notifications and QR codes if you want something working today.

7Testing Deep Links via ADB#

Test your deep links from a PC connected via USB debugging:

1. Enable USB Debugging on your phone
2. Connect via USB
3. Run the commands below.

⚠️ Important: 'am start' with an https link can open your app even when verification has FAILED, because you are handing the link straight to Android. It does not prove a real tap in Gmail or Chrome will work. Only 'pm get-app-links' (previous step) tells you that. Use am start to check your PAGE routing, not your domain setup.

# Test custom scheme:
adb shell am start -a android.intent.action.VIEW \
  -d "myapp://some/page"

# Test website URL:
adb shell am start -a android.intent.action.VIEW \
  -d "https://mysite.com/some/page"

# Verify which app handles it:
adb shell cmd package resolve-activity --brief \
  -a android.intent.action.VIEW \
  -d "myapp://some/page"

8Deep Links in Push Notifications#

When sending a push notification via OneSignal, paste any deep link URL into the 'Launch URL' field. The app will open and navigate directly to that page.

Both URL types work:
✅ https://mysite.com/flash-sale
✅ myapp://flash-sale

OneSignal Dashboard → New Push:

Launch URL: https://mysite.com/flash-sale
  OR
Launch URL: myapp://flash-sale

Both will open the app on the sale page.

9Important: Warm Launch Behaviour#

If your app is already running in the background when a deep link is triggered, Android delivers the link directly without restarting the app - this is called a 'warm launch'.

✅ Your app handles this automatically. The WebView will navigate to the new page even when the app is already open.

⚠️ If deep links only open the homepage, check that:

• Your Website URL in config matches the domain in the deep link
• The path in the custom scheme URL is correct

⚠️ If https:// links do not open the app AT ALL, this is not a warm-launch problem - it is the assetlinks.json step above. Custom scheme links working while https links do nothing is the classic sign.

Warm launch works automatically.
No extra setup needed.