Implementation worksheet · 5 min read
A Cross-Device Onboarding Completion Synchronization Policy
Store completion server-side per user and per step identifier, with the device as metadata rather than as part of the key. Merge by union rather than by last-write-wins: if any device completed a step, the step is complete. Completion is monotonic — it does not un-complete because an older device syncs later — and union is the only merge rule that respects that. Then decide two things explicitly: whether a genuinely platform-specific step (enable push on iOS) counts as complete when done elsewhere, and what a user sees on a second device that is partway through, which should be a resume prompt rather than a silent skip or a silent restart.
Onboarding state starts in local storage because that is the fastest thing that works, and it works until someone signs in on a second device. Then the tablet asks them to complete onboarding they finished on the phone last week, which is both irritating and a bad signal about whether the product knows who they are.
Put it into practice
1. Key completion on user and step identifier, not on device
The device belongs in the record as metadata — useful for debugging and for platform-specific steps — but not in the key. Keying by device is what produces the repeat-onboarding experience, and it is usually an accident of whatever storage was reached for first.
2. Merge by union, never last-write-wins
Completion only moves forward. A device that was offline for a week and syncs stale state must not un-complete a step finished yesterday. Last-write-wins is the default in many sync libraries and is precisely wrong for monotonic state — a phone coming back online should never reset a tablet's progress.
3. Classify each step as universal or platform-specific
Most steps are universal: understanding a concept, creating the first project, inviting a colleague. A few are genuinely per-device — enabling push notifications, granting camera access. Mark those, and let them re-prompt on a new device even when onboarding overall is complete, because they are per-device facts rather than per-user ones.
4. Show a resume prompt on the second device
Someone three steps in on their phone opening the tablet should see 'continue where you left off' rather than either a silent restart or a silent skip. The prompt costs one screen and it is the visible signal that the product tracked their progress correctly.
5. Reconcile on sign-in, before rendering onboarding
Fetch server state before deciding whether to show onboarding at all. Rendering first and correcting after produces a visible flash of an onboarding screen the user has already completed, which is the same class of defect as the flash of dismissed guidance on the web.
6. Handle the offline second device honestly
If server state is unreachable on a new device, prefer showing onboarding to skipping it — a repeated explanation is a smaller harm than a user missing setup entirely. Reconcile on connect and do not re-prompt what has already been done.
The synchronization policy
Copy this structure into your review document and record your observed result for each row.
| Decision | Policy | Set |
|---|---|---|
| Completion key | user + step identifier | |
| Device in the record | metadata only | |
| Merge rule | union — completion is monotonic | |
| Stale sync from an old device | cannot un-complete | |
| Universal steps | complete once, anywhere | |
| Platform-specific steps | re-prompt per device | |
| Second device, partly complete | resume prompt | |
| Second device, fully complete | no onboarding shown | |
| Server unreachable on new device | show onboarding, reconcile later | |
| Reconcile timing | before rendering, not after |
A failure worth checking
Last-write-wins on completion state. A tablet that has been in a drawer for two weeks syncs its old record and overwrites progress the user made on their phone yesterday. Onboarding reappears on a device they use daily, for someone who finished it, and the cause is a sync default nobody chose deliberately. Union is not harder to implement; it is just not the default, and completion is exactly the kind of state where the default is wrong.
Common questions
Should onboarding show again after a major redesign?
Sometimes, and it should be a deliberate decision with its own version rather than a side effect of the sync policy. Add new steps with new identifiers so the union rule handles them naturally — previously completed steps stay complete and only the new ones prompt.
What about a user on a shared device?
Keying on user rather than device handles it correctly by construction: each person sees their own state. It is another reason the device does not belong in the key.
Basis and scope
This is a proposed implementation method using illustrative examples, not a measured benchmark or a customer case study. Prepared with AI assistance. Validate product-specific behavior against current documentation and your own test environment.