Deep-link diagnostics
Finding where the journey breaks
Illustrative practice note · Mobile attribution and user-journey troubleshooting
A campaign link is expected to send a user to a specific place in an app. Instead, the user reaches the wrong screen, sees the app store, lands on the home screen or never receives the intended content after installation.
The visible symptom looks simple. The actual issue may sit anywhere in a chain of systems: the campaign URL, redirect behaviour, operating-system association, app configuration, routing logic, install state, attribution setup or reporting.
The practical job is to replace “the deep link is broken” with a testable explanation and a clear next action.
Role represented: Technical Account Manager, coordinating reproduction, technical investigation, customer communication and validation across marketing, mobile Engineering and platform teams.
Working approach: Test one exact journey, locate the first point where expected and actual behaviour differ, then provide evidence that the right owner can act on.
1. Define the expected journey before testing
A deep-link test is unreliable when the expected destination is vague.
Start by writing the expected user journey in one sentence.
Example:
A new Android user taps a paid social campaign link, installs the app, opens it for the first time and arrives on the promoted product page.
Then identify the conditions that matter.
| Test condition | Example |
|---|---|
| Platform | Android or iOS |
| App state | Installed, not installed, previously installed or reinstalled |
| Source | Paid social, email, web page, QR code or another app |
| Link type | Universal link, app link, custom scheme or deferred deep link |
| Intended destination | Product page, offer, content item or onboarding step |
| Test environment | Production, staging or sandbox |
| Device and app version | Exact device model, operating-system version and app build |
| Attribution expectation | Campaign, channel or parameter that should be recorded |
A test without these details can produce an answer that is technically correct but irrelevant to the customer’s actual issue.
2. Separate the journey into observable stages
A campaign-to-app journey has several stages. Test them separately.
| Stage | Question to answer | Useful evidence |
|---|---|---|
| Link creation | Does the URL contain the intended destination and required parameters? | Original URL and decoded parameters |
| Redirect | Does the link resolve to the expected destination for this device and state? | Browser behaviour, redirect path and timestamp |
| App association | Does the operating system recognise that the domain or link belongs to the app? | Domain association files, app configuration and device behaviour |
| App opening | Does the app open from the link? | Screen recording or reproducible test |
| Route handling | Does the app parse the link and route to the intended destination? | App logs and engineering confirmation |
| Deferred routing | If the app is not installed, is destination context preserved through installation? | Fresh-install test with exact conditions |
| Attribution | Is the campaign context recorded according to the agreed measurement rules? | Platform logs and reporting evidence |
The first point where expected and actual behaviour differ is usually where investigation should begin.
3. Use a controlled test matrix
A link may work for one user state and fail for another. A single successful test is not enough.
| Scenario | Expected behaviour | Result | Evidence to collect |
|---|---|---|---|
| App installed, user taps link | App opens at the intended in-app destination | Pass or fail | Device, app version, timestamp and screen recording |
| App not installed, user taps link | User installs, then reaches the intended destination on first open | Pass or fail | Store path, first-open behaviour and test timestamp |
| User has a previous installation | App opens without losing relevant campaign context | Pass or fail | Reinstall state, device ID where permitted and routing result |
| Link opened in an in-app browser | Expected redirect and app-opening behaviour occurs | Pass or fail | Source app, browser behaviour and screenshot |
| Link opened on iOS and Android | Behaviour matches the defined platform-specific expectation | Pass or fail | Device and build details for each platform |
This makes the issue visible. It also prevents teams from treating an Android-only, deferred-link issue as a general link failure.
4. Check the most common break points
The wrong link or parameter
The campaign may use an outdated URL, wrong destination parameter, malformed encoding or a link created for another environment.
Check the original click URL, not only the final page seen by the tester.
The app is not associated with the domain
For universal links and Android app links, the operating system must recognise the connection between domain and app. A correct campaign URL cannot solve a missing or incorrect app association.
The app opens but ignores the destination
The link can successfully open the app while routing fails inside the app. This often happens after navigation changes, wrapper refactors or changes to how parameters are parsed.
The result can look like a successful deep link because the app opens. The user still lands in the wrong place.
Deferred context is lost after installation
A new user may reach the app store correctly, install the app and then open the app without the original destination context.
This is a different issue from a standard deep link. It needs a clean-install test and evidence from the deferred-routing or attribution configuration.
Sandbox and production are mixed
A staging build, test domain or sandbox configuration can behave differently from the actual campaign environment. Always record exactly which build and environment were tested.
5. Turn a vague problem into an actionable update
A useful customer update should state what is known, what is not yet known and who owns the next step.
Example:
Subject: Deep-link validation update — Android installed-user route confirmed; deferred journey still open
Hi team,
The Android installed-user test passes: the campaign link opens the current production build and routes to the expected product page.
The fresh-install journey does not yet preserve the intended destination after installation. The user reaches the app store correctly, but the first app open lands on the home screen.
Evidence collected
- Production campaign link tested at [timestamp]
- Android device and app build recorded
- Installed-user journey passes
- Fresh-install journey reproduces the issue
- The original destination parameter is present in the click URL
Next steps
- Mobile Engineering: review deferred-route handling on first app open
- Marketing: keep the current campaign link unchanged until the routing result is confirmed
- I will: retest the fresh-install journey once the updated build is available and document the result
The campaign can continue for installed users. The deferred destination should remain unapproved until the clean-install test passes.
Best, Giulia
What this approach delivers
Deep-link troubleshooting becomes faster when the issue is treated as a user journey with observable stages, rather than as one technical feature.
The outcome is a reproducible test, evidence for the affected component, a named owner and a clear decision about the impact on the customer experience and campaign measurement.