App Development Solutions: Why Your Deep Links Stop Working

Somebody on the marketing team sends a campaign. The link in the message is supposed to open the product on the right screen. For a third of the people who tap it, it opens a browser instead, shows a page that says the content is in the application, and ends there. Nobody files a bug, because nothing crashed. The campaign simply underperforms and the reason never surfaces.
Deep links are the part of mobile work that is easiest to demonstrate and hardest to keep working. They demo beautifully on the developer's phone and fail in a dozen ordinary situations nobody tested.
What a deep link actually is
There are two mechanisms, and confusing them is the root of most of the trouble.
The old mechanism is a custom scheme. The product registers a name, and a link using that name opens it. This works, and it has two fatal properties. Any application can claim any scheme, so there is no ownership. And if the product is not installed, the link goes nowhere at all, with no page to fall back to.
The modern mechanism is a verified web link. The link is an ordinary web address on a domain you control. The operating system checks, at install time, whether that domain has published a file saying this application is allowed to handle its links. If the check passes, taps on that address open the product. If the product is not installed, the address is just a web page, which is exactly what you want.
Almost every problem below is a problem with the second mechanism, because the second mechanism depends on a file on a server, and servers change.
The ways it quietly breaks
The association file stops being served correctly. It is a small file at a fixed path on the domain. It has to return a success status, be served as a specific content type, and be reachable without a redirect. A content delivery network rule, a new security header, a change to how unknown paths are handled, or a redirect from the bare domain to a subdomain will each break it. Nothing in the application changes. The links simply stop opening it, on new installs first, which is why the symptom appears weeks after the cause.
The verification result is cached from install time. The check happens when the product is installed or updated, not when a link is tapped. So a broken file breaks links for people who install after it broke, while everyone who installed before continues to work normally. Two engineers on the same build, one of whom reinstalled yesterday, will disagree about whether the feature works, and both will be right.
The path pattern does not cover the real link. The application declares which paths it handles. The campaign uses a path nobody declared, or the same path with a trailing slash, or an uppercase segment, or a country prefix added later for a new market.
Tracking parameters rewrite the address. Email systems, advertising platforms and messaging clients wrap links in their own redirectors. The address the person taps belongs to the tracking service, not to you. The operating system checks the tracking domain, finds no association with your product, and opens a browser. Your link is at the end of a chain that the check never reaches.
The link is tapped inside an application that will not leave itself. Several large social and messaging products open links in their own internal browser by default. That internal browser is not the system browser and often does not hand the address to the operating system at all. The person sees your web page inside a social application and never reaches the product, no matter how correctly everything is configured.
The screen the link points at cannot be built in isolation. This one is a code problem rather than a configuration problem, and it is the most common of all. The application is written so that the target screen is only ever reached by navigating through two screens before it, and it depends on state those screens set up. Open it directly from a cold start and it has no data, so it shows an empty view or sends the person to the home screen. The link worked. The navigation did not.
What a product that handles this properly does
Every deep link target can be opened from nothing. This is the design rule that matters most. A screen reachable by link must be able to build itself from the address alone: fetch what it needs, handle the case where the person is not signed in, handle the case where the content was deleted, and produce something sensible in each. If reaching a screen requires passing through another screen first, it is not linkable, and no amount of configuration will change that.
Sign in preserves the destination. A link tapped by somebody not signed in should hold the destination, take them through sign in, and then land them where they were going. Dropping them at the home screen after sign in is the single most common deep link disappointment, and it is entirely a code decision.
The web address works as a web page too. Every linkable address should render a real page for somebody without the product installed: the actual content where that is possible, a useful summary where it is not, and an install route. This also means the links survive being shared into contexts that never open applications at all.
The association file is monitored like any other production dependency. A check that runs on a schedule, fetches the file, and confirms the status, the content type, the absence of redirects and the presence of the right identifier. This is five lines of configuration and it catches a class of failure that is otherwise invisible for weeks.
Testing happens on a freshly installed build. Because verification is cached at install, deep link testing on a device that has had the product for months proves nothing. Uninstall, install, then tap.
The test sequence that finds the real problems
Four taps, on a clean install, from four places.
From a plain note or message, to confirm the base case. From an email sent through whatever system marketing actually uses, which is where tracking wrappers appear. From inside a social application, which is where internal browsers appear. And from the same link while signed out, to confirm the destination survives sign in.
Then one more, the one teams skip: uninstall the product and tap the same link. A person who does not have it installed should reach a real page, not a dead end.
Where the time goes
Deep links are usually estimated as a configuration task and turn out to be an architecture task. The configuration is an afternoon. Making every linkable screen able to build itself from an address, and making sign in preserve a destination, touches how navigation works across the whole product.
Teams that build it that way from the start pay nothing extra later. Teams that bolt it on find that the estimate was wrong by an order of magnitude, and that the thing standing in the way is not the link at all.
Appagentix builds mobile applications and the web presence behind them, and treats every screen a link can reach as one that has to work from a cold start.

More on how Appagentix builds mobile applications and the systems behind them: https://appagentix.com/locations/app-development-san-diego/