Paths

A path is an ordered journey made of steps and sub-steps. Each step unlocks once the previous one is complete; sub-steps inside a step finish either automatically (rule-engine event) or manually (widget CTA / API). Operators define one path per audience as the active default; users see it through the path widget.

Why paths exist

Coins, streaks, and badges reward isolated moments. Paths reward progress through a defined arc — first-value onboarding, a five-lesson unit, a seller activation checklist, a 30-day training plan, a certification track. Instead of asking users to infer "what's next," the widget shows the next concrete action and rewards completion in context.

How they work

A path has three layers:

• Definition — label, audience, display mode, accent color, icon.
• Steps — ordered milestones. Each step has a label, optional description, optional unlock_condition override, optional completion_condition, and reward (coins + badge).
• Sub-steps — the actual work inside a step. Each sub-step finishes via a completion_condition (auto) or allow_manual_complete=true (manual CTA / public API). Optional content_url deep-links to the customer's app.

Default unlock semantics: step n+1 unlocks when step n is fully completed. Override per step with unlock_condition (e.g. "unlocks when the user earns the novice badge") if you need non-linear gating.

Default sub-step semantics: allow_manual_complete=true with no completion_condition. The widget shows a "Mark complete" CTA (if the session token has events:track scope), and a content_url opens in a new tab. Add an automation later if you want the rule engine to mark the sub-step done off an event.

Step-level completion is optional. Add a step completion_condition when one event should finish the whole milestone, such as event_count(module_finished) >= 1. When it matches, Hatched marks every unfinished sub-step in that step as complete in the same event tick, applies each sub-step reward once, then applies the step reward. Leave the step condition blank when each sub-step should complete from its own event or manual CTA.

Display modes

• Straight column (display_mode: 'straight') — a readable vertical path with a continuous accent connector. Best for long ordered journeys where clarity matters.
• Zigzag quest (display_mode: 'zigzag') — alternating nodes and labels, Duolingo-style. Best when the path should feel more playful.
• Compact stepper (display_mode: 'stepper') — horizontal scrolling chips with the active step expanded inline. Best for short checklists, onboarding flows, or any place vertical real estate is tight.

The runtime renders the same data either way — toggle freely; users see the change on next mount.

Path icons

The definition icon is optional decoration next to the path label. Allowed values are path, flame, heart, bolt, star, and leaf. Use path for no icon. Existing unsupported icon values are normalized to path by the path icon migration.

Single active path per audience

Activating a path atomically deactivates every other path in the same audience. There is one live path per audience at any time. Drafts stay inactive until you flip the toggle from the dashboard.

Example

buyer_onboarding path (audience: seller) — three steps:

1. Set up your storefront — sub-step "Add your first product" (manual, deep-links to /products/new).
2. Stock your shop — sub-step "Add five products" (auto, completes when event_count(product_added) ≥ 5).
3. Go live — step completion condition event_count(storefront_submitted) ≥ 1, then awards verified_seller badge.

How to set it up

1. Dashboard → Paths → New path.
2. Pick the audience (multi-audience customers only).
3. Add steps in order; expand each one to add sub-steps.
4. Default sub-step is manual — leave it that way unless you want automation. If one event should complete the whole step, add a step completion rule instead.
5. Live preview shows fresh / in-progress / completed states.
6. Set active when you're ready. Activating swaps in this path and deactivates whatever was previously live for this audience.
7. Embed the path widget on the customer surface — the runtime resolves the active path automatically.

Gotchas

• Audience is immutable after a path is created. Pick carefully on creation; if you need a different audience, clone the path.
• Manual completion needs a session token with events:track scope. Embed-token mounts (read-only) won't show the "Mark complete" CTA.
• Step completion rules cascade unfinished sub-steps and their rewards. Use them for true milestone events; use per-sub-step conditions when each task should award independently.
• Add at least one sub-step when using a step completion rule. The rule persists progress by marking unfinished sub-steps complete; an empty step has no completion record to update.
• A sub-step must keep either a completion_condition or allow_manual_complete=true. The API rejects sub-steps that drop both.
• Path definition icons are curated keys, not arbitrary emoji or image URLs. Use one of path, flame, heart, bolt, star, or leaf.
• Per-buddy completion state is bound to the path definition. Deleting a path removes its completion records — there is no recovery.

Related

• Badges — step rewards are usually a badge.
• Streaks — habit loops that run alongside a path.
• Send events — events drive automatic sub-step completion.
• Path widget — rendering the active path.