Analytics.js

Analytics.js makes it dead simple to send your data to any tool without having to learn, test or implement a new API every time. Instead, you can turn on any new tool with the flick of a switch.

All of our libraries are open-source, so you can view Analytics.js on Github, or check out our mobile and server-side libraries too.

Getting Started

To get started with Analytics.js check out our Setting up Analytics.js tutorial which will help you install analytics tracking on your site in just a few minutes. Once you’ve installed the library, read on for the detailed API reference!

Identify

The identify method is how you tie one of your users and their actions to a recognizable userId and traits. You can read more about how to set it up or about how it works.

Here’s what an identify call looks like, along with it’s method signature:

analytics.identify('1e810c197e', {
  name: 'Bill Lumbergh',
  email: 'bill@initech.com'
});
analytics.identify([userId], [traits], [options], [callback]);
userId String, optional The database ID for this user. If you don’t know who the user is yet, you can omit the userId and just record traits. You can read more about identities in the identify reference.
traits Object, optional A dictionary of traits you know about the user, like their email or name. You can read more about traits in the identify reference.
options Object, optional A dictionary of extra options for the call.
callback Function, optional A callback function that will be called after a short timeout, giving the browser time to send the identify requests first. Note that it does not wait for all of the integrations to actually receive the requests.

All of the arguments are optional. So you can actually call identify without a userId if you want to tag an anonymous user with a set of traits, like so:

analytics.identify({
  email: 'bill@initech.com',
  newsletter: true,
  industry: 'Technology'
});

For example, you might do that when someone signs up for a newsletter but hasn’t yet created an account on your site. We’ll store those traits interally, and carry them over the next time you call identify with a userId.

You can also omit both traits and options—passing the callback as the second argument—if all you want to do is associate an ID, like so:

analytics.identify('1e810c197e', function(){
  // Do something after the identify request has been sent, like
  // submit a form or change the URL.
});

Track

The track method lets you record any actions your users perform. You can read more about how to set it up or about how it works.

Here’s a basic example, along with the track method signature:

analytics.track('Signed Up', {
  plan: 'Startup',
  source: 'Analytics Academy'
});
analytics.track(event, [properties], [options], [callback]);
event String The name of the event you’re tracking. You can read more about the track method and what event names we recommend.
properties Object, optional A dictionary of properties for the event. If the event was 'Added to Cart', it might have properties like price and productType.
options Object, optional A dictionary of extra options for the call.
callback Function, optional A callback function that gets called after a short timeout, giving the browser time to make the track requests first. Also checkout the trackLink and trackForm helpers.

The only required argument to track in Analytics.js is an event name string.

Page

The page method lets you record page views on your website, along with optional extra information about the page being viewed.is being viewed.

It’s already included in your snippet just after the call to load, so in most cases you don’t ever need to touch it. However, if you want to add extra information, like tagging the page with a name or category, read on!

Note that you must call this method at least once per page load! (That’s why we throw it in the snippet for convenience.) If you have a single page app you can call it multiple times, whenever a new page view occurs.

Here’s a basic example, along with the page method signature:

analytics.page('Signup');
analytics.page([category], [name], [properties], [options], [callback]);
category String, optional The category of the page. Useful for things like ecommerce where many pages might live under a larger category. Note: if you only pass one string to page we assume it’s a name, not a category. You must include a name if you want to send a category.
name String, optional The name of the of the page, for example Signup or Home.
properties Object, optional A dictionary of properties of the page. We’ll automatically send url, title, referrer and path, but you can add your own too!
options Object, optional A dictionary of extra options for the call.
callback Function, optional A callback function that gets called after a short timeout, giving the browser time to make the page requests first.

Alias

The alias method combines two previously unassociated user identities. This comes in handy if the same user visits from two different devices and you want to combine their history.

Some providers also don’t alias automatically for you when an anonymous user signs up (like Mixpanel), so you need to call alias manually right after sign up with their brand new userId.

Here’s a basic example along with the alias method signature:

analytics.alias('019mr8mf4r');
analytics.alias(userId, [previousId], [options], [callback]);
userId String The new User ID you want to associate the user with.
previousId String, optional The previous ID that the user was recognized by. This defaults to the currently identified user’s ID if you don’t pass one. In most cases you don’t need to worry about this argument.
options Object, optional A dictionary of extra options for the call.
callback Function, optional A callback function that gets called after a short timeout, giving the browser time to make the alias requests first.

trackLink is a helper that binds a track call to whenever a link is clicked. Usually the page would change before you could call track, but with trackLink a small timeout is inserted to give the track call enough time to fire.

var link = document.getElementById('free-trial-link');

analytics.trackLink(link, 'Clicked Free-Trial Link', {
  plan: 'Enterprise'
});
element(s) Element or Array The link DOM element you want to track clicks on. You can also pass an array of link elements, or a jQuery object. Note: This must be an element, not a CSS selector.
event String or Function The name of the event which gets passed straight to the track method. You can also pass a function here which returns the name of the event instead, and which will be called with the link that was clicked.
properties Object or Function, optional A dictionary of properties which get passed straight to the track method. You can also pass a function here which returns a dictionary of properties instead, and which will be called with the link that was clicked.

Track Form

trackForm is a helper that binds a track call to a form submission. Usually the page would change before you could call track, but with trackForm a small timeout is inserted to give the track call enough time to fire.

var form = document.getElementById('signup-form'); 

analytics.trackForm(form, 'Signed Up', {
  plan: 'Premium',
  revenue: 99.00
});
form(s) Element or Array The form DOM element you want to track submissions for. You can also pass an array of form elements, or a jQuery object. Note: trackForm takes an element, not a CSS selector.
event String or Function The name of the event which gets passed straight to the track method. You can also pass a function here which returns the name of the event instead, and which will be called with the form that was submitted.
properties Object or Function, optional A dictionary of properties which get passed straight to the track method. You can also pass a function here which returns a dictionary of properties instead, and which will be called with the form that was submitted.

Ready

The ready method allows you to pass in a callback that will be called as soon as your analytics integrations have been initialized. It’s like jQuery’s ready method, except for integrations.

If you want to make calls to a specific integration, like adding an extra setting to Mixpanel, use a ready callback so that you’re guaranteed to have access to the Mixpanel object.

analytics.ready(function(){
  window.mixpanel.set_config({ verbose: true });
});
analytics.ready(callback);
callback Function A callback you want to fire after all integrations have loaded.

Advanced Options

The alias, group, identify, page and track calls can all be passed an object of options for the call. That lets you to do things like turn certain integrations on or off, or send additional context about a call.

You can read more about turning specific integrations on or off in the integrations reference. Here’s an example showing an identify call that only goes to Mixpanel and KISSmetrics:

analytics.identify('019mr8mf4r', {
  email: 'achilles@segment.io',
  plan: 'Premium'
}, {
  integrations: {
    'All': false,
    'Mixpanel': true,
    'KISSMetrics': true
  }
});

You can also use the options object to send additional context about a request, which you can read more about here. An example might be sending a specific IP address:

analytics.identify('019mr8mf4r', {
  email: 'achilles@segment.io',
  plan: 'Premium'
}, {
  context: {
    ip: '233.28.8.12'
  }
});

Event Emitting

Analytics.js emits events whenever you call alias, group, identify, track or page. That way you can listen to those events and run your own custom code. For example, you could use them to send data to your own custom integration:

analytics.on('track', function(event, properties, options){
  bigdata.push(['recordEvent', event]);
});

If you ever have any questions, or see anywhere we can improve our documentation, just shoot us an email at friends@segment.io!