Writing Integrations

We're huge fans of open-source, and we absolutely love getting good contributions to analytics-android! Integrations are available to thousands of Segment customers and we have hundreds of integrations in already in our queue, so it's important that you do the following before writing a new integration.

By working on an integration contribution to Segment you agree to the Segment Platform Partners Agreement.

You can apply to be a Segment partner: 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 after forking analytics.js-integration- just cd into the folder and run make:

$ cd analytics.js-integration-mixpanel
$ 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 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.

Manual Testing

When the local tests pass, you can try building and testing with a local version of analytics.js. During testing you can load your integration’s settings locally by calling analytics.initialize():. When your integration goes live, Segment will take care of analytics.initialize in our custom-rendered version of analytics.js for each customer.

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.