Activation, first behaviors and placements
I wrote this to decide what counts as someone adopting TuckBuddy, which behaviors to encourage first, and where in the app a prompt is allowed to appear.
What happened next: 1.0 shipped. The next build logs these levels, so 30-day retention can show which one predicts that someone stays.
Updates three earlier docs (the onboarding plan, the habits and flywheels doc, and the engagement strategy) to what 1.0 actually is. The earlier principles from the onboarding plan (ask only when giving back, one new thing per session, never block the add, no guilt) all still hold.
0 · What changed since the first plans
| Earlier assumption | 1.0 reality | Effect on the plan |
|---|---|---|
| Describe It / AI parse is a T3 "taste then pay" feature | AI removed in the cull | The capture reveal points at Add a Few and Scan a Book only. The AI reveal and the whole AI tier are gone. |
| Payment ladder (credits, subscription) | Free, no item cap, no subscription | The trust ladder ends at sync. No paywall step to design. This is also the positioning: every competitor caps at 10 to 100 items and then charges. |
| Sharing is a T3 reveal | Hidden in 1.0, 1.1 headline | The sharing reveal moves to 1.1. |
| Sync needs a sign-in ask | Private iCloud, no account, on by default | No auth ask at all. Sync is a thing to show ("your items are backed up to iCloud"), never a thing to ask for. |
| O0 to O4 frosted onboarding | Name home → room → first item → animated ready screen pointing at Search | The first-session end already names the payoff. It doesn't yet let the user do it. |
| Hand-rolled onboarding coach | Apple ships TipKit (iOS 17+): eligibility rules, display limits, one-at-a-time groups | Use TipKit as the coach. Same lesson as the tab bar and native titles: adopt the platform before hand-rolling it. |
Competitive read. Every home-inventory app checked starts with the container (Sortly: folders first; Under My Roof: room or box inventory, 15-step onboarding, then a paywall; Memento: pick a database template; ToteScan: stick a label first). None uses sample data and none makes finding something the goal of the first session. Review complaints cluster on setup effort ("don't expect to get everything entered in one day") and on being charged after investing hours. Encircle's consumer app shut down, and users who hadn't exported lost their data. No app in the category publishes an activation definition. The nearest analog is Dropbox: "one file, in one folder, on one device," a single small input that pays off immediately.
1 · What is the adoption event?
The short answer: the first time the app answers "where is it?" for something the user put in on an earlier day. Adding is the cost. Finding is the payoff, and the engagement strategy already names the search hit as the retention event. An app you've only put things into hasn't done anything for you yet.
We can't know the real threshold in advance. What we can do is define a ladder of candidate events, instrument all of them, and let 30-day retention pick the winner. The ladder:
| Level | Name | Definition (starting guess) | Why it matters |
|---|---|---|---|
| L0 | Set up | Finished onboarding with one item filed | Survived the startup. Not adoption. |
| L1 | Stocked | ≥ 10 items across ≥ 2 places, ≥ 1 with a photo | Enough in the app for a search to have something to find. |
| L2 | Found it ★ | Opened an item's detail from Search or browse, for an item added on a previous day | First real payoff. Proposed activation event. |
| L3 | Adopted | Active on 3 different days within the first 30, at least one of them a find | The habit exists: the app is where they look. |
| L4 | Invested | 100+ items, or a list, or a backup/second device | The data is worth protecting. Retention by gravity. |
How we find out if L2 is right. Log each level as a TelemetryDeck signal the first time it's reached (one signal per level, no content, no names). After the first few hundred installs, compare 30-day return rates for users who hit each level in their first week. The level with the biggest gap between "reached" and "didn't" is the real activation event; if that turns out to be L1's item count instead of L2's find, the thresholds change and the placements below shift toward capture. Until then, L2 is the bet, because it's the one the product promise ("find anything in your home") depends on.
Instrumentation gaps today (checked in code): - The search signal fires on submit, not when a result is opened. We can't see a find. Add an "item found" signal (source: search / browse / spotlight, and whether it was added the same day). - The book scanner doesn't record an item added (still open). - No days-active count or last-open date, so L3 and win-back can't be computed. Add both to the usage signals. - No level signals. Add a "level reached" signal with the level (L1 to L4) and days since install.
All device-local or anonymous analytics; nothing touches the iCloud schema.
2 · Which behaviors to encourage out of the gate
In order. Everything not on this list waits for its readiness signal (see the placements below).
- Fill the room you're standing in. Room-at-a-time, not "inventory your house." Ten things in one place is a complete first session. The Add a Few flow is the tool; the onboarding room is the place. Permission to stop is part of the behavior: no progress bars, no "incomplete."
- Take a photo. Photo tiles are what make browse-finding work (you recognize before you read), and a photo item looks finished. Encourage it on the add form, never require it.
- Find one thing. Close the loop in the first days, not the first month. The ready screen already says "Find it anytime in Search"; make it a button that runs the search for the item they just added. It's a staged find, but it teaches the move with their own data.
- Add as things arrive. After the first burst, the habit is the trickle: the package on the doorstep, the thing you just put away. This needs capture to be one tap from outside the app (widget, quick action, share sheet), which is why those are placements, not features.
Deliberately not encouraged early: nesting depth, tags, lists, manual order, multiple homes, backup. All are real, all are readiness-gated. Showing them on day one is the "features plainly visible failed to register" failure from the earlier docs.
3 · Placements
A placement is a fixed spot in the app where a prompt can appear. Each has one job, one trigger, and a cap. The coach (TipKit) owns the budget across all of them: at most one new prompt per session, each shown once, dismissible in one tap, never between the user and the next add.
3a · Placements that exist today (re-aim them)
| # | Placement | Trigger | What it says / does | Level it pushes toward |
|---|---|---|---|---|
| P1 | Onboarding ready screen | End of onboarding | Replace "Let's go" alone with two buttons: Add more to {room} (primary, opens Add a Few in that room) and Try finding it (runs Search for the first item) | L0 → L1, teaches L2 |
| P2 | Home "Getting started" card | Shown until done | Becomes a 3-step card that checks itself off from usage signals: Add 10 things · Add a photo · Find something. Disappears when all three are done. No percentages. | L1, L2 |
| P3 | Save toast | Every save | Micro: stays a pure reward. At 10 / 50 / 100 / 250 items it becomes a milestone line ("That's 50 things tucked away"), celebrate-only unless the coach attaches one step | L1, L4 |
| P4 | Search empty state | No items / no query | With items: show recent adds as tappable suggestions ("Try: Passport, Drill"). Without: "Add your first item" | L2 |
| P5 | Search result → item detail | First find on an item from a previous day | A quiet "Found it" moment: a light haptic, nothing on screen the first few times, then once a subtle line on the detail ("Found in 2 taps") | Confirms L2 |
| P6 | Add chooser | Several single adds in one session (≥ 5) | TipKit tip on Add a Few: "Adding a lot? Add a Few takes a whole shelf at once." Once. | Faster L1 |
| P7 | Item form, category = Books | A book added by hand | Tip on Scan a Book. Once. | Capture speed |
| P8 | Unsorted row | Unsorted count ≥ 10 | "10 things aren't in a place yet. Put them away?" → multi-select move | Organization |
| P9 | Homes screen | Second home created | The one-time "Tap Home anytime to come back here" hint already decided. No other prompts here. | — |
3b · New placements to build (ranked)
| # | Placement | Why | Trigger / governance | Level |
|---|---|---|---|---|
| N1 | Spotlight indexing (Core Spotlight) | Lets people find their things from the iPhone home-screen search without opening the app. This is the retrieval payoff with zero friction, and a find logged from here counts toward L2. Probably the highest-leverage retention work on this list. | Always on, no prompt. One tip after L2: "You can search your things from the home screen too." | L2, L3 |
| N2 | App Shortcut: "Where is…" (App Intents) | "Hey Siri, where's the drill in TuckBuddy" answers with the path. Same payoff, hands-free. Shows in Shortcuts and Spotlight automatically. | No prompt; one tip after the third find. | L3 |
| N3 | Home-screen quick action + widget ("Add an item", "Scan a book") | The trickle habit (behavior 4 above) only exists if capture is one tap from outside the app. | Tip once, after L3 (they've come back three days; now make it faster). | L3 |
| N4 | Welcome-back summary | After ~14 days away, open to "Your home: 212 things in 18 places" before anything else. Reminds them the investment is there. No ask attached the first time. | Once per absence. | L3 |
| N5 | Backed-up reassurance | Free-with-iCloud is the trust story. At 50 items, one line in the milestone: "All 50 are saved to your iCloud." At 250, one tip toward a manual backup file. | Milestone-attached, once each. | L4 |
| N6 | Rediscovery card | "Tucked away 8 months ago: Camping stove, Garage › Metro shelf." Real information, self-renewing. | Home, at most weekly, only after 60 days and 50 items. Post-launch. | L3, L4 |
3c · Governance, restated for TipKit
- Each tip has an eligibility rule built from the usage signals (TipKit parameters and events), a display count of 1, and invalidates itself when the user does the action (someone who already uses Add a Few never sees P6).
- Tips go in one TipGroup so only one is eligible at a time, in priority order.
- A global frequency of one new tip per day (TipKit's daily display frequency).
- Milestones (P3, N5) are celebrations first; only one in three carries a next step, never two in a row.
- Nothing fires during onboarding or inside the first add session.
4 · What this replaces in the backlog
- The hand-rolled coach → TipKit setup + eligibility rules, reading the usage signals.
- The capture reveal → P6 (Add a Few only). The AI reveal dropped. The sharing reveal → 1.1 with sharing.
- The Getting started checklist → P2 (three-step self-checking card).
- New: Instrumentation (the item-found signal, level signals, days-active, scanner signal) · Ready-screen buttons (P1) · Spotlight indexing (N1) · "Where is" App Intent (N2) · Quick action + widget (N3).
Suggested order: Instrumentation first (nothing else can be measured without it, and it's small), then P1 + P2 (the first-week path), then N1 Spotlight (payoff without opening the app). Everything else after launch data.
5 · Open questions
- Is "found it" the right bet for activation, or should item count (L1) be the headline metric until data says otherwise? Count is easier to explain; find is closer to the promise.
- Staged find on the ready screen (P1): helpful teaching, or a gimmick with only one item in the app?
- TipKit's look is system-standard popover/inline cards. Acceptable, or does the coach need a custom surface? Recommendation: stock, per the stock-iOS design decision.
- Spotlight indexing puts item names in the system index (on device only, respects the user's Siri & Search settings). Fine for 1.0, or hold for privacy review?