Guided Flows

Guided flows let you define ordered sequences of UI interactions in your .arcy/ knowledge graph. When a user completes the steps in order, ARCY emits analytics events so you can measure adoption, drop-off, and time spent on each step.

How it works

A guided flow is a sequence of anchor IDs that a user must interact with in order, resolved to real elements at runtime by fingerprint (see Element Targeting), not a source attribute you add. ARCY watches for pointer events on those elements and tracks progress automatically. No code is required beyond defining the flow in YAML and pushing it.

When a user:

• Clicks the first anchor in a flow, ARCY emits flow_started
• Clicks each subsequent anchor in order, ARCY emits flow_step_completed
• Completes the final step, ARCY emits flow_completed
• Goes idle for longer than flowAbandonThresholdMs, ARCY emits flow_abandoned

All events include the flowId, the step ID, and timing data. They are visible in the ARCY dashboard under Analytics.

Defining a flow

Add a flows/{id}.yaml file to your .arcy/ directory:

flow:
  id: onboarding
  name: Onboarding
  goal: "Connect a data source and run a first analysis"
  persona: admin

steps:
  - order: 0
    title: Open integrations
    anchorId: sidebar-integrations-link
  - order: 1
    title: Connect a source
    anchorId: connect-integration-btn
  - order: 2
    title: Run first analysis
    anchorId: run-analysis-btn

Push the updated knowledge graph:

arcy push

The flow becomes active on the next session bootstrap.

Step matching

ARCY matches steps by anchorId. Steps must have anchorId values set to be tracked. Steps without anchorId are AI context only (Chat and Copilot read them to answer "how do I..." questions, but they are not tracked in the flow engine).

Steps are matched in order sequence. Interacting with step 1 before step 0 does not advance the flow. Interacting with steps out of order is ignored.

Activation milestones

Activation milestones are one-time events, tracked per user in localStorage. They fire the first time a user interacts with a specific anchor, even outside a guided flow. Milestones are configured on the backend (contact support to enable), not in local YAML. Once a milestone fires, it does not repeat for that user on that browser. Use milestones to track first meaningful actions such as "first API key created" or "first report exported."

Configuration

The only SDK-level option for guided flows is flowAbandonThresholdMs on ARCYProvider:

<ARCYProvider
  publicKey="pk_..."
  userTraits={{ userId }}
  flowAbandonThresholdMs={600_000}
>
  {children}
</ARCYProvider>

Default is 300000 (5 minutes). See Configuration for the full props reference.

Analytics events

Events appear in the ARCY dashboard under Analytics > Flows.