Flow events

If you choose to integrate flows using an iFrame wrapper in your application, most of the work will be done for you already. But how do you know when the user is done with the workflow if you need to trigger navigation or close a containing modal in your application?

Enter flow events

You can listen for a flow event signaling that the user is done with the workflow and your application can react accordingly. Flow events leverage the browser API postMessage to inform the parent application of an event in the frame. This sends a message that you can receive with an event listener in Javascript.

Compatibility

This functionality is ubiquitous in desktop and mobile browsers - you can rest assured that all your customers will be covered by flow events, regardless of their computing device.

Source: Browser compatibility chart on MDN

When are events fired?

Flow events can be emitted in two scenarios:

1. The flow’s goal has been clearly completed and there is no other information to view or action for the user to take. An example is the industry selection flow: once the industry has been saved successfully, there is nothing else to be done. The flow is completed and the event is triggered automatically without additional user interaction
2. The user takes an action that signals that they have finished their interaction with the flow. For flows that are more open-ended or have information that the user should consume after taking an action, flow events can be triggered by clicking a button signaling they have completed their interaction with the flow. An example of this is the “Add employees” flow. Since we cannot automatically determine when the user has finished – they may be editing many employees, adding one or multiple employees, or just viewing employee information – the user must inform us that they are done with their operation by clicking a button, commonly labeled “Finish”.

The structure of an event

Here is a raw event fired from within a flow:

{  
  "event": "gusto:flow-finish",  
  "metadata": {  
    "flowType": "industry_selection",  
    "companyUuid": "4206ae3f-5f02-4cac-b22f-3a2676449f2f"  
  }  
}

A flow event is a JSON object. The “event” attribute contains the type of event fired. The “metadata” attribute will at minimum contain “flowType” and “companyUuid”, but may contain more attributes depending on the flow. If so, this will be covered in the documentation.

Currently gusto:flow-finish is the only event type, but this may expand to other types in the future. Your application should consider future expansion when interpreting events.

Sample event listener for flow events

To receive flow events when embedding flows in your application, add an event listener for ‘message’ events. It’s also important to follow all security recommendations for verifying any event’s origin. See the MDN postMessage documentation for more details and documentation.

window.addEventListener( 'message', (event) => {  
    if (event.data.event == 'gusto:flow-finish') {  
        // event origin verification  
        console.log( 'received flow event: ', event)  
    }  
)

Note: you may already have ‘message’ event listeners, and in Javascript, event listeners are processed in the order that they are declared in your code. This could become an issue if, for instance, you have two listeners capable of changing the application’s state (reloading the page, changing the location, etc.).

Which flows are covered?

Please refer to "Flow event type" column in the Flow Types page. The possible values for that column are

• None: This flow is not currently supported
• Manual: The user must click a button inside the flow to trigger the event
• Automatic: The event is triggered once the user reaches the end of the flow

Enabling flow events for your application

Flow events are disabled by default, but they can be enabled for your application by going into Flow settings in your developer portal account. Check the “Enable flow events on supported flows” checkbox to enable events for your application.