One time surfaces

A hint, a coach mark, a primer, a review ask. They share a failure mode: they look right on the device that built them and reach nobody, or everybody, twice.

Three questions decide whether yours works. Each needs different evidence, and none of them is answered by looking at it on your own phone.

1. Store a count, never a boolean

A flag cannot express "three times, then stop", which is the rule that retires a surface before anyone is annoyed enough to dismiss it. Shipped consumer apps store counts, and more besides. Common shapes worth matching:

• an impression count per surface
• a lifetime ceiling, so it retires on its own
• a separate dismissal record, because being seen and being dismissed are different events and the second is rarer than you expect
• a per session record, so a surface cannot appear twice in one sitting
• a version in the key, so a redesigned surface can legitimately show again

That last one is the one teams skip and cannot retrofit cleanly. Put a version in the key the day you write it.

Suppression does not have to run on a calendar. Counting against a domain event the person actually does, rather than days elapsed, is often truer to intent.

2. Decide nothing from a store that has not answered

This is where these surfaces go wrong most often. The gates are read asynchronously, they land in different orders, and the empty default of most of them is exactly what a brand new user looks like. So the surface either:

• draws itself from unread state and is withdrawn a moment later, which reads as a glitch, or
• is suppressed by a gate that has not loaded yet and never appears at all.

Two rules that prevent both:

• Hold every surface that can withdraw itself until every read has ANSWERED. One rule for all of them, not a flag per surface, or the next surface is written without it.
• A read that FAILS must still answer. Otherwise one unreadable table leaves a screen with nothing on it for the rest of the session, which is worse than the flash you were preventing. Set the answered flag in a finally.

3. Check what a gate actually means

Two specific confusions, both of which ship silently:

• A one time key means "not dismissed", not "on screen now." Using it as a proxy for visibility suppresses other things long after the thing itself is gone. Gate on whether the surface is actually being drawn.
• A boolean whose false means both "no" and "not read yet" will be read as a fact. Give it a third state, or a separate answered flag.

4. Prove it, in the order confidence allows

1. Tests over the gates. Hold each read open in turn and assert the surface is NOT drawn. Then let them land and assert it is. Verify each by reverting the gate and watching the test go red: a test that passes either way proves nothing.
2. One look on a real build. A recording of a cold open, frames extracted, is enough to show it arrives and is never taken back. A development build is not representative: its timings are nothing like what you ship.
3. The number that matters, after release. Not how many obeyed it. How many eligible people never saw it. Every gate can take that to zero, and that is invisible until somebody measures the gap between who qualified and who was shown.

Emit an impression event and a resolution event with the outcome (obeyed, dismissed) from the day you build it. Without them, step 3 is impossible and you will be guessing for a release cycle.

5. When you want to know how others do it

Reading a shipped app of this kind tells you the STORAGE rules quickly: key names for counts, ceilings, sessions and versions are readable from an Android build's identifiers and strings. It will not tell you when anything fires, and it cannot tell you anything about whether YOUR surface reaches YOUR users.

Treat the shapes as evidence and any claim about timing as inference.