# Connect search, web, and app with deep links

- **Canonical URL:** https://playbook.affpartners.io/en/practices/discoverability-links/index.html
- **Markdown version:** https://playbook.affpartners.io/en/practices/discoverability-links/index.md
- **Module:** ASO & SEO
- **Time:** 2 hours for the first route

A deep link is a precise address inside the app. It should preserve the original task after a tap, sign-in, or even a new install, and provide a clear fallback when the destination is unavailable.

## Outcome

A continuous-journey map and iOS/Android test matrix covering installed, signed-out, not-installed, and outdated-app states.

## A link should lead to the right room, not just the building

Someone reading a guide about their status expects the tap to open that status. The home screen makes them find the way all over again. A good route remembers the destination through sign-in and offers a safe alternative when the screen is unavailable.

## What you will need

- **One route:** A specific web page or message, a destination screen in the app, and one expected action.
- **Development:** An iOS and Android developer, or a links owner who knows the supported paths and the sign-in behavior.
- **Testing:** Devices on both platforms, the app installed and uninstalled, test accounts, and analytics events.

## Terms in plain language

- **Deep link — A link to a specific app screen:** Definition: After a tap, the user lands in the promised journey rather than on the home screen. Example: A push about a saved lesson opens that lesson directly.
- **SEO — Improving website pages for search:** Definition: Useful pages answer real user questions and help people find the product through search engines. Example: One page answers one question, explains constraints, and leads to a relevant app journey.
- **Analytics event — A record of a specific user action:** Definition: The app sends an event when a user opens a screen, taps a button, or completes an action. Example: registration_started and registration_completed reveal how many people abandon registration.
- **Conversion — The share of people moving to the next step:** Definition: Shows how many people who started a step completed it or reached the next one. Example: 80 registrations completed from 100 started: 80 ÷ 100 × 100% = 80% conversion.

## When to use it

Clicks from search, the site, email, or push open the home page, get lost after sign-in or a fresh install, and leave the target action unmeasurable.

## What to describe before development

First map the behavior for every user state. The same link must not silently dead-end when the app or the screen is missing.

- **Route map**
  - **Source:** Match the source, the promised screen, the required sign-in, and the target action after opening.
  - **If access is unavailable:** Start with the single most important link and write down the expected behavior for the five states by hand.
- **Technical errors**
  - **Source:** Collect successful opens, fallback routes, unknown paths, and the app version for every link.
  - **If access is unavailable:** Without events, keep a manual test log with the device, version, steps, and a video of the error.
- **Taps and actions**
  - **Source:** Join the tap, the destination-screen open, and the completed action with one route identifier.
  - **If access is unavailable:** Add a technical route_id parameter to the link and the screen event before the next launch.

## Set up a continuous route

1. **Choose one task and screen.** Start with a specific promise and a final result. Do not create a universal “open the app” link.
   - **Where to do it:** In the first row of the route map.
   - **Example:** The “How to check status” article → the specific status screen → the user sees the next step.
2. **Describe the user states.** Write down the behavior when the app is installed, the user is signed out, the version is outdated, or the app is missing.
   - **Where to do it:** In the rows of the test matrix.
   - **Example:** After sign-in the original route ID survives and opens the status, not the home screen.
3. **Add a safe fallback.** If the destination screen is unavailable, show a relevant web page, the store, or help. Do not leave a blank screen and an unexplained error.
   - **Where to do it:** In the link router settings.
   - **Example:** App not installed → the web guide stays available, plus a clear button to the store.
4. **Test on real devices.** Check iOS and Android, cold start, sign-in, an old version, and entry from different sources. Record the actual result for every row.
   - **Where to do it:** On the devices and versions the audience actually uses.
   - **Example:** Android 13 from the browser, iOS 17 from email, and both platforms after signing out.
5. **Join the tap to the outcome.** Pass route_id — the route identifier — and record the destination-screen open, the fallback path, errors, and the target action.
   - **Where to do it:** In the link parameters and analytics events.
   - **Example:** A tap on the site → the app opens → the status is viewed → the next step, with route_id=status_help.

## Practical examples

- **Sign-in does not erase the destination:** The status link asks the user to sign in, keeps the route_id, and after sign-in opens the promised screen instead of the home page.
- **No app — no dead end:** The user stays on the useful web guide and gets a clear link to the store. After installing, the route continues — or a web alternative opens safely.

## Finished artifact: Verification matrix for the “Open status” route

Walk every row on iOS and Android. “The app opened” is not enough — the promised screen must appear.

| State | Expected path | Fallback route | Result |
| --- | --- | --- | --- |
| Installed, signed in | Straight to the status screen | Not needed | Check iOS/Android |
| Installed, signed out | Sign-in → status screen | Preserve the destination | The route ID is not lost |
| App not installed | Store page | The web answer stays available | No error shown |
| Outdated version | A supported screen or an update prompt | Web version | No dead end |
| Screen removed | A current alternative | Help section | A “route not found” event |

The scenario is ready when the tap shows the promised screen in every supported state, and route errors land in the report with the version and platform.

## Deep-link checklist

The link is ready only after the full path is tested — not after one lucky open on the developer's device.

- [ ] There is a specific promised screen and a target action.
- [ ] The original destination survives sign-in and a cold start.
- [ ] There is a fallback for a missing app, an old version, and a removed screen.
- [ ] The link carries no sensitive user data.
- [ ] The tap, screen, errors, and action are joined by the route ID and tested on iOS/Android.

## How to know the route works

- **Technical success:** The share of taps that opened the promised screen or a correct fallback without an error.
- **Context preserved:** After sign-in or a fresh install, the user continues the original task instead of landing on the home screen.
- **Useful action:** Users complete the action after the tap, while “route not found” errors and back-navigation decline.

## Key rule

A deep link counts as working only when users reach the promised screen in every supported state — not just in the developer's test.

---

- [HTML version](https://playbook.affpartners.io/en/practices/discoverability-links/index.html)
- [All practices](https://playbook.affpartners.io/en/)