Funnels

Funnels let you define an ordered sequence of steps that users should complete, then measure how many users reach each step and where they drop off. They are useful for tracking conversion flows like onboarding, checkout, or signup.

Add Owlmetry funnel tracking to this project.
Load `/owlmetry-cli` plus `/owlmetry-swift` or `/owlmetry-node`
(install the owlmetry-skills Claude Code plugin if missing).

- Identify 2-3 key user journeys worth measuring conversion on
  (e.g., onboarding, checkout, activation).
- For each journey, define the funnel on the server via CLI with
  3-6 ordered steps, then add Owl.step("step-name") calls at
  each progression point in the code.
- Each step must be a point every user passes through — don't
  include optional side-paths or engagement actions as steps.
- Split alternative paths into separate funnels (e.g., screenshot
  export vs video export).

Funnel Definitions

A funnel definition is a project-scoped record with an ordered list of steps. Each definition includes:

Funnels are managed through the dashboard, the CLI, or the API.

Steps

Each step has a name and an event_filter that determines which events count as completing that step:

{
  "name": "Viewed Pricing",
  "event_filter": {
    "step_name": "viewed-pricing",
    "screen_name": "PricingScreen"
  }
}

The event_filter can match on step_name, screen_name, or both. When both are provided, an event must match both fields to satisfy the step.

A funnel can have up to 20 steps.

Tracking Funnel Steps

SDKs provide a step() method that emits an event matching the step name in your funnel definition:

step("viewed-pricing")    → matches event_filter { "step_name": "viewed-pricing" }
step("started-trial")     → matches event_filter { "step_name": "started-trial" }

The step name you pass to step() must match the step_name in the funnel definition's event_filter. For SDK-specific usage, see the Swift SDK or Node SDK guides.

You can also define steps that match on screen_name instead of or in addition to step_name. A step filter matching screen_name: "CheckoutScreen" would count any event from that screen.

Analysis Modes

Funnel queries support two modes that change how step completion is evaluated:

Open Mode (Default)

Users can enter the funnel at any step. A user who completed step N is automatically counted in all preceding steps (1 through N-1), even if they never triggered those events. This ensures the funnel always narrows downward.

Open mode answers: "How many users reached at least this step?"

Closed Mode

Steps are evaluated sequentially. A user only counts toward step N if they also completed all preceding steps (1 through N-1), and in the correct order based on event timestamps. The system uses each user's earliest timestamp per step, requiring each subsequent step to occur strictly after the previous one.

Closed mode answers: "How many users completed the full progression from step 1 through step N?"

Identity Dimension

Both modes group events by user_id. A "user" in funnel analytics means a distinct user_id value. In closed mode, the system tracks each user's earliest timestamp at each step and requires strict chronological ordering — step N must occur after step N-1.

Important: Events with no user_id are excluded from funnel analytics. The Swift SDK automatically attaches an anonymous owl_anon_* ID to every event, so those events do flow into funnels. On the Node SDK you must scope an instance to a user with Owl.withUser("…") before emitting step() — global Owl.step() calls have no user_id and are excluded from funnel results. Call Owl.setUser("real-id") (Swift) after sign-in to claim earlier anonymous events to the real user.

Analytics Results

A funnel query returns per-step analytics:

The total_users at the top level represents the total number of users in the funnel (all users who completed at least step 1 in closed mode, or any step in open mode).

Grouping and Segmentation

Funnel queries support a group_by parameter to break down results by a dimension:

Experiment grouping is particularly useful for measuring how different A/B variants affect conversion through a funnel.

Filtering

Funnel queries accept optional filters to narrow the data:

• since / until -- date range
• app_id -- restrict to a specific app
• app_version -- restrict to a specific version
• environment -- restrict to a runtime platform
• experiment -- filter to a specific experiment variant (format: name:variant)
• mode -- open or closed
• data_mode -- production, development, or all (see Data Mode)

Storage

Funnel events are stored in a dedicated funnel_events table, partitioned monthly by timestamp, with structured rows containing step_name, user_id, screen_name, and experiments.

For API details, see the funnels API reference.