BlogAndroid

How to test deep links on Android with adb, from routing to deferred installs

· 9 min read · By the Strait team

A practical walkthrough for testing Android deep links with adb. Fire a link at your app without tapping anything, check App Links verification, reset and re-verify, read logcat, test the browser hand-off and know which tests adb can't do.

Tapping a link on a phone is the test that matters in the end, but it's a slow way to find bugs. When a tap goes wrong you can't tell which step failed: the link domain, Android's verification, your intent filter, the browser, or your routing code.

adb, the Android Debug Bridge that ships with the Android SDK platform tools, lets you test each step on its own. This post goes through the commands we use, in the order we use them, with what you should see and what it means when you don't. The last section covers what adb can't test, because deferred deep links need a real install from Google Play. Once each command works, our Android deep link test plan runs them across the closed, background and not-installed states.

You need a phone with USB debugging turned on (or an emulator), adb on your path, and a build of your app installed. Run adb devices first. If your phone isn't listed as device, accept the debugging prompt on the phone and try again.

The fastest test skips the browser and the chat app completely. You ask Android's activity manager to open a URL with the VIEW action, the same thing that happens when another app hands Android a link.

Terminal
# A custom scheme link (what a browser hand-off delivers)
adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42?color=red"

# An https link on your link domain (what a verified App Link delivers)
adb shell am start -W -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://hilltop.strait.link/summer"

What the flags mean:

  • -W waits until the launch finishes and prints the result, including which activity started and how it was launched.
  • -a android.intent.action.VIEW is the action every link uses.
  • -c android.intent.category.BROWSABLE adds the category a browser adds. Android's own verification guide uses this form of the command (Android Developers: Verify App Links).
  • -d is the URL. Quote it, or the shell will eat the & and ? characters.

What you should see: your app opens on the screen for product 42. Run it twice: once with the app closed (a cold start) and once with the app in the background. Routing bugs often show up in only one of those cases. A cold start delivers the link with the launch, and a warm app receives it as a new intent, so code that only reads the launch link misses the second one.

If the browser opens for the https link (or, on Android 11 and older, a chooser appears), Android doesn't consider your app verified for that domain. On Android 12 and later an unverified https link opens in the default browser (Android 12 behaviour changes). Go to step 2.

If the browser opens for the custom scheme link, no activity in the installed build declares that scheme. Check the intent filter in the merged manifest (Android Studio shows it under Merged Manifest). A common cause is a scheme declared only in a debug or flavour manifest.

You can add your package name at the end of the command to force a specific app. That's useful when two builds (debug and release) are installed side by side:

Terminal
adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42" com.yourco.app.debug

App Links open your app with no browser in between, but only after Android has verified your link domain against the app. On Android 12 and later, adb shows the result per domain:

Terminal
adb shell pm get-app-links com.yourco.app

Android's guide lists the states this can print (Verify App Links). The ones you'll meet in practice:

State What it means What to do
verified The domain passed verification for this app Nothing; https links should open the app directly
none Nothing recorded yet Wait a few minutes, or trigger a fresh check (step 3)
approved / denied Forced by a shell command Reset it (step 3) before you trust the result
legacy_failure The older verifier rejected the domain Check the file and fingerprints, then re-verify
1024 or higher A verifier-specific error code Almost always the file or a fingerprint; see below

When the state isn't verified, the cause is nearly always one of three things. The assetlinks.json file on the domain can't be fetched cleanly (a redirect, a login wall, a bot challenge or the wrong content type). The SHA-256 fingerprint of the installed build isn't in the file. Or the intent filter in the app doesn't name the host, or lacks android:autoVerify="true". Our post on App Links verification mistakes goes through each one, and Android App Links verification failed works back from each state to its cause. The free assetlinks.json checker fetches your file the way Android does and points at the problem.

On Strait, your link domain serves assetlinks.json for you, built from the package name and fingerprints you save in Dashboard → Apps & stores, so the file side is usually fine once every fingerprint is listed. The App Links docs list exactly what we host.

Step 3: reset and re-verify after a fix

Android checks verification when the app is installed. After you fix the file or add a fingerprint, you don't have to reinstall on Android 12 and later. Reset the state, ask for a fresh check and read the result:

Terminal
adb shell pm set-app-links --package com.yourco.app 0 all
adb shell pm verify-app-links --re-verify com.yourco.app
# wait a minute or two
adb shell pm get-app-links com.yourco.app

The first command puts the app back to the state it's in before anyone chose default apps for its domains. The second runs the verification again. Android's guide notes the verifier needs a few minutes to finish its requests, so don't read the result immediately.

