Deep Links

Your friend sends you a link to a rain jacket. You tap it, and instead of the jacket, the shopping app opens on its Home screen. Or it opens the website and asks you to log in again. Or it opens the right product, but pressing Back throws you out of the app. You shrug and close it. The marketing team paid for that click, and nobody will ever know why it didn’t turn into a sale.

Links into apps are everywhere: newsletters, order emails, SMS, QR codes on posters, ads, Instagram posts, push notifications. They connect the outside world to one exact screen in the app, and they cross many systems on the way: the email tool, the browser, the operating system, the website and the app. That’s exactly where bugs hide. By the end of this lesson you’ll know how deep links work, which situations to test, and how to fire links at a phone in seconds.

How it works

A deep linkDeep linkA link that opens a specific screen inside an app instead of just its home screen.Open in glossary → is a link that opens a specific screen inside an app, not just the app’s start screen. “Open Pinecone” is a normal link. “Open Pinecone on product 42” is a deep link.

Two kinds of links: custom schemes and https links

There are two ways to build a deep link, and testers meet both.

A custom scheme is like a nickname that the app registers on the phone: “send me everything that starts with pinecone://”. It’s simple, but it has two problems: if the app isn’t installed, the link is dead, and another app could register the same nickname.

Universal Links (Apple’s name) and App Links (Android’s name) are normal https:// web addresses. If the app is installed, the phone opens the app. If not, the same link simply opens the website. To stop any random app from grabbing pinecone.example links, the website has to vouch for the app with a small verification file:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.pinecone.app"],
        "components": [{ "/": "/product/*" }, { "/": "/orders/*" }, { "/": "/go/*" }]
      }
    ]
  }
}

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.pinecone.app",
    "sha256_cert_fingerprints": ["14:6D:E9:83:...:A5"]
  }
}]

Deferred deep links: when the app isn’t installed yet

A normal link can’t survive an app install. You tap an ad for “10% off your first tent”, go to the store, install, open the app… and land on a generic welcome screen. The offer is gone.

A deferred deep link fixes this. The link first goes through a link service that remembers what you wanted. After installation, the app asks “was this person sent here by a link?” and opens the offer on first launch. Android has a built-in helper for this (the Play Install Referrer). iOS has no built-in equivalent, so link services (Branch, AppsFlyer, Adjust and similar) use their own matching, which is not 100% reliable. Firebase Dynamic Links, which many older apps used, was shut down in 2025, so old links that still point to it are worth a check.

The tricky part for testers: the offer must open exactly once. Not zero times, and not on every launch. See also Onboarding, which usually runs right before.

Try it: what happens when you tap?

Pick a link type, whether the app is installed, and where the link was tapped:

Where links come from

The same link can behave differently depending on where it’s tapped. A good test plan covers the real sources:

Example requirements

Criteria 1 (both domains), 3 (parameters), 4 (continue after login) and 6 (Back) are the ones developers most often forget, because nobody writes them down. If your story doesn’t mention them, ask.

What usually goes wrong

Find the bug

Pinecone, an outdoor gear shop, has six deep-link bugs. On the left are links as they would arrive by email, SMS, QR code, push and ads. Change the device state between tests like a real tester would:

• Tap every link with the app killed, then again with it in the background (open the app and press Home).
• Log out, then try the order links.
• Uninstall the app and tap the ad.
• After every link, press Back and see where you end up.
• Watch the device log.

Test scenarios

Deep links multiply quickly: every link × every app state × logged in or out. Use the scenarios below as a menu, and agree with your team which combinations matter most.

Functional

• Every supported link type opens the right screen with the right content: products, categories, orders, search results, campaigns, password reset (Password Reset).
• App states: open in the foreground, in the background, and not running (killed). The killed case is a separate code path (a cold start) and breaks most often. Read Background and Foreground for how to kill an app properly and why the OS does it on its own.
• Logged in vs logged out: links to private screens ask for login and then continue to the target. Links to public screens don’t ask for login at all.
• Installed vs not installed: https links fall back to the website. Campaign links survive the install (deferred deep links) and open once.
• Back and Up: after the link, Back goes to a sensible place. Test from a cold start and from the background.
• Tabs: a link to an order selects the Orders tab (or wherever orders live), so the bottom navigation matches the screen.
• Both domains: pinecone.example and www.pinecone.example, and any short-link or tracking domain the marketing team uses.

