The base integration factory used to create custom analytics integrations for analytics.js.

var integration = require('integration');

var Custom = integration('Custom Analytics')
  .global('_custom')
  .assumesPageview()
  .readyOnInitialize();

Custom.prototype.track = function (event, properties) {
  window._custom.push(['track', event, properties]);
};

Create a new Integration constructor with the given integration name. name is the key with which users can initialize the integration.

Register a new global variable key that the Integration uses. If this key already exists on window when initialize is called, it will return early, ensuring that setup logic and libraries aren't loaded twice.

Mark the Integration as assuming an initial pageview has happened when its Javascript library loads. This way the very first call to page actually initializes the integration, ensuring that the first page isn't counted twice.

Mark the Integration as being ready after initialize is called. This is true of integrations that create queues in their snippets so that they can record data before their library has been downloaded.

Mark the Integration as being ready after load is called. This is true for integrations that need to wait for their library to load to record data.

Create mapping method with name, this will default an option to [], to learn more about mappings see #events method as an example.

Initialize the integration. This is where the typical 3rd-party Javascript snippet logic should be. If the integration assumes an initial pageview, initialize will be called with the page method's arguments.

Get all events that match event, for example if your integration only supports a handful of events like Signed Up and Completed Order you would use this method.

//
// Example
//

var MyIntegration = Integration('MyIntegration')
  .mapping('events');

//
// In Our UI the user has those options:
//
// "Register" -> "Signed Up"
// "Purchase" -> "Completed Order"
//
// when initialized your integration.events will be:
//
// [{ key: 'Register', value: 'Signed Up' }, { key: 'Purchase', 'Completed Order' }];
//

MyIntegration.prototype.track = function(track){
  var events = this.events(track.event());

  // we use each because the user might map multiple events to
  // a single "Signed Up" or "Completed Order"
  each(events, function(event){
    self.debug('track %s -> %s', track.event(), event);
    window._myglobal.push(event, track.properties());
  });
};

Load the integration's 3rd-party Javascript library, and callback(err, e). The loading logic should be pulled out of the snippet from initialize and placed here.

Label a page with an optional name and properties.

Identify a user by an optional id with optional traits.

Identify a group of users, like an "account" or "organization" or "team" by an optional id with optional properties.

Track an event triggered by the user with optional properties.

Alias a user's identify from an old ID to a new one. The old ID is optional and defaults to the user's current automatically generated distinct ID.

MIT