Skip to content
webtoapkfree

What is assetlinks.json and does my WebView app need it?

assetlinks.json proves your site and Android app belong together. A plain WebView app doesn't need it; App Links, TWAs and passkeys do.

GuidesNookesh Karri

Light cover card with the title 'What is assetlinks.json and does my WebView app need it?' in dark text and a green accent bar

assetlinks.json is a small JSON file on your website, at /.well-known/assetlinks.json, that tells Android which apps the site trusts. A plain WebView app that just loads your pages doesn’t need it. You need the file only when you want links to your domain to open straight in your app, when you ship a Trusted Web Activity, or when your app and site share saved logins or passkeys.

What assetlinks.json is

The file is the format of Digital Asset Links, a Google protocol that lets an app or website make “public, verifiable statements” about other apps or websites, as the Digital Asset Links getting started guide puts it. A website uses it to say: this Android app, signed with this key, speaks for me.

Android reads those statements to decide whether to trust the connection. The Android App Links overview says Android uses Digital Asset Links statements hosted on your website to set up a verified association between the site and the app.

Here is the shape of the file, based on the example in Android’s assetlinks configuration guide:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]
  • relation says what you’re allowing. handle_all_urls means “open my links in this app”.
  • package_name is your app’s application ID, the reverse-domain name like com.example.shop.
  • sha256_cert_fingerprints lists the SHA-256 fingerprints of the certificate that signs the app. The field accepts more than one, for example a debug key and a release key.

Does a WebView app need assetlinks.json?

A WebView app does not need the Digital Asset Links file to show your website. Android’s WebView documentation describes WebView as a View that displays web pages as part of your activity layout. No step in that process looks for a Digital Asset Links file, so a missing file can’t cause a blank screen or a load error.

The file matters when something outside your app needs proof that the site and the app belong together. That happens in three cases:

What you want Needs the file? What breaks without it
WebView app that loads your site No Nothing
Links to your domain open in your app (App Links) Yes, handle_all_urls Links open in the browser
Trusted Web Activity (PWA in Chrome, full screen) Yes A browser bar appears at the top
Shared passwords or passkeys between site and app Yes, get_login_creds Passkeys don’t work in the app

My take: if your app is a WebView wrapper with no link handling, skip the file. Add it the day you want links from Gmail or WhatsApp to land inside the app.

App Links are the reason most people meet this file. The App Links overview calls them a deep linking capability in Android 6 and later that opens your verified website URLs in your app without asking the user to pick an app. They need Android 6 (API level 23) or later on devices with Google services.

What happens without verification depends on the Android version. According to Android’s deep links guide, on Android 12 and higher, web links that are not verified App Links generally open in a web browser by default. Older versions might show an “Open with” dialog instead.

A WebView app with an intent filter for https://example.com but no valid file behaves like this on a recent phone: the user taps your link in an email, and Chrome opens. Your app never gets the chance.

Trusted Web Activities and Credential Manager

A Trusted Web Activity always needs the file. The Chrome TWA quick start says the capability is restricted to websites you own, proven with Digital Asset Links. If verification fails, the site opens as a Custom Tab with browser UI at the top. That toolbar is the most common sign of a broken file. I covered the full setup in What is a Trusted Web Activity.

Credential Manager sign-in also relies on the file. Android’s Credential Manager prerequisites say Digital Asset Links are required for passkeys and strongly recommended for passwords. You add the delegate_permission/common.get_login_creds relation so the app and site can share credentials. If your site uses Google sign-in inside a WebView, read Google sign-in in a WebView first, since that has its own blocker.

How to host assetlinks.json correctly

Hosting the file correctly means one URL, one content type and zero redirects. The configuration guide lists the rules:

  1. Publish it at https://your-domain/.well-known/assetlinks.json.
  2. Serve it over HTTPS with Content-Type: application/json.
  3. Return it without any 301 or 302 redirects.
  4. Put a copy on every host your links use. www.example.com and example.com each need one.

The Credential Manager page adds two checks: the server must answer with HTTP status 200, and robots.txt must allow /.well-known/. Static hosts often hide dot-folders, so open the URL in a private browser window to confirm it loads.

Which SHA-256 fingerprint to use

Use the fingerprint of the key that signed the copy installed on the user’s phone. Most broken setups get this wrong.

You can read a fingerprint from your own keystore with keytool -list -v -keystore my-release-key.keystore, per the configuration guide. The same guide warns that with Play App Signing, your local fingerprint usually won’t match the one on users’ devices. Google re-signs the release, so take the ready-made JSON snippet from Play Console under Release > Setup > App signing.

If you share an APK directly and also publish on Play, list both fingerprints. The difference between the two keys is explained in Upload key vs app signing key and Play App Signing.

WebToAPK Free signs your APK and AAB in the browser with your own key, and the key is never uploaded. Its documented options are the app name, package name, icon, colour, theme, navigation and content sections, so none of them adds link handling to your domain. For a basic app built there, you don’t need the file. If you later add App Links in your own Android project, the package name and key you used must match the file. The signing and updates guide explains why keeping that key safe matters.

You test the setup on a real device with adb. The App Links verification guide says installing on Android 6.0 or higher starts verification automatically. Wait at least 20 seconds, then run:

adb shell pm get-app-links com.example.shop

Each domain shows a state such as verified, none or legacy_failure. After a fix, run adb shell pm verify-app-links --re-verify com.example.shop.

The troubleshooting guide lists the mistakes that come up again and again:

  • Lowercase fingerprint. The signature should be in upper case.
  • Debug build, release fingerprint. Testing a debug build while the file lists only the release key.
  • Missing android:autoVerify="true" on the intent filter.
  • Redirects. Sending http://example.com to https://example.com, or example.com to www.example.com, stops the system verifying any App Links for your app.

One limitation to know: on Android 15 and higher, changes to the file can take up to seven days to reach all devices, says the verification guide. Android 14 and lower don’t re-check in the background. Test after every change, and don’t expect users to see a fix the same day.

If you’re also routing other sites’ links out of your WebView, see Open external links in the browser.

FAQ

Does a WebView app need assetlinks.json to load my website?

No. A WebView renders whatever URL your app loads, and nothing in that process checks a Digital Asset Links file. You only need the file when you want verified App Links, a Trusted Web Activity, or shared sign-in through Credential Manager.

Where do I put assetlinks.json?

At https://your-domain/.well-known/assetlinks.json, served over HTTPS with the content type application/json and no redirects. If your links cover several domains, each domain needs its own copy.

Which SHA-256 fingerprint goes in the file?

The fingerprint of the certificate that signed the copy on the user’s phone. If Google Play re-signs your app with Play App Signing, use the snippet from Play Console under Release > Setup > App signing, and add your own key too if you also share APKs directly.

Usually the fingerprint doesn’t match, the file sits behind a redirect, or the intent filter lacks android:autoVerify=“true”. On Android 12 and higher, links that fail verification open in the browser by default.

Can I add the file for a website I don’t own?

No. The file has to be hosted on the domain itself, so only someone who controls that site can publish it. That is the point: it proves the site owner approves the app.

Sources