Define key flows

Key flows are read from the journey, so they need it switched on: Follow the journey.

Define them in code

Write a class that implements KeyFlows:

namespace App\Journey;

use MyBeast\Sessions\Laravel\Flows\FlowDefinition;
use MyBeast\Sessions\Laravel\Flows\FlowStepDefinition;
use MyBeast\Sessions\Laravel\Flows\KeyFlows;

final class AppKeyFlows implements KeyFlows
{
    public function flows(): array
    {
        return [
            new FlowDefinition('add-project', 'Add a project', [
                FlowStepDefinition::visit('opened', 'Opened', ['projects.create']),
                FlowStepDefinition::save('saved', 'Saved', ['projects.store']),
            ]),
        ];
    }
}

and name it in the SDK's config (publish it first with php artisan vendor:publish --tag=mybeast-sessions-config):

// config/mybeast-sessions.php
'journey' => [
    // …
    'flows' => App\Journey\AppKeyFlows::class,
],

Each step is reached by a journey step of one of its routes, named as your routes are named:

• FlowStepDefinition::visit(key, label, routes): your server showed one of these pages.
• FlowStepDefinition::save(key, label, routes): your server took one of these writes.
• FlowStepDefinition::start(key, label): a first-run flow's first step, below.

A run starts when a person reaches the flow's first step, moves to the furthest step they reach, and finishes at its last. A run with no new step for the flow's giveUpAfterHours (24 unless you say otherwise) has been given up, and shows as a stuck point.

What a flow may be

• Up to 50 flows, each with 2 to 20 steps.
• Slugs and step keys of 1 to 40 lowercase letters, digits and hyphens, each unique.
• A visit or save step names at least one route; route names have no slash and no space.
• A start step only as the first step of a first-run flow.

The definitions are checked before anything is sent, even while the SDK is off, and a flow that doesn't fit fails the command with every problem named. A route name your app doesn't have is a warning, not a failure: a route may live only in some environments.

A first-run flow

A flow with newAccountDays follows a new person's first run: it starts at their first step of the journey, if their account is at most that many days old, and never twice. Its first step is a start step, reached when the run starts.

// A first run: starts at a new person's first step (account at most 7 days old), never twice.
new FlowDefinition('onboarding', 'First run', [
    FlowStepDefinition::start('signed-up', 'Signed up'),
    FlowStepDefinition::save('project-saved', 'First project saved', ['projects.store']),
], giveUpAfterHours: 168, newAccountDays: 7),

An account's age comes from the user's created_at by default; change it with Sessions::journeyUsing(subjectSince: …).

Push them at deploy

php artisan mybeast:sessions-flows          # push them: a deploy step
php artisan mybeast:sessions-flows --check  # CI: check only, send nothing

The push needs the server secret, and replaces the flows Sessions has, all or nothing. Run it as a deploy step, and --check in CI to catch a flow that doesn't fit before it ships. While the SDK is off, or no flows are named, the command says so and succeeds.

Changing a flow

Runs and stuck points name a flow by its slug and its steps by their keys. Keep both when you rename a flow or a step: change the label instead. A new step at the end is safe. A flow you leave out of the push is retired, and its runs are kept.

What you see

Key flows shows each flow for the last 7, 30 or 90 days: how many runs started and finished, and the share that finished against the period before. Each step shows how many reached it and how many gave up there, with what went wrong in their runs, such as a form that refused a field or a page that failed. With only a few runs, it shows counts instead of shares.