Skip to content
This repository has been archived by the owner on Apr 28, 2022. It is now read-only.

Writing Integrations

Jump to bottom
Andy edited this page Aug 5, 2019 · 14 revisions

We're huge fans of open-source, and we absolutely love getting contributions to the analytics.js ecosystem!

Anyone can write an analytics.js integration plugin, and martech partners can apply to expose their plugins to Segment customers via our catalog: https://segment.com/partners/.

Getting Set Up

To start, we'll get you set up with our development environment. All of our development scripts and helpers are written in node.js, so you'll want to install that first by going to nodejs.org.

Then you can fork an existing integration to get started. Here are some examples:

After forking analytics.js-integration-{repo} just cd into the folder and run make:

$ cd analytics.js-integration-{repo}
$ make

That will install all of our npm and component dependencies and compile the latest version of the development build to test against. You can now add your changes to the library, and run make test to make sure everything is passing still.

The commands you'll want to know for development are:

$ make               # re-compiles the development build of analytics.js for testing
$ make test          # runs all of the tests in your terminal
$ make test-browser  # runs all of the tests in your browser, for nicer debugging

Writing the Plugin logic

The plugin is simple. You'll want to import our integration base class.

Example

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

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

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

For the full API you'll use to implement your plugin, check out the readme in the repo

Facade

The base class library relies on segmentio/facade which is a helper that makes working with the input to Analytics.js easier, by handling lots of common cases in one place. Check out that repo to understand the methods made available to you on each corresponding message type that gets passed into your methods.

Writing Tests

Every contribution should be accompanied by matching tests. If you look inside of the test/ directory, you'll see we're pretty serious about this. That's because:

  1. analytics.js runs on tons of different types of browsers, operating systems, etc. and we want to make sure it runs well everywhere.
  2. It lets us add new features much, much more quickly.
  3. We aren't insane.

When adding your own integration, the easiest way to figure out what major things to test is to look at everything you've added to the integration prototype. You'll want to write testing groups for #initialize, #load, #identify, #track, etc. And each group should test all of the expected functionality.

The most important thing to writing clean, easy-to-manage integrations is to keep them small and clean up after each test, so that the environment is never polluted by an individual test.

Before releasing we’ll need to see a full suite of passing tests, including cross-browser testing in Sauce Labs. Your initial release should be 1.0.0.

If you run into any questions, check out a few of our existing integrations to see how we've done it.

Further Testing

Before submitting for approval, we encourage you to enable your newly built integration in your own Segment workspace so that you can see it load on a test website in order examine the data flow downstream to your own tool's interface. In order to do this:

  1. Make sure all NPM package information is saved in your Developer Center Web Plugins component
  2. Add your integration to a Segment Source within your workspace by navigating to: https://app.segment.com/goto-my-workspace/destinations/catalog/ - replacing with the slug you can find under App Info > Basic Info.
  3. Enable the integration with the relevant Settings configuration filled out and toggle on.

Contributing Checklist

To help make contributing easy, here's all the things you need to remember:

  • Add your integration file to /lib.
  • Create a new Integration constructor with the integration factory component.
  • Add your integration's default options with .option().
  • Add an initialize method to your integration's prototype.
  • Add methods you want to support to the prototype. (identify, track, pageview, etc.)
  • Write tests for all of your integration's logic.
  • Run the cross-browser tests and get everything passing.
  • Verify end to end with analytics.js.
Clone this wiki locally