The first screen of our first mini-program had four bullet points, a two-step tutorial overlay, and a sign-up card before the actual menu. We thought we were being generous. The numbers argued back: a large share of people who landed there never reached the menu at all.
In a native app, that kind of front door is survivable. Someone just downloaded you, so they came in expecting a setup ritual — account, permissions, a tour of the tabs. A mini-program sits inside a host the user already trusts and already uses. They didn't come for you; they came for a ride, a bill, a coupon. The moment you start explaining yourself, you're spending attention they didn't agree to give.
Why the door is narrower here
A web or native app earns a few seconds of patience by virtue of the install. A mini-program gets none. The host hands you a cold start, a loading spinner, and a user whose thumb is already moving. If the first thing they meet is a wall of intent, the back gesture is one swipe away and it costs them nothing.
So the instinct to over-explain is doubly dangerous here. We've watched teams pour a value proposition, a feature carousel, and three permission prompts into the first view, convinced that clarity requires coverage. It doesn't. Clarity requires one thing to do.
| First-run mistake | What the user actually does | What we ship instead |
|---|---|---|
| Tutorial overlay before content | Swipes it away, or leaves | Content first, tutorial on a long-press |
| Sign-up card on entry | Closes the program | One tap to the core action, account later |
| Three permission prompts at once | Denies all, permanently | Ask the one we need, ask the rest in context |
| Four bullet points of value | Reads none of them | One sentence, if the screen has room |
| Hidden primary action | Taps the wrong thing | One obvious button, everything else recedes |
The table isn't a style guide; it's what our analytics kept shouting. Every extra element on that first screen was a small tax, and taxes compound.
The temptation to over-explain
Here's the thing we had to admit: over-explaining feels like diligence. A product manager can point at a tutorial and say we told them how it works. But telling isn't activation. Activation is the user doing the one thing that makes the program worth keeping — placing the order, sending the message, finishing the level — within the first session.
We measure that now, and we measure it narrowly. Not installs, not opens, but first-action-completed within, say, ninety seconds of first run. When we stripped the welcome screen down to a single primary action and moved every explanation behind a help affordance, that number moved more than any redesign we'd shipped before. We didn't add clarity. We removed friction.
And yes, there's a real risk in being too thin. If the program's value really does need a word of context — a novel interaction, a confusing category — then hiding everything can leave people stranded. The test we use is simple: can a returning user who forgot us complete the core action cold? If yes, the first run can stay nearly empty. If no, one sentence earns its place.
Deferring the asks
Permission prompts are the easiest trap. Location, contacts, notifications — each one is a small chance the user says no forever, and a denied permission in a mini-program is harder to win back than on a phone where settings are one tap deeper. We ask for the one permission the immediate action needs, and we ask it inside the moment it's needed, not on arrival. The rest wait until the user has a reason to grant them.
This isn't just politeness. It changes the activation curve. People who complete the core action before seeing a single prompt are far more willing to grant the next one, because by then the program has kept a promise.
One primitive, not a hundred reinventions
There's a platform angle that rarely gets said out loud. Today, every merchant who builds a mini-program reinvents this same first-run dance — their own tutorial, their own deferred-permission logic, their own idea of a primary action. Multiply that across hosts and you get a hundred slightly broken onboarding flows, each maintained by someone who isn't thinking about onboarding full time.
A runtime that targets several hosts can carry one well-tested onboarding primitive — progressive disclosure, a single primary action, context-scoped permission asks — and let every mini-program inherit it. The merchant stops solving a problem they didn't hire for, and users stop relearning the front door every time they enter a new program. We'd rather see that primitive get a thousand hours of attention once than a thousand programs each spend an afternoon on it.
Sources
- web.dev — Learn — practical guidance on performance and user experience for the first load.
- MDN — Web Docs — fundamentals of progressive enhancement and interaction design.
- W3C — WCAG 2.2 — the measurable baseline for usable, perceivable interfaces.
- Google — Think with Google — research on mobile behavior and what keeps users coming back.
- StatCounter — Global Stats — data on device and platform share across markets.