Keep onboarding progress correct when events arrive out of order

A user creates a project in one tab and connects an integration in another. The corresponding background jobs may finish in either order. An onboarding checklist should reflect the completed actions without depending on the order in which the browser was clicked.

TinyActivate by TinyScale accepts backend milestone events and tracks their completion for an enrollment. Here is a synthetic test you can run before connecting real users.

Configure two distinct actions

Follow the backend-confirmed onboarding walkthrough to download and checksum-verify the CLI and create a new preview with --products tinyactivate. From that project directory, create this configuration after replacing the origin:

bun ./tinyscale-agent-v0.2.0.mjs activate create --configuration-json '{"name":"Getting started","allowedOrigins":["https://your-owned-app.example"],"steps":[{"key":"project_created","label":"Create a project","description":"Start your first project.","actionPath":"/projects/new"},{"key":"integration_connected","label":"Connect an integration","description":"Connect your first integration.","actionPath":"/settings/integrations"}]}'

Choose milestones that correspond to facts your own backend can confirm. The action links help people navigate; clicking them does not complete a milestone. If your app requires a project before connecting an integration, your app must enforce that business rule. The checklist is a sidecar, not a dependency engine.

Send the second milestone first

Replace CHECKLIST_ID with the returned ID and run:

bun ./tinyscale-agent-v0.2.0.mjs activate test --checklist CHECKLIST_ID --event integration_connected
bun ./tinyscale-agent-v0.2.0.mjs activate status --checklist CHECKLIST_ID --revision 1 --cohort test
bun ./tinyscale-agent-v0.2.0.mjs activate test --checklist CHECKLIST_ID --event project_created
bun ./tinyscale-agent-v0.2.0.mjs activate status --checklist CHECKLIST_ID --revision 1 --cohort test

These commands use one fixed synthetic subject for the checklist. Inspect the summaries after each event: the connected-integration step should be completed first, then the enrollment should be complete after the project event. These are expected results to verify, not a claim that this example has just run in your project.

Use the widget integration from the walkthrough to inspect the same behavior in a browser. Keep the session route authenticated, derive the subject on the backend, and return the read session only to that user. Refresh the widget after the backend finishes a milestone.

Preserve event identity through retries

For your production integration, write a durable outbox intent in the transaction that commits the business action. A background sender delivers it to TinyActivate afterward, using that outbox ID as the stable idempotency key on every retry. Do not generate a new key for each transport attempt.

The event contains a pseudonymous subject digest, cohort, and milestone key. Derive the digest server-side with HMAC-SHA256 and keep the HMAC secret stable. No raw user IDs, names, form values, or arbitrary properties belong in the event.

Bound retries according to the integration reference. A duplicate must not be treated as a new user accomplishment, and a permanently rejected event needs investigation rather than endless retry. Failed delivery must leave the customer's committed action intact.

Keep revisions and cohorts visible

Existing enrollments stay on the revision they started with; new subjects use the current revision. When you change checklist steps, inspect the corresponding revision instead of mixing two different definitions of “complete.” Removing an allowed origin also blocks its old read sessions.

Preview accepts synthetic subjects only. Human claim is required before live use, and it keeps the same IDs under hard Free limits. Keep test counts separate from live counts. Two completed synthetic steps prove the integration path, not product adoption or a conversion improvement.

Start with the complete integration walkthrough. The reference guide covers current limits, sessions, pause, erasure, and retry behavior.