Examples · Flourish for developers

Integrating with analytics platforms

The addAnalyticsListener function is designed so that it can be easily integrated with any analytics system. Here are some examples of how you might add a listener which relays the information to some commonly used analytics platforms:

Adobe Analytics

Flourish.addAnalyticsListener(function (event) {
    // Create a name for the event
    var event_name =
        (event.story_id ? "Flourish story " : "Flourish visualization ") +
        event.action;

    var properties = {};

    // Copy everything apart from the action name to the properties
    for (var key of Object.keys(event)) {
        if (event.hasOwnProperty(key) && key !== "action") {
            properties[key] = event[key];
        }
    }

    _satellite.track(event_name, properties);
});

Mixpanel

Flourish.addAnalyticsListener(function (event) {
    // Create a name for the event
    var event_name =
        (event.story_id ? "Flourish story " : "Flourish visualization ") +
        event.action;

    var properties = {};

    // Copy everything apart from the action name to the properties
    for (var key of Object.keys(event)) {
        if (event.hasOwnProperty(key) && key !== "action") {
            properties[key] = event[key];
        }
    }

    mixpanel.track(event_name, properties);
});

Google Analytics (using gtag.js)

Flourish.addAnalyticsListener(function (event) {
    var action = event.action;

    // Set a category for the event so you can identify that this was an engagement
    // with a Flourish
    var category = "flourish_engagement";
    // Set a label so you can identify what was engaged with.
    var label = event.story_id
        ? "Flourish story " + event.story_id
        : "Flourish visualization " + event.visualisation_id;

    var parameters = {
        event_category: category,
        event_label: label,
    };

    // Copy everything apart from the action name to the parameters
    for (var key of Object.keys(event)) {
        if (event.hasOwnProperty(key) && key !== "action") {
            parameters[key] = event[key];
        }
    }

    // Send the event to Google Analytics
    gtag("event", action, parameters);
});

Google Analytics (using Google Tag Manager)

Flourish.addAnalyticsListener(function (event) {
    var action = event.action;

    var category = "flourish_engagement";
    // Set a label so you can identify what was engaged with.
    var label = event.story_id
        ? "Flourish story " + event.story_id
        : "Flourish visualisation " + event.visualisation_id;

    var dataLayerEvent = {
        event: event.action,
        event_category: category,
        event_label: label,
        event_action: action,
        // Include any additional data from the event object.
    };

    Object.keys(event).forEach(function (key) {
        if (key !== "action") {
            dataLayerEvent[key] = event[key];
        }
    });

    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push(dataLayerEvent);
});

Setting triggers for analytics in Google Tag Manager

The following steps are for customers wanting to send Flourish events to GA4 when using GTM.

Configure GTM to listen to Data Layer events

In GTM, click on Variables in the left sidebar.
Under the User-Defined Variables section, click New.
Click on Variable Configuration and choose Data Layer Variable.
In the Data Layer Variable Name, enter the exact key name that was used when pushing to the dataLayer. In the example code above, these are rows 16, 17 and 18 - respectively, event_category, event_label and event_action.
Name your variable in the top left corner (eg. DLV - Event Category for event_category)
Repeat the same for the Event Label and Event Action

Triggers in GTM

Navigate to Triggers in GTM.
Create multiple triggers that listen to specific events - those are "mouse_enter", "mouse_leave", "click", "key_down", "play", "pause", or "slide_change". In other words, we need 7 different triggers, with each trigger only firing when the specific event action is being performed.
Create a New trigger.
The Trigger type should be Custom event.
For the Event Name, enter the exact name of the event, for example mouse_enter.
Set the trigger to fire on SOME custom events: the configuration should be to only fire when the DLV - Event Action (which was previously defined) equals mouse_enter.
Name your Trigger in the top left-hand corner, for example, Trigger - Flourish action mouse_enter.
Repeat steps 3-7 for all other custom events. If you don't want to track a specific event, you can just remove the relevant trigger. This makes it clearer and straightforward.

GA4 Event Tags

Click on Tags in the left sidebar and then click New.
Click on Tag Configuration and choose Google Analytics: GA4 Event.
Add your Measurement ID. Here are the relevant steps.
For the Event name, click on the Lego-like icon and choose the Data Layer variable we defined in the previous steps, {{DLV - Event Action}}.
Then, under Event Parameters, map the Data Layer Variables to the GA4 event parameters. This will ensure all this metadata gets sent to GA4:
1. Click Add Row.
2. For Event Parameter, add event_action, using exactly the same syntax as in the code.
3. For Event value, choose the Data Layer variable we defined earlier by clicking on the Lego-like icon. It will look like this: {{DLV - Event Action}}.
4. Repeat the same for the event category and for the event label.
In the Triggering section, choose ALL triggers created earlier.
Name your tag (e.g. GA4 Flourish Interaction Event).
Click Save.