Analytics Plugin

The analytics plugin turns Journey observation events into normalized analytics envelopes.

It does not change transition behavior. It listens to the runtime lifecycle and forwards a stable event shape to your analytics client.

Install And Use

import { createJourneyMachine } from "@rxova/journey-core";
import { createAnalyticsPlugin } from "@rxova/journey-core/analytics";

const machine = createJourneyMachine(journey, {
  plugins: [
    createAnalyticsPlugin({
      machineId: "checkout",
      includeStepMeta: true,
      track: (event) => analytics.track(event.name, event.payload)
    })
  ]
});

What You Get

The plugin augments the machine with:

type JourneyAnalyticsMachineExtension = {
  trackAnalyticsEvent: (
    name: string,
    payload?: Record<string, unknown>
  ) => JourneyAnalyticsTrackedEvent;
};

That lets you send custom analytics markers alongside the built-in lifecycle events.

Built-In Event Names

The plugin emits normalized events for:

journey_started
step_viewed
step_exited
transition_started
transition_succeeded
transition_failed
journey_completed
journey_terminated
navigation_previous
navigation_last_visited

Every event includes:

name
timestamp
payload
optional machineId

Depending on the event, payload fields may include:

raw context
stepId
from
to
eventType
transitionId
dwellMs
durationMs
stepMeta, fromStepMeta, toStepMeta

Options

track(event): analytics sink
machineId: optional identifier included in every tracked event
includeStepMeta: include step metadata in emitted payloads
onError(error, event): handles tracker failures without breaking the machine

payload.context always contains the raw machine context from the current snapshot.

Safety Behavior

If track(...) throws, the machine continues running.

when onError is provided, the plugin forwards the failure there
otherwise Journey reports a development warning

Analytics failures never block transitions, navigation, or snapshot commits.