Two habits save time here:

  • Test the build you'll ship. A debug build is signed with your debug key, a sideloaded release build with your upload key, and a build installed from Google Play with Google's app signing key. Each has a different fingerprint, and verification is checked against the one that's installed.
  • Don't force-approve and forget. pm set-app-links can mark a domain as approved, which makes the link open your app on your phone and nowhere else. Reset it before you call verification fixed.

Step 4: watch what your app receives with logcat

When the right screen doesn't open, you need to know whether the link reached your app and what it looked like when it got there. Filter logcat to your app's process while you fire a link:

Terminal
adb logcat --pid=$(adb shell pidof -s com.yourco.app)

Log the incoming URL in the place your app receives links: onCreate and onNewIntent for a native activity, or the link callback of your framework's deep-link library. Then fire the same link from step 1 and compare. Common findings:

  • The URL arrives, but the query string is gone. Usually the shell ate it because the -d value wasn't quoted.
  • The URL arrives with an extra parameter. With Strait, a browser hand-off adds a tap id (strait_click) so the app open can be joined to the tap. The SDK removes it before your routing code sees the URL; if you read the raw intent yourself, ignore it.
  • Nothing arrives on a warm start. The activity's launch mode sends the link to onNewIntent, and the code only reads the link in onCreate.

Step 5: test the browser hand-off

Step 1 tests your app. It doesn't test what happens when a link is tapped in a browser that isn't verified for your domain, or in a chat app's in-app browser. In those cases the link server, not Android, decides how to get to your app. On Android that usually means an intent:// URL with a fallback to Google Play, as described in Google's guide to Android intents with Chrome.

You can open a link in a specific browser from adb, which loads it the way a tap from another app would:

Terminal
adb shell am start -a android.intent.action.VIEW -d "https://hilltop.strait.link/summer" com.android.chrome
adb shell am start -a android.intent.action.VIEW -d "https://hilltop.strait.link/summer" com.sec.android.app.sbrowser

The package names are Chrome and Samsung Internet. Expect differences between them: browsers apply their own rules about when a page may open an app. Our post on Samsung Internet and intent links covers the most common case, where the Play listing opens even though the app is installed.

To see what a link server would answer without loading anything on the phone, ask the engine. Strait's dry-run endpoint returns the decision, the location and a plain-English reason, and records no tap:

Terminal
curl "https://strait.link/v1/simulate?url=https%3A%2F%2Fhilltop.strait.link%2Fsummer&ua=android" \
  -H "Authorization: Bearer $SECRET_KEY"

The free intent link builder builds the same intent:// URL our engine builds, so you can paste the result into a browser on the phone and compare. Will it open? shows the decision for a browser and a link without an account.

Finally, do one real tap per channel you care about. Send the link to yourself in Google Messages, Gmail and WhatsApp and tap it in each. Instagram, and some WhatsApp versions, open links in their own in-app browsers, where Strait shows an Open in app page first.

A deferred deep link opens the right screen on the first launch after an install. On Android, Strait carries the link through the install with the Google Play Install Referrer, which Google Play provides for an install that came from Play. A build you install with adb install or from Android Studio didn't come from Play, so there is no referrer to read and the app opens on its home screen. That's expected and doesn't mean anything is broken.

To test a deferred link for real:

  1. Upload a build to a Google Play internal testing track and add yourself as a tester.
  2. Uninstall the app from the phone.
  3. Tap your link, install from the Play listing it opens, then open the app.

What you should see: the first screen is the link's screen. In the SDK's result, kind is deferred and route is install_referrer. The Android test guide has the full sequence and the common errors, such as a workspace set to send people without the app to your website instead of Google Play. Our test mode for checking a first open from a debug build is built but not released yet, so for now the Play internal track is the way to test.

A one-screen checklist

  1. adb devices lists the phone.
  2. am start with the custom scheme opens the right screen, cold and warm.
  3. am start with the https link opens the app, not a browser or a chooser.
  4. pm get-app-links says verified for your link domain, on the build you'll ship.
  5. logcat shows the URL your routing code receives.
  6. Chrome and Samsung Internet both reach the app from the hand-off.
  7. A real tap works in each chat app you care about.
  8. A Play internal-testing install opens the link's screen on the first launch.

Sources and how we checked

  • Android Developers, Verify Android App Links: the am start test command, pm set-app-links, pm verify-app-links --re-verify, pm get-app-links and the meaning of each verification state. Read on 5 October 2026.
  • Google, Android Intents with Chrome: the intent:// URL format and its browser fallback.
  • The hand-off URL, the strait_click tap id, the dry-run endpoint and the Play Install Referrer route come from our engine's code and our Android test guide.
  • The adb flags (-W, -a, -c, -d, a trailing package name, logcat --pid) are standard platform-tools options; run adb shell am help on your own phone to see the exact set your Android version supports.