This document outlines detailed flow event information, if you're looking for information on NPS, and Checklist events for an integration please reference the Appcues Events Reference document. If you're looking to learn about sending events into Appcues or tracking events in Appcues see the Events Overview document.

We have three "levels" of events: flow, step-group and step-child. Flow events pertain to the overall lifecycle of a flow, which is composed of separate step groups. Step-group events describe the lifecycle of an individual step-group in a flow. A step-group will usually include some number of children. The step-child events describe the nitty-gritty details of what occurs during the process of showing and interacting with a particular step-child.

Public-facing events

• Flow Started (flow_started) Fired when the first step of a flow is started or displayed on the page. If this event is fired, then the Flow Aborted and Flow Error events should not be fired. This should be fired before the Step Started event.
• Flow Completed (flow_completed) Fired when the user completes the last step of the flow. This should be fired after the Step Completed event.
• Flow Skipped (flow_skipped) Fired when the user chooses to skip a flow. This should fire after the Step Skipped event is fired for the corresponding step.
• Flow Aborted (flow_aborted) Fired when there is a "fatal" error that prevents starting or completing a flow. If this event is fired before the first step is started, then Flow Started should not be fired. This should be fired after the Flow Error event.
• Step Started (step_started) Fired when the step-group is run or displayed on the page. If this event is fired, then the Step Aborted and Step Error events should not be fired. This should be fired before Step Child Activated or Step Child Recovered events are fired.
• Step Completed (step_completed) Fired when the user completes a step-group. For modals and tooltips, this means closing the content with the "complete button". For hotspots, this means clicking on the last hotspot. This should be fired before the Flow Completed event.
• Step Skipped (step_skipped) Fired when the user chooses to skip a step-group or flow. This should be fired before the Flow Skipped event.
• Step Aborted (step_aborted) Fired when there is a "fatal" error that prevents starting or completing a step-group. If this event is fired before we show the step-group, then Step Started should not be fired. This should be fired before the Flow Aborted event.
• Step Interacted (step_interacted) Fired when a user interacts with a step-group in some way. Currently we track when a user does any of the following:
  • Clicks a link in a flow
  • Clicks a button (built-in or custom) in a flow
  • Submits a form in a flow
  • Clicks on a hotspot to expand it. This should be fired before the Step Child Deactivated or Step Child Activated events that it may trigger.
• Form Submitted (form_submitted) Fired when a user submits a form in a modal. This should be fired before the Step Child Deactivated event it may trigger and before the Form Field Submitted event(s) that it will trigger.
• Form Field Submitted (form_field_submitted) Fired for each field in a form that a user submits in a modal. This should be fired after the Form Submitted event.

Internal events

These you probably shouldn't care about. They're much more low-level events that Appcues uses internally to track the performance of flows. Use at your own risk!

• Flow Attempted (flow_attempted) Fired when a user qualifies for a flow and Appcues begins the process of trying to start the content. This will either result in a Flow Started or a Flow Error event. This should always be the first event fired for a particular flow.
• Flow Error (flow_error) Fired when there is a "fatal" error that prevents starting a flow. If this event is fired, then Flow Started should not be fired. This is usually caused by the bubbling up of a Step Error event. This should be fired before the Flow Aborted event.
• Step Attempted (step_attempted) Fired when a user has qualified for a flow and Appcues begins the process of trying to start a particular step-group. This will either result in a Step Started or a Step Error event. This should always be the first event fired for a particular step-group. It will be fired for each step-group in a flow that Appcues attempts to start.
• Step Error (step_error) Fired when there is a "fatal" error that prevents starting a step-group. If this event is fired, then Step Started should not be fired. This should be fired before the Step Aborted event.
• Step Child Activated (step_child_activated) Fired when the user successfully views the content of a particular step child. For example: viewing a particular "page" in a modal; viewing the content of a tooltip or hotspot (either by clicking the hotspot or next button). This should fire after the Step Interacted event.
• Step Child Deactivated (step_child_deactivated) Fired when a user closes/finishes a particular step child. For example, leaving a particular "page" in a modal or closing a tooltip. This should fire after the Step Interacted event.
• Step Child Error (step_child_error) Fired for any error that prevents showing a particular step child. Depending on the content type, this can result in a "fatal" Step Error. This should be fired after Step Attempted and before Step Error (if it causes a Step Error).
• Step Child Recovered (step_child_recovered) Fired for a step child that had previously caused a Step Child Error but is no longer in an error state. This should fire after the Step Started event and potentially after a Step Child Error event.

