A friend sends you a card: we're one vote short, tap to add yours. You tap. The mini-program opens on its home screen, the vote is gone, and you have to find the group again from scratch. Nothing crashed. The button worked. The link just forgot what it was carrying.
We've shipped that bug more than once, and it's rarely a broken button. It's a link designed as an address when it should've been a sentence: open this, at this state, for this person, from this place. Years of web URLs trained us to treat links as locations. Inside a super app, a link that carries no context is barely a link at all — it's just a way to open the front door.
A link is a sentence, not an address
Every entry point hands you a small envelope of context before the first screen renders. There's the payload you control — an item id, a group id, a campaign tag, who shared it — and there's the host's own metadata, like a scene value that tells you whether this came from a QR sticker, a chat, or a saved shortcut. WeChat calls those scene values; Alipay has its own equivalent; a Telegram bot gets a start payload on the first /start. Different names, same idea: the host already knows something about how you arrived, and you should read it instead of guessing.
The practical move is to make sharing stateful. When someone shares from a product screen, the card should carry that product's id and land the recipient on that exact screen, not on a homepage with a vague check this out. When a campaign sends people in, the first screen should be the thing the campaign promised. That sounds obvious until you audit a real app and find half the cards pointing at the root path.
One rule we learned the hard way: keep identity, price and permission out of those parameters. Anything in a link is client-supplied. Treat the payload as a hint about where to go, and let the server decide what the person is actually allowed to see.
Two paths, one payload
Here's where most teams get caught. There isn't one way in, there are two, and they behave differently.
A cold start — the mini-program wasn't running — hands the payload to the launch lifecycle. You read it once, decide the route, and render the target screen. Fine. But if the mini-program is already open in the background, a fresh link doesn't relaunch it. It resumes. The new payload arrives on the resume hook, the current page doesn't reload, and unless you explicitly handle that hook, the person stays on whatever screen they left ten minutes ago. That's the tap did nothing bug, and it isn't a crash, so it sails through testing.
So handle both: parse and route at launch, and parse and route again every time the app comes forward. Same small function, two call sites. Skip the second one and roughly half your deep links quietly do nothing.
| Entry | What it carries | Lands on | Where it breaks |
|---|---|---|---|
| Share card from a chat | Item id, group id, who shared | That exact item or group, with their state applied | Card points at the home path; the context never leaves the sender |
| QR code with a scene value | Scene id, campaign, placement | A campaign-specific first screen | Scene param gets stripped when the link is copied out of the host |
| Ad or SMS link | Campaign, creative, a short payload | The offer the ad actually promised | External browser can't open the host scheme; the tap hits a dead end |
| Push or subscription message | A reason and a target screen | One specific screen, not the inbox | Template limits drop the custom field; tap opens a generic page |
| Already-open mini-program | A fresh payload on resume | The new target, decided on resume | The resume hook isn't handled, so the old screen just sits there |
Where attribution quietly dies
Now the honest part. Assume some of it will go missing. Payloads get truncated: length caps, special characters, an encoding step you didn't expect, a host that rewrites a shared link on the way out. Hosts also gate external launching. A link inside a browser or an SMS often needs a specific scheme, gets intercepted, or shows a confirmation sheet before anything opens — and a link minted for one host simply won't open in another. We'd love one URL that works everywhere; no host wants that, so stop designing for it. Build one entry per host and keep a boring web fallback for the rest.
Attribution can break at either end. The sender edits the path. The recipient copies the link into a different chat and the scene id doesn't follow. A second open overwrites the cold-start parameters you were about to log. Someone screenshots the QR instead of scanning it. You'll end up with a bucket of unknown source no matter how careful you are, and pretending otherwise just produces confident, wrong dashboards.
There's a security cost too. If you trusted a user id or an admin flag from the query string because it made routing easy, you've handed out an authorisation bug. Verify on the server, every time. The link tells you where to land; it must never tell you who the person is.
Before you design the next share card, try one thing: open the mini-program, push it to the background, then tap a fresh link from a different conversation. If it lands on the old screen, you've just found the bug most teams ship. Handle the resume path, keep the payload short and boring, verify anything sensitive server-side — and accept that the scene id someone pasted into a group chat is a gap you live with, not one you close.
Sources
- Android Developers — App Links — how a platform decides which app owns an incoming link.
- WeChat — mini program developer docs — scene values, launch options and where entry parameters surface.
- Telegram — Bot API — deep-link start payloads that arrive with the first open.
- Apple Developer — platform documentation — how a host gates external linking and universal links.