Guides
Android App Links for Your Website App: Make Links Open in the App
Links from emails, WhatsApp and Google open in the browser, not your app, until you set up Android App Links. Here's how assetlinks.json works, the fingerprint mistake almost everyone makes, and how to test it.
You've launched your website as an Android app. Then a customer taps a link to your site in an email, a WhatsApp message or a Google search result, and it opens in Chrome instead of your app. They're signed out, they don't see the app's tab bar, and your password reset or magic link signs them in on the website instead. Android App Links fix this: once they're set up, links to your domain open straight in your app. This guide explains how they work and how to set them up correctly the first time.
Two kinds of deep links
| Custom scheme | Android App Links | |
|---|---|---|
| Looks like | com.yourbrand.app://orders/123 | https://yourdomain.com/orders/123 |
| Setup | None beyond the app itself | A verification file on your website |
| If the app isn't installed | The link doesn't work | Opens your website in the browser as normal |
| Chooser dialog | Sometimes, if another app claims the scheme | Never. Opens your app directly |
| Best for | Links you control, like buttons on your own pages | Links in email, SMS, social and search |
Every Capsule app supports both. The custom scheme is your package name and works as soon as the app is installed. App Links are set up for the exact domain your app loads, so if your app opens www.yourdomain.com, that's the host links must use and where the verification file must live. App Links need one file on your website, covered below.
How App Links verification works
Anyone could build an app that claims to open links to your domain, so Android checks that you own both. When your app is installed, Android downloads https://yourdomain.com/.well-known/assetlinks.json and looks for two things: your app's package name, and the SHA-256 fingerprint of the certificate the app was signed with. If both match, links to your domain open in your app with no chooser. If the file is missing or wrong, Android 12 and later quietly open links in the browser instead.
The fingerprint trap: use Google Play's key
This is where most setups fail. When you publish on Google Play, Play App Signing re-signs your app with Google's own app signing key before it reaches users. The fingerprint Android checks on a Play install is Google's key, not the one used to sign the AAB you uploaded. If you paste the upload key's fingerprint into assetlinks.json, verification fails for every user who installed from the Play Store, and you'll get no error telling you so.
Always copy the fingerprint from Play Console, under the app signing key certificate, not from your build tool.
If you also share the APK directly, outside the Play Store, you can list more than one fingerprint in the same file: Google's app signing key and the key that signed your APK.
Setting up App Links step by step
- 1
Upload your app to Google Play
Internal testing is enough. It doesn't need to be public yet, but Google has to have created your app signing key.
- 2
Copy the SHA-256 fingerprint
In Play Console, open your app, then Test and release, Setup, App integrity, App signing. Copy the SHA-256 certificate fingerprint under App signing key certificate.
- 3
Create assetlinks.json
Capsule's Deep Linking tab gives you the file with your package name already filled in. Paste the fingerprint in place of the placeholder.
- 4
Upload it to your site
Serve it at https://yourdomain.com/.well-known/assetlinks.json over HTTPS, with no redirects and a content type of application/json.
- 5
Reinstall and test
Android verifies links when the app is installed or updated, so reinstall the app from Play to check.
The file itself is short. It looks like this, with your own package name and fingerprint:
[{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.yourbrand.app", "sha256_cert_fingerprints": ["AB:CD:..."] } }]
Where to put the file on popular platforms
| Platform | How to serve /.well-known/assetlinks.json |
|---|---|
| Lovable, Bolt, Vite or React apps | Put the file in public/.well-known/ so it's copied to the site root when you deploy |
| Next.js | Put it in public/.well-known/, or serve it from a route handler with the JSON content type |
| WordPress | Upload it to a .well-known folder in your site root over FTP or your host's file manager, or use a plugin that serves it |
| Netlify, Vercel, Cloudflare Pages | Include it in your build output's .well-known folder. Check that no redirect rule catches it |
| Shopify, Wix, Squarespace | These platforms control the root folder, so custom .well-known files are often not possible. Use the custom scheme for links you control |
How to test it
- Open https://yourdomain.com/.well-known/assetlinks.json in a browser. You should see the JSON straight away, with no redirect to another URL or a login page.
- Use Google's Statement List Generator and Tester to check that the file matches your package name and fingerprint.
- On the phone, open Settings, Apps, your app, then Open by default. Your domain should be listed as a verified link.
- Send yourself a link to your domain in a messaging app and tap it. It should open in the app with no chooser.
What to use App Links for
- Magic links and password reset emails, so users finish signing in inside the app. If you can, use one-time codes instead; see the Google sign-in WebView error.
- Order confirmation and shipping emails that link to the order page.
- Links you share on social media and WhatsApp, so app users land in the app.
- Links in push notifications work without App Links, because the app opens them itself. See push notifications for website apps.
Frequently asked questions
- What is assetlinks.json?
- It's a small file on your website, at /.well-known/assetlinks.json, that tells Android which apps are allowed to open links to your domain. It lists the app's package name and signing certificate fingerprint.
- Why do my links still open in the browser?
- Usually because the fingerprint in assetlinks.json doesn't match the app on the phone. For Play Store installs, use the app signing key fingerprint from Play Console, not your upload key. Redirects or a wrong content type on the file also break verification.
- Which SHA-256 fingerprint should I use?
- The one under App signing key certificate in Play Console's App integrity page. If you also distribute the APK outside Google Play, add that key's fingerprint too.
- Do App Links work if the app isn't installed?
- Yes. They're normal https links, so without the app they simply open your website in the browser.
- Do I need App Links for push notifications?
- No. A notification's link opens inside the app because the app handles it itself. App Links are for links tapped outside the app.