Base factory for analytics.js integrations



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

The factory returns a barebones integration that has no logic, so that we can share common pieces of logic—like queueing before an integration is ready, providing a way to default options, etc—in one place.

Integrating with Segment

Interested in integrating your service with us? Check out our Partners pagefor more details.


var integration = require('@segment/analytics.js-integration');

var Custom = integration('Custom Analytics')

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


This library relies on segmentio/facadewhich is a helper that makes working with the input to Analytics.jseasier, by handling lots of common cases in one place.



Create a new Integrationconstructor with the given integration name. nameis the key with which users can initializethe integration.

.option(key, default)

Register a new option for the integration by key, with a defaultvalue.


Add a new mapping option by key. The option will be an array that the user can pass in of key -> valuemappings. This will also generated a #KEYmethod on the integration's prototype for easily accessing the mapping.

For example if your integration only supports a handful of events like Signed Upand Completed Order, you might create an mapping option called eventsthat the user would pass in, like so:

var MyIntegration = Integration('MyIntegration')

Which means that when the integration is initialized, it would be passed a mapping of eventsto use, like so:

new MyIntegration({
  events: [
    { key: 'Signed Up', value: 'Register' },
    { key: 'Completed Order', value: 'Purchase' }

Then later on, you can easily get all of the entries with a specific key, by calling this.events(key). For example:

MyIntegration.prototype.track = function(track){
  var matches = this.events(track.event());
  each(matches, function(value){


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


Mark the Integrationas assuming an initial pageview has happened when its Javascript library loads. This is important for integrations whose libraries assume a "pageview" in their interface as soon as the library loads, instead of exposing a .page()method or similar to call via Javascript.

This option changes the integration so that the very first call to pageactually initializes the integration, ensuring that the pageviews aren't accidentally duplicated.


Mark the Integrationas being ready to accept data after initializeis 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 Integrationas being ready to accept data after loadis called. This is true for integrations that need to wait for their library to load on the page to start recording data.


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


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


Identify the current user for the integration given an Identifyfacade. See the identifymethod docsfor more information.


Group the current account/organization/group/etc for the integration given an Groupfacade. See the groupmethod docsfor more information.


Transform a Pagefacadeinto a page view for the integration. See the pagemethod docsfor more information.

Identify a user.


Track an event with the integration, given a Trackfacade. See the trackmethod docsfor more information.


Alias two user identities given an Aliasfacade. See the aliasmethod docsfor more information.

以上是 @segment/analytics.js-integration 的使用教程帮助文档。

  • @segment/analytics.js-integration官网:官网
  • @segment/analytics.js-integration源码仓库:源码仓库


扫码加入 JavaScript 社区



欢迎加入 JavaScript 社区