@humany/widget-analytics

@humany/widget-analytics

Analytics Plugins for Humany Widgets.

Currently this package only contains support for Google Analytics, more providers is scheduled to be supported.

Basic Setup

humany.configure((config) => {
  config.plugin(GoogleAnalyticsPlugin, {
    action: ({ type, resolve }) => {
      resolve()
        .then(data => {
          console.log('Emitted event type with emitted data', type, data);
        });
    },
    config: {
      trackingId: 'UA-XXXXXXXX-X',
      trackingName: 'your-tracking-name',
    },
  });
});

Supported Providers

• Google Analytics

Customization

Overrides

It is possible to capture and override the default behavior in order to customize the data you want to send to your provider.

To override the data add the overrides property to the plugin configuration.

The overrides property is a function which expects a string which is the emitted event type. Inside the overrides function you want to check for the type you want to override and then return an object containing the data you want to send to your provider.

The emittedData is the original emitted data and the gaEventData is the data you would send to your provider, if not overriden.

Keep in mind that in order to access the data you need to resolve the resolve promise.

In order to ignore a specific event simply return false for the specific event type you want to ignore. You can do this before resolving the promise.

humany.configure((config) => { 
  config.plugin(GoogleAnalyticsPlugin, {
    action: ({ type, resolve })  => {
      resolve()
        .then(data => {
          console.log('Emitted event type with emitted data', type, data);
        });
    },
    config: {
      trackingId: 'UA-XXXXXXXX-X',
      trackingName: 'your-tracking-name',
    },
    overrides: (type) => (resolve) => {
      // to ignore an event, return false
      if (type === 'NoAnswer') {
        return false;
      }
  
      // resolve the promise containing the emitted data
      return resolve()
        .then(({ emittedData, gaEventData }) => {
          // specify the event type you want to override
          if (type === 'Interact') {
            // return an object with the new data
            return {
              ...gaEventData,
              eventLabel: `My Custom Event Label`,
            };
          }
  
          // if its any other event, return the original event data
          return gaEventData;
        });
    },
  });
});

Dispatch

In some situations you want to handle the actual emitting to your provider by yourself. In those cases you can provide the dispatch property to the plugin settings.

The dispatch property overrides the sending of data to your provider and instead let you capture it and handle it accordingly. The dispatch property accepts a function that receives an object in the following format:

• Type: The dispatched action type
• gaData: Google Analytics data that would normally be dispatched
• emittedData: The original event data which contains additional data
• credentials: Your Google Analytics credentials, if provided in plugin settings

Example of how to override the dispatch method:

humany.configure((config) => { 
  config.plugin(GoogleAnalyticsPlugin, {
    action: (...),
    dispatch: ({ type, gaData, emittedData, credentials }) => {
      console.log('Emitted type', type);
      console.log('Google Analytics event data', gaData);
      console.log('Original emitted data', emittedData);
      console.log('Your Google Analytics configuration if provided', credentials);
    },
  });
});

Create your own Analyzers

If you need to emit events other than the default events found in the @humany/widget-tracking package you can create your own Analyzer and inject them to the analytics plugin configuration.

The purpose of an Analyzer is to listen for events and emit actions, which will be available to listen for in your analytics plugin.

Example of a custom Analyzer:

class CustomAnalyzer {
  constructor(container, emit) {
    const { events } = container.get('$widget');

    // Here you listening for the event "widget:move-outside-viewport" 
    // and dispatches a custom event (MoveOutsideViewport) that you can listen to in your plugin
    events.subscribe('widget:move-outside-viewport', (e, data) => {
      emit('MovedOutsideViewport', {
        message: 'moved outside viewport',
      });
      
      // OR you can use a function which returns a promise
      emit('MovedOutsideViewport', () => Promise.resolve({
        message: 'moved outside viewport',
      }));
    });
  }
}

Above is an example of a custom Analyzer that listens for events on the widget. When the event, in this example the widget:move-outside-viewport event, is triggered it will emit an event called MovedOutsideViewport (you can give your events any name you want).

To listen for your MovedOutsideViewport event you simply look for it in the action method in your plugin configuration.

In order to send data to your provider for your custom event you need to override the behavior of the emitted event in the overrides function.

Injecting your custom Analyzer to the plugin

You need to inject your Analyzer to your plugin configuration in order to use it. The plugin accepts an array of Analyzer in it's options.

humany.configure((config) => { 
  config.plugin(GoogleAnalyticsPlugin, {
    action: ({ type, resolve })  => {
      resolve()
        .then(data => {
          console.log('Emitted event type with emitted data', type, data);
        });
    },
    config: {
      trackingId: 'UA-XXXXXXXX-X',
      trackingName: 'your-tracking-name',
    },
    analyzers: [CustomAnalyzer], // inject your Analyzer(s) here
    overrides: (type) => (resolve) => {
      // resolve the promise containing the emitted data
      return resolve()
        .then(({ emittedData, gaEventData }) => {
          // look for your custom event
          if (type === 'MovedOutsideViewport') {
            // return an object with the new data
            return {
              ...gaEventData,
              eventLabel: `My Custom Event`,
            };
          }
  
          // if its any other event, return the original event data
          return gaEventData;
        });
    },
  });
});