Event structure

The events follow the flow > step-group > step-child hierarchy. Fields common to flow events are present on step-group and step-child events, while fields common to step-group events are also present on step-child events.

Structure of flow events

All flow-level events have the following common structure:

• id: flow_started (string, required) - Snake case identifier for the event type
• name: Flow Started (string, required) - Human-formatted name of the event type
• flowId: -JEz-zuieQH29FZLHqvR (string, required) - The ID of the flow object
• flowName: Onboarding Flow (string, required) - Human-readable title of this flow
• flowVersion: 1465479478192 (number, required) - Indicates a particular version of a flow (currently the same as the updatedAt timestamp)
• sessionId: 1478371724807 (number, required) - Identifier for a particular session of a user, which corresponds to a particular initialization of the Appcues script
• timestamp: 1478371725400 (number, required) - Timestamp at which the event was generated

Flow Error

Flow Error events will also include the following fields:

• error: Failed to load CSS. (string, required) - A text summary of the error
• details (string, required) - A more detailed explanation of the error, usually referencing step child errors that raised this step-level error

Structure of step events

All step-level events have the above flow-level properties and share the following fields:

• stepId: -JEz-zvIXWj-9qNICQYK (string, required) - The ID of the step-group object
• stepType: hotspot-group (string, required) - The type of pattern of this step-group (hotspot-group, modal, etc)

Step Interacted

Step Interacted events will also include the following fields:

• stepChildId: -JKafq_L5HRpGN3vIYB2 (string, required) - The ID of the step child in which the user performed an interaction
• stepChildNumber: 1 (number, required) - The index (zero-based) of the step child in which the user performed an interaction
• interactionType: click (string, required) - How the user interacted with the step-group (click, hover, submit, etc)
• interaction (object, required) - An object representing information about the user's interaction
• interaction.category: link (string, optional) - Category of the thing upon which the interactionType was performed

Existing interactionType and category values:

Depending on the interaction.category value, the interaction object contains different fields:

Form Submitted

Form Submitted events will include the fields of Step Interacted events with the following modifications:

• interactionType: submit (string, required) - Always submit for Form Submitted events
  • interaction (object, required) - An object representing information about the user's interaction
  • interation.category: form (string, required) - Always form for Form Submitted events
  • interaction.formId: -JKgfc1rgO8JlCrh0B1U (string, required) - The ID of the form object that was submitted
  • interaction.response (array, required) - List of response objects
    • (object)
      • fieldId: -KQaXuLFQEcbyzuNftXr (string, required) - The ID of a specific field in a form
        • label: Email (string, required) - The label describing the form field
        • value: test@example.com (required, nullable) - The value the user entered in the form field

Form Field Submitted

Form Field Submitted events will include the fields of Step Interacted events with the following modifications:

• interactionType: submit (string, required) - Always submit for Form Field Submitted events
• interaction (object, required) - An object representing information about the user's interaction
  • interaction.category: form (string, required) - Always form for Form Field Submitted events
  • interaction.formId: -JKgfc1rgO8JlCrh0B1U (string, required) - The ID of the form object from which this field was submitted
  • interaction.fieldId: -KQaXuLFQEcbyzuNftXr (string, required) - The ID of this form field
  • interaction.label: Email (string, required) - The label describing this form field
  • interaction.value: test@example.com (required, nullable) - The value the user entered in this form field

Step Error

Step Error events will include all the step-level fields in addition to the following:

• error: Failed to load CSS. (string, required) - A text summary of the error
• details (string, required) - A more detailed explanation of the error, usually referencing step child errors that raised this step-level error

Structure of step-child events

All step-child events will include the fields of step events in addition to the following:

• stepChildId: -JKafq_L5HRpGN3vIYB2 (string, required) - The ID of the step child
• stepChildNumber: 1 (number, required) - The index (zero-based) of the step child

Step Child Deactivated

Step Child Deactivated events will also include the following fields:

• timeSpent: 12537 (number, required) - The amount of time in ms spent on the step child

Step Child Error

Step Child Error events will also include the following fields:

• error (string, required) - The error description