Negative

• Product, order or campaign ID that doesn’t exist or was deleted.
• IDs in the wrong format: /product/abc, /product/-1, /product/ with nothing after it.
• Unknown paths: /sale2023, /product/42/reviews if reviews have no deep link.
• An expired campaign or a password reset link that was already used.
• A link to an order that belongs to a different user (log in as user B and open user A’s order link).
• The app is installed but outdated and doesn’t know a new link type yet.

Edge cases

• Query parametersQuery parameterData in a URL after the ?, like ?q=mug&sort=price, often used to keep search and filter state.Open in glossary →: ?utm_source=email (often with utm_medium and utm_campaign too), ?ref=ad, parameters in a different order, unknown parameters, a #fragment at the end.
• Upper case and trailing slashes: /Product/42, /product/42/.
• Special characters: search links like /search?q=rain%20jacket or q=Zoë.
• Tapping a link while a modal, a payment sheet or an unsaved form is open. Does the app warn before throwing away the user’s input?
• Two links quickly one after another. The second one should win, without a stack of duplicate screens.
• A link that arrives during onboarding, the login screen, or a forced update screen.
• Deep link while logged in as a different user than the one the email was sent to.

UI & usability

• The target screen shows a loading state while it fetches data, not an empty screen.
• “No longer available” screens offer a way forward (similar products, Home).
• Web fallback pages work on a phone and show a clear “Open in app” / “Get the app” banner.
• iOS shows a small ”◀ Mail” (or ”◀ Messages”) button in the status bar after a link. Tapping it should return the user to where they came from.
• The link preview (title and image) looks right when the link is pasted into a chat app.

Security

• Links never log the user in or change data without confirmation. pinecone://transfer?amount=500 must not move money on its own.
• Links can’t show data the user isn’t allowed to see. That’s an IDORIDORInsecure Direct Object Reference: reaching another user's data by changing an ID in a URL or request.Open in glossary → bug, see Web Security Basics.
• One-time tokens (password reset, email confirmation, magic login links) work once, expire, and are not in custom-scheme links, which other apps could intercept.
• Unknown or malformed parameters don’t crash the app or get displayed as raw text (try <b> or a very long value).

Accessibility

• After the link opens, a screen readerScreen readerSoftware that reads the screen aloud for blind and low-vision users, like VoiceOver or TalkBack.Open in glossary → starts on the new screen’s title, not somewhere in the middle.
• “Open in app” banners on the website are real buttons with a clear name, reachable with the keyboard.
• “Not available” and login prompts are announced, not only shown visually.

How to open links while testing

You don’t need to send yourself an email for every test. Each platform can fire a link at a phone directly.

# Open a link as if it was tapped (Android decides: app or browser)
adb shell am start -W -a android.intent.action.VIEW -d "https://pinecone.example/product/42"

# Force it into a specific app (skips the verification check, so don't use it to test verification)
adb shell am start -W -a android.intent.action.VIEW -d "pinecone://orders/8812" com.pinecone.app

# Links with & need quotes around the whole command, or the device shell cuts them off
adb shell 'am start -W -a android.intent.action.VIEW -d "https://pinecone.example/product/42?utm_source=email&utm_medium=newsletter"'

# Android 12+: is App Link verification OK for each domain?
adb shell pm get-app-links com.pinecone.app

# Kill the app first to test a cold start
adb shell am force-stop com.pinecone.app

# Open a link in the booted simulator
xcrun simctl openurl booted "https://pinecone.example/product/42"
xcrun simctl openurl booted "pinecone://orders/8812"

# Kill the app first to test a cold start
xcrun simctl terminate booted com.pinecone.app

Example test cases

Mobile vs web

Checklist

Check your understanding