Set up a progression funnel
A progression funnel shows how players move through the levels, challenges, or other stages in your game. Use it to identify where players stop progressing, compare successful and failed outcomes, and review how long completed stages take.
In this guide, you'll prepare your progression events, create a funnel, and check its results. Progression funnels use the predefined jt_progression event and provide metrics for starts, completions, failures, and completion time. See the funnel overview for more context.
Before you begin
- Integrate the justtrack SDK and define what counts as starting, completing, and failing a stage.
- Choose consistent identifiers for your progression hierarchy. Use the same identifiers across the actions belonging to a stage.
- Provide a duration on completion events to use Avg. Completion Time.
- Use an admin or manager role to create or edit funnels.
For platform-specific SDK calls, select your platform and version in Track events. The examples below describe event data; adapt them to your platform's SDK methods.
Prepare your progression events
The predefined SDK event is JtProgression; its event name in the analytics platform is jt_progression.
| Field or property | Purpose | Example or usage |
|---|---|---|
| Event name | Identifies the progression event. | jt_progression |
jt_action | Records the stage's action or outcome. | start, complete, or fail |
jt_progression_1 | Identifies the progression category or top level. | world_forest or world_desert |
jt_progression_2 | Identifies a stage within that progression. | level_0001 or level_0002 |
jt_progression_3 | Distinguishes a stage or variant. | normal or hard |
| Duration | Attaches a numeric time value to the event. | For example, 42.5. Send completion time with jt_action="complete". |
| Duration unit | Defines how to interpret the time value. | seconds or milliseconds, using your SDK's duration API. |
You define the progression identifiers. Include the hierarchy dimensions you need to identify and filter your stages. See JtProgression and Predefined Dimensions for the event and dimension reference.
Choose a consistent hierarchy
These two examples use the same campaign. Both contain Forest and Desert worlds, each with Level 1 and Level 2. The simple example uses two progression dimensions; the extended example adds difficulty as a third dimension. Each tree shows jt_action beneath the stage or variant to illustrate its possible actions.
Simple example: world → level → action
jt_progression_1 = world_forest
├── jt_progression_2 = level_0001
│ ├── jt_action = start
│ ├── jt_action = fail
│ └── jt_action = complete
└── jt_progression_2 = level_0002
├── jt_action = start
├── jt_action = fail
└── jt_action = complete
jt_progression_1 = world_desert
├── jt_progression_2 = level_0001
│ ├── jt_action = start
│ ├── jt_action = fail
│ └── jt_action = complete
└── jt_progression_2 = level_0002
├── jt_action = start
├── jt_action = fail
└── jt_action = complete
Extended example: world → level → difficulty → action
jt_progression_1 = world_forest
├── jt_progression_2 = level_0001
│ ├── jt_progression_3 = normal
│ │ ├── jt_action = start
│ │ ├── jt_action = fail
│ │ └── jt_action = complete
│ └── jt_progression_3 = hard
│ ├── jt_action = start
│ ├── jt_action = fail
│ └── jt_action = complete
└── jt_progression_2 = level_0002
├── jt_progression_3 = normal
│ ├── jt_action = start
│ ├── jt_action = fail
│ └── jt_action = complete
└── jt_progression_3 = hard
├── jt_action = start
├── jt_action = fail
└── jt_action = complete
jt_progression_1 = world_desert
├── jt_progression_2 = level_0001
│ ├── jt_progression_3 = normal
│ │ ├── jt_action = start
│ │ ├── jt_action = fail
│ │ └── jt_action = complete
│ └── jt_progression_3 = hard
│ ├── jt_action = start
│ ├── jt_action = fail
│ └── jt_action = complete
└── jt_progression_2 = level_0002
├── jt_progression_3 = normal
│ ├── jt_action = start
│ ├── jt_action = fail
│ └── jt_action = complete
└── jt_progression_3 = hard
├── jt_action = start
├── jt_action = fail
└── jt_action = complete
Track starts, completions, and failures
| Action | Recommended trigger |
|---|---|
start | The player begins an attempt at the stage. |
complete | The player successfully finishes the attempt. Include its completion duration. |
fail | The attempt ends in a failure according to your game's rules. |
Send one start event per attempt and the appropriate outcome when that attempt ends. A retry begins a new attempt. Avoid duplicate events from overlapping callbacks, and don't report an abandoned attempt as completed.
Example event sequence
This sequence follows one player who fails Forest Level 1 on normal difficulty, retries it, and then succeeds. Every event uses the same progression identifiers: world_forest, level_0001, and normal.
| Game action | jt_action | Duration | Unit |
|---|---|---|---|
| Begin the first attempt | start | — | — |
| Fail the first attempt | fail | 28.5 | seconds |
| Begin the retry | start | — | — |
| Complete the retry | complete | 42.5 | seconds |
The duration on the failed attempt doesn't supply Avg. Completion Time; that metric uses the time you send with completion events. A player can have both failure and completion events for the same stage, so the same player can contribute to both outcome groups.
Provide the duration on the completion event. The funnel uses this value for Avg. Completion Time. Use a consistent timing convention for pauses, background time, and retries, and send the matching time unit. A score or a count can't replace a completion duration.
You can send decimal durations. Numeric event values must be finite. See Track time and the event restrictions.
Create a progression funnel
- Select the app you want to analyze. In the App Menu, open Funnels.
- Click Create funnel and enter a name. Add a description if it helps explain the analysis.
- Select Progression funnel as the type and confirm the app and platform used to choose the available events.
- Add your progression steps. Each step uses
jt_progression; use conditions on the progression dimensions to identify the relevant stage. - Arrange the steps in the progression you want to analyze. You can configure up to 50 steps.
- Click Create funnel, then open the saved funnel to review its data.
For example, to analyze the four stages from the hierarchy above on normal difficulty, use these conditions:
| Step | jt_progression_1 | jt_progression_2 | jt_progression_3 |
|---|---|---|---|
| Forest Level 1 | world_forest | level_0001 | normal |
| Forest Level 2 | world_forest | level_0002 | normal |
| Desert Level 1 | world_desert | level_0001 | normal |
| Desert Level 2 | world_desert | level_0002 | normal |
These conditions identify the stage. The progression actions provide its start, completion, and failure data. Include the difficulty condition when you want to isolate that variant; omit it if you use the simple hierarchy without jt_progression_3.
You can't change the funnel type after creation. Changing the app or platform while configuring a funnel resets the configured steps. Check these selections before adding your steps.
The funnel creation guide explains the setup controls in more detail.
Review your results
Understand how steps count users
A user contributes to a step only if they also match every preceding step. If they don't match a required step, they don't contribute to any later step. These counts represent unique users rather than the number of attempts or raw events.
The configured order determines which users remain eligible at each step. It doesn't require their events to have happened in that chronological order. For example, reversing a funnel starts the analysis from the users who match the new first step. See Funnel steps.
Read the progression metrics
In the formulas below, Uᵢ is the user count at the current step, Uᵢ₋₁ is the count at the preceding step, and U₁ is the count at the first step. Use the same app, segments, date range, and aggregation settings when comparing results.
| Metric | Meaning |
|---|---|
| Users | Users who match this step and all preceding steps. |
| Complete/Start Ratio | Users who complete the stage divided by users who start it, within the applicable funnel population. |
| Fail/Complete Ratio | Users who fail the stage divided by users who complete it, within the applicable funnel population. |
| Avg. Completion Time | Average completion duration, based on the time supplied with jt_progression events whose jt_action is complete. |
| Step Completion Rate | Uᵢ / Uᵢ₋₁ × 100% |
| Churn | Users counted at the preceding step who don't match this one: Uᵢ₋₁ − Uᵢ. |
| Churn Rate | (Uᵢ₋₁ − Uᵢ) / Uᵢ₋₁ × 100% |
| Total Completion Rate | Uᵢ / U₁ × 100% |
Interpret the results
High Churn Rate
Inspect the transition to that step. Missing tracking, a skipped stage, or players who haven't reached it can all contribute. Funnel churn alone doesn't establish that a player uninstalled or permanently stopped playing.
Low Complete/Start Ratio
Investigate whether players have difficulty finishing the stage and whether completion events arrive as expected.
High Fail/Complete Ratio
Compare failure and completion outcomes for that stage. Keep in mind that one player can contribute to both groups.
Unusual Avg. Completion Time
Check the game experience together with your duration measurement, time unit, and pause handling.
Choose Daily Logic or Cohort Logic
The Aggregation setting determines how the selected date range applies to your progression funnel.
Daily Logic uses the dates on which progression events occurred. It shows activity within the selected calendar period, including events from new and returning players. Use it to understand progression activity during a particular day or date range.
Cohort Logic groups players by their app install date. The date range selects the install cohorts; the days-since-install setting determines which part of their subsequent progression to include. D0 is the install day, D1 the following day, and so on. Use it to compare how groups of newly acquired players progress over the same observation window.
Example: the same player in Daily Logic and Cohort Logic
A player installs the app and starts Level 1 on Monday, then completes Level 1 on Wednesday.
Setup: Select Monday as the date range in both views. For Cohort Logic, include D0, D1, and D2. Review the example after Wednesday's events arrive, using the same step conditions and segment filters.
| Setting or event | Daily Logic | Cohort Logic |
|---|---|---|
| What does selecting Monday mean? | Include progression events that occurred on Monday. | Select players who installed on Monday; include their events from the selected days since install. |
| Monday: player starts Level 1 | Included. The start occurred on Monday. | Included. Monday is D0 for this player. |
| Wednesday: player completes Level 1 | Excluded. Wednesday is outside the selected calendar date range. | Included. Wednesday is D2 and is part of the selected observation window. |
| Progression captured for this player | The Level 1 start is included; the later completion is outside this view's date range. | Both the Level 1 start and completion are included for the Monday install cohort. |
Wednesday's completion can contribute to the Monday cohort even though it occurred after the selected install date. The funnel's step conditions and segment filters still apply.
For more context, see the aggregation and days-since-install definitions and the cohort analysis guide.
Validate your tracking
Check representative events in Live Events on the app's SDK integration page before relying on the funnel. The SDK guide describes where to find them.
Why doesn't my progression funnel show any data?
Confirm that the app sends jt_progression, that its dimension values match the step conditions, and that the selected app, date range, and segments include the intended data.
Why does a later funnel step show fewer users than the event report?
Check the preceding steps. Users who don't match every required earlier step aren't eligible for that funnel row.
Why is the completion time missing or implausible?
Inspect the numeric duration and unit on complete events. Check for seconds sent as milliseconds, missing values, and inconsistent timing conventions.
Why do outcomes appear under different stages?
Compare all progression identifiers across start, fail, and complete events. Check spelling, formatting, game mode, and difficulty.
Why don't retries increase the Users count?
Users counts people, not attempts. Repeated events from one player don't represent additional unique players.
Next steps
- View a funnel to explore its data view.
- Manage an existing funnel to update its settings.
- Track events for platform-specific implementation details.