Skip to content

amplitude/Amplitude-JavaScript

Repository files navigation

Circle CI

Amplitude-Javascript

Setup

  1. If you haven't already, go to http://amplitude.com and register for an account. You will receive an API Key.
  2. On every page that uses analytics, paste the following Javascript code between the <head> and </head> tags:
<script type="text/javascript">
  (function(t,e){var n=t.amplitude||{};var r=e.createElement("script");r.type="text/javascript";
  r.async=true;r.src="https://d24n15hnbwhuhn.cloudfront.net/libs/amplitude-2.6.1-min.gz.js";
  r.onload=function(){t.amplitude.runQueuedFunctions()};var s=e.getElementsByTagName("script")[0];
  s.parentNode.insertBefore(r,s);var i=function(){this._q=[];return this};function o(t){
  i.prototype[t]=function(){this._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
  return this}}var a=["add","set","setOnce","unset"];for(var u=0;u<a.length;u++){o(a[u]);
  }n.Identify=i;n._q=[];function c(t){n[t]=function(){n._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
  }}var l=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify"];
  for(var p=0;p<l.length;p++){c(l[p])}t.amplitude=n})(window,document);

  amplitude.init("YOUR_API_KEY_HERE");
</script>
  1. Replace YOUR_API_KEY_HERE with the API Key given to you.
  2. To track an event anywhere on the page, call:
amplitude.logEvent('EVENT_IDENTIFIER_HERE');
  1. Events are uploaded immediately and saved to the browser's local storage until the server confirms the upload. After calling logEvent in your app, you will immediately see data appear on Amplitude.

Tracking Events

It's important to think about what types of events you care about as a developer. You should aim to track between 5 and 50 types of events on your site. Common event types are actions the user initiates (such as pressing a button) and events you want the user to complete (such as filling out a form, completing a level, or making a payment). Shoot me an email if you want assistance determining what would be best for you to track.

Settings Custom User IDs

If your app has its own login system that you want to track users with, you can call setUserId at any time:

amplitude.setUserId('USER_ID_HERE');

A user's data will be merged on the backend so that any events up to that point from the same browser will be tracked under the same user.

You can also add the user ID as an argument to the init call:

amplitude.init('YOUR_API_KEY_HERE', 'USER_ID_HERE');

Setting Event Properties

You can attach additional data to any event by passing a Javascript object as the second argument to logEvent:

var eventProperties = {};
eventProperties.key = 'value';
amplitude.logEvent('EVENT_IDENTIFIER_HERE', eventProperties);

User Property Operations

The SDK supports the operations set, setOnce, unset, and add on individual user properties. The operations are declared via a provided Identify interface. Multiple operations can be chained together in a single Identify object. The Identify object is then passed to the Amplitude client to send to the server. The results of the operations will be visible immediately in the dashboard, and take effect for events logged after.

  1. set: this sets the value of a user property.

    var identify = new amplitude.Identify().set('gender', 'female').set('age', 20);
    amplitude.identify(identify);
  2. setOnce: this sets the value of a user property only once. Subsequent setOnce operations on that user property will be ignored. In the following example, sign_up_date will be set once to 08/24/2015, and the following setOnce to 09/14/2015 will be ignored:

    var identify = new amplitude.Identify().setOnce('sign_up_date', '08/24/2015');
    amplitude.identify(identify);
    
    var identify = new amplitude.Identify().setOnce('sign_up_date', '09/14/2015');
    amplitude.identify(identify);
  3. unset: this will unset and remove a user property.

    var identify = new amplitude.Identify().unset('gender').unset('age');
    amplitude.identify(identify);
  4. add: this will increment a user property by some numerical value. If the user property does not have a value set yet, it will be initialized to 0 before being incremented.

    var identify = new amplitude.Identify().add('karma', 1).add('friends', 1);
    amplitude.identify(identify);

Note: if a user property is used in multiple operations on the same Identify object, only the first operation will be saved, and the rest will be ignored. In this example, only the set operation will be saved, and the add and unset will be ignored:

var identify = new amplitude.Identify()
    .set('karma', 10)
    .add('karma', 1)
    .unset('karma');
