Build an onboarding checklist that follows backend results

A “Create your first project” button is useful navigation. Clicking it does not prove that a project was created. TinyActivate by TinyScale completes onboarding milestones when your backend confirms the corresponding action.

You can first test this behavior with a synthetic subject, then connect your own backend. TinyActivate displays one to five milestones and remembers progress across browser sessions. Your application remains responsible for access, billing, and its business actions.

If a setup milestone involves bringing in existing data, TinyImport's CSV upload and validation flow can prepare rows for review. Mark the onboarding milestone complete only after your backend saves the approved batch; the CSV import guide covers that handoff.

How should an onboarding checklist know a task is complete?

Record the milestone after the corresponding backend action commits, using a stable event identity for retries. TinyActivate displays that backend-confirmed progress through a read-only widget. Clicking an action link alone does not complete a milestone or authorize a business action.

Prefer your agent to handle setup? Use the TinyActivate setup prompt, then return here for the details.

Try one milestone

Use Node.js 20 or later and a new project directory. The commands below run the pinned TinyScale CLI through npx.

Stop if verification fails. The TinyScale setup reference describes current commands. Existing projects retain their original product permissions, so explicitly opt in when creating this preview:

npx -y tinyscale@0.10.0 workspace create --name "Onboarding example" --products tinyactivate --cohort external
npx -y tinyscale@0.10.0 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"}]}'
npx -y tinyscale@0.10.0 activate list

Replace the origin with your owned HTTPS origin. Keep private .tinyscale state out of source control and model context. Use the checklist ID returned by creation:

npx -y tinyscale@0.10.0 activate test --checklist CHECKLIST_ID --event project_created
npx -y tinyscale@0.10.0 activate status --checklist CHECKLIST_ID --revision 1 --cohort test

The test command uses a fixed synthetic subject. Its completion shows that this test event reached the checklist; it is not a customer activation or evidence of conversion lift.

Connect completion to committed work

In your application, save a small durable outbox record in the same transaction that creates the user's project. A background sender delivers the milestone after commit, reusing the outbox record's ID on every retry. A TinyActivate outage must not undo or block the successful project creation.

The backend event body follows this shape; placeholders are illustrative, not runnable values:

{
  "schemaVersion": "2026-09-07",
  "idempotencyKey": "YOUR_STABLE_OUTBOX_EVENT_ID",
  "subjectDigest": "64_LOWERCASE_HEX_CHARACTERS",
  "cohort": "test",
  "eventKey": "project_created"
}

Derive subjectDigest server-side using HMAC-SHA256 with a stable backend secret and your internal user ID. Send no raw IDs, email addresses, form values, or arbitrary metadata. Keep the scoped credential on the backend. The integration reference supplies the versioned endpoint paths, response contract, and retry handling. Its TypeScript client is currently a repository package, not a published npm dependency.

Add the browser view

Implement /api/onboarding/session in your app. It authenticates the current user, derives their digest, and obtains an origin-bound read session from TinyActivate. It must ignore caller-supplied subject identities and return the session with Cache-Control: no-store.

Once that backend route is in place, include:

<div id="onboarding"></div>
<script src="https://ingest.tinyscale.io/v1/activate/widget.v1.js" defer></script>
<script src="/onboarding.js" defer></script>

In your own /onboarding.js:

const widget = TinyActivate.mount(document.getElementById('onboarding'), {
  sessionPath: '/api/onboarding/session'
});

Follow the reference's CSP requirements. Call widget.refresh() after a backend milestone completes and widget.destroy() when removing the view. A browser click alone cannot complete a milestone.

Claim before live use

After verifying synthetic progress, run workspace claim and let the human owner claim in their browser. Use cohort: "live" only after claim and after connecting the authenticated session and backend event paths.

Preview lasts 72 hours and allows two checklists, 25 lifetime enrollments, and 200 accepted events, with synthetic subjects only. Free permits five lifetime checklists, 1,000 lifetime enrollments, and 2,000 events per UTC month. Limits hard-stop; paid expansion is not enabled. The owner console shows aggregate progress and controls. Incomplete milestones identify steps to investigate; they do not establish why a person stopped.

Common questions

Can the browser mark a milestone complete?

The widget reads progress and offers navigation. Your authenticated backend records completion after its business action succeeds; the browser does not receive the backend credential.

What happens when two steps finish out of order?

TinyActivate records the matching completed milestones for the enrollment. Your application enforces prerequisites. Follow the reverse-order event example to test the distinction with synthetic data.