amplitude.identify(identify);

Setting Multiple Properties with setUserProperties

You may use setUserProperties shorthand to set multiple user properties at once. This method is simply a wrapper around Identify.set and identify.

var userProperties = {
    gender: 'female',
    age: 20
};
amplitude.setUserProperties(userProperties);

Tracking Revenue

To track revenue from a user, call

amplitude.logRevenue(9.99, 1, 'product');

The function takes a unit price, a quantity, and a product identifier. Quantity and product identifier are optional parameters.

This allows us to automatically display data relevant to revenue on the Amplitude website, including average revenue per daily active user (ARPDAU), 7, 30, and 90 day revenue, lifetime value (LTV) estimates, and revenue by advertising campaign cohort and daily/weekly/monthly cohorts.

Opting User Out of Logging

You can turn off logging for a given user:

amplitude.setOptOut(true);

No events will be saved or sent to the server while opt out is enabled. The opt out setting will persist across page loads. Calling

amplitude.setOptOut(false);

will reenable logging.

Configuration Options

You can configure Amplitude by passing an object as the third argument to the init:

amplitude.init('YOUR_API_KEY_HERE', null, {
    // optional configuration options
    saveEvents: true,
    includeUtm: true,
    includeReferrer: true,
    batchEvents: true,
    eventUploadThreshold: 50
});
option description default
saveEvents If true, saves events to localStorage and removes them upon successful upload.
NOTE: Without saving events, events may be lost if the user navigates to another page before events are uploaded.
true
savedMaxCount Maximum number of events to save in localStorage. If more events are logged while offline, old events are removed. 1000
uploadBatchSize Maximum number of events to send to the server per request. 100
includeUtm If true, finds utm parameters in the query string or the __utmz cookie, parses, and includes them as user propeties on all events uploaded. false
includeReferrer If true, includes referrer and referring_domain as user propeties on all events uploaded. false
batchEvents If true, events are batched together and uploaded only when the number of unsent events is greater than or equal to eventUploadThreshold or after eventUploadPeriodMillis milliseconds have passed since the first unsent event was logged. false
eventUploadThreshold Minimum number of events to batch together per request if batchEvents is true. 30
eventUploadPeriodMillis Amount of time in milliseconds that the SDK waits before uploading events if batchEvents is true. 30*1000
deviceId Custom device ID to set Randomly generated UUID

Advanced

This SDK automatically grabs useful data about the browser, including browser type and operating system version.

By default, no version name is set. You can specify a version name to distinguish between different versions of your site by calling setVersionName:

amplitude.setVersionName('VERSION_NAME_HERE');

User IDs are automatically generated and stored in cookies if not specified.

Device IDs are generated randomly, although you can define a custom device ID setting it as a configuration option or by calling:

amplitude.setDeviceId('CUSTOM_DEVICE_ID');

You can pass a callback function to logEvent, which will get called after receiving a response from the server:

amplitude.logEvent("EVENT_IDENTIFIER_HERE", null, callback_function);

The status and response from the server are passed to the callback function, which you might find useful. An example of a callback function which redirects the browser to another site after a response:

var callback_function = function(status, response) {
    if (status === 200 && response === 'success') {
        // do something here
    }
    window.location.replace('URL_OF_OTHER_SITE');
};

You can also use this to track outbound links on your website. For example you would have a link like this:

<a href="javascript:trackClickLinkA();">Link A</a>

And then you would define a function that is called when the link is clicked like this:

var trackClickLinkA = function() {
    amplitude.logEvent('Clicked Link A', null, function() {
        window.location='LINK_A_URL';
    });
};

You can also pass a callback function to init, which will get called after the SDK finishes its asynchronous loading. Note: no values are passed to the init callback function:

amplitude.init('YOUR_API_KEY_HERE', 'USER_ID_HERE', null, callback_function);

In the case that optOut is true, then no event will be logged, but the callback will be called. In the case that batchEvents is true, if the batch requirements eventUploadThreshold and eventUploadPeriodMillis are not met when logEvent is called, then no request is sent, but the callback is still called. In these cases, the callback will be called with an input status of 0 and response 'No request sent'.