Permutive Developer Hub

Welcome to the Permutive developer hub. You'll find comprehensive guides and documentation to help you start working with Permutive as quickly as possible, as well as support if you get stuck. Let's jump right in!

API Reference

Permutive JavaScript SDK

The Permutive SDK provides access to all public API methods from within the browser.

Before you start, you'll need an account at Permutive.com. If you need any help with our SDK email support@permutive.com.

Installation

When creating a new project on the Permutive Dashboard, you'll be taken through a guided setup with the JavaScript SDK. We also include a Default integration, to start tracking some basic events about usage on your site. This provides some base data to play with.

If you'd prefer to set up manually, follow the installation instructions below.

To get started, first paste the code snippet below into the <head> and </head> tags of your HTML pages. Make sure to replace <PROJECT_ID> with your project's ID, and <API_KEY> with a public API key for the project.

<!-- start Permutive -->
<script>!function(n,e,o,r,i){if(!e){e=e||{},window.permutive=e,e.q=[],e.config=i||{},e.config.projectId=o,e.config.apiKey=r,e.config.environment=e.config.environment||"production";for(var t=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],c=0;c<t.length;c++){var f=t[c];e[f]=function(n){return function(){var o=Array.prototype.slice.call(arguments,0);e.q.push({functionName:n,arguments:o})}}(f)}}}(document,window.permutive,"<PROJECT_ID>","<API_KEY>",{});</script><script async src="https://cdn.permutive.com/<PROJECT_ID>-web.js"></script>
<!-- end Permutive -->

The snippet will asynchronously load the JavaScript SDK, whilst allowing you to start tracking events straight away.

Important

As the JavaScript SDK installation is publicly readable in the HTML's source code, make sure you're using the Public API Key.

Browser Support

The Permutive JavaScript tag supports all modern web browsers including Chrome, Firefox, Edge, IE, Safari and Opera. We use modern JavaScript features such as web workers to ensure our tag is performant and doesn't impact the page or user experience. As a result, we don't support older versions of IE (IE9 and below) or Opera Mini.

Track an Event

Once the Permutive JavaScript code snippet has been added, you can start tracking events by calling the permutive.track method.

// Track an "EmailSubscription" event, with the property
// `newletter` set as `true`. 
permutive.track('EmailSubscription', {
  newsletter: true
});

You can pass in additional options via the options parameter.

var options = {
  success: function(event) {
    console.log("Tracked a new " + event.name + "event.");
  }, 
  error: function(errors) {
  }
}

permutive.track('EmailSubscription', {
  newsletter: true
}, options);

Permutive enforces event schemas to ensure data consistency and validity

If an event doesn't match the expected schema, it will be rejected and a 400 error returned. Event schemas are viewable in the dashboard.

To migrate an event schema, please email support.

Retrieving Individual Segment States

Segments are computed from a user's events, and can be used to answer questions about the user. Segments can be created in dashboard with the Segment Builder. They can then be referenced by their unique code from within the JavaScript SDK.

For example, we might create an IsEngaged segment which checks to see if a user has two or more Pageview events. The dashboard will show a unique segment code for this segment - which in this example we will assume to be 1010. To check the state of this segment in Javascript, we can use permutive.segment:

permutive.segment(1010, function(result) {
  if (result) {
    // The user meets the isEngaged criteria
  } else {
    // The user does not meet the criteria
  }
});

This segment will return true if two or more Pageview events has been tracked, and false if not.

Retrieving All Current Segments

You can also retrieve an entire list of Permutive segments that the user is currently in. The SDK exposes a method, permutive.segments, for this purpose. As usual, this method takes a callback function which you can use to handle the result. The callback function should accept a single argument, segments, which will be a list of segment codes which correspond to all the segments that the user is currently in.

permutive.segments(function(segments) {
  for (var idx in segments) {
    // The user is currently in this segment
    console.log("User is currently in Permutive segment: " + segments[idx]);
  }
});

Retrieving Query States

If you need to build more powerful real-time features than segments can offer, you can look at using Permutive queries. While segments can be used to compute a real-time boolean value (true or false), queries can be used to compute other real-time information, such as aggregate values. Furthermore, queries can also return multiple properties. For example, you could create a query which computes the minimum, maximum and average purchase value for a user.

To retrieve a query's state from Javascript, simply call permutive.query with the query code and handle the result in a callback function:

permutive.query(1234, function(result) {
  if (result.avg_order_value > 500) {
    // This is a high-value user - give them a special experience
  }
});

Query Code

This is a short, public identifier that every query has. It can be found in the dashboard under the Queries page in the Code column.

Realtime Triggers

Realtime triggers can be used to trigger functions when a user moves into a segment. The method takes the segment's code, the result property whose change will trigger our function, and a callback function which will be called once the segment's result property changes for the user. When using the trigger function with segments, the object passed through to your callback function will always contain a single property, result, with a boolean value.

Triggers will only fire for events which are being tracked on the current page, via the track method.

For example, we might want to trigger a popup asking for an email subscription when a user has registered five Pageview events. Handily the IsActiveUser default segment tracks whether a user has viewed 5 or more pages. We can then create a trigger which watches the result property, and fires a popup function when it becomes true.

permutive.trigger(1010, "result", function(obj){
  if (obj.result) {
    $("#email-subscription-popup").show();
    permutive.track("ShownEmailSubscriptionPopup", {});
  }
});

Important

The trigger event will fire only once, when the segment becomes true for the first time. For the example above this is when 5 pages are viewed. To return the current state of a segment instead, use permutive.segment.

Identifying Users

Permutive assigns each and every user a unique ID (a Permutive user ID), which is persisted in local storage so we can keep track of the user.

If you have your own internal login IDs, you can pass those into Permutive as aliases using permutive.identify. This is particularly useful if you want to continue storing data against a user as they move across domains or different devices.

/*
 * Associate all events tracked afterwards with
 * a user ID "6ad2c899-8e18-48d0-96a9-8f8763e7b9be".
 * All events retrieved afterwards will be those 
 * that belong to "6ad2c899-8e18-48d0-96a9-8f8763e7b9be".
 */
permutive.identify("6ad2c899-8e18-48d0-96a9-8f8763e7b9be");

Important

If you're using Permutive identities, make sure permutive.identify is the first thing you call when a user signs-in or becomes identifiable on your site. Calling permutive.identify may change the Permutive user ID against which events are tracked. If you track events prior to calling identify, those events will be lost unless it is the first time you've seen this user. As such, you should make sure identify is called as soon as possible after a user arrives on site.

You can also tag your aliases. In the above example, our SDK will automatically assign a tag default to the alias. However you can explicitly specify your own tags. This may be useful in certain scenarios, for example if:

  • You wish to identify users with more than one type of alias
  • You want to use a Permutive integration that requires you to send in a certain alias type

To send in alias tags, you must pass a list of objects to permutive.identify in the following format:

/*
 * Associate all events tracked afterwards with
 * an internal identifier for the user. Also register
 * an MD5 hash of the user's email address as an alias.
 */
permutive.identify([{
  "id": "918635528918",
  "tag": "internal"
}, {
  "id": "4E812201ADDB4289A1272E02B3C4F62D",
  "tag": "email_md5"
}]);

Important

In practice, you should not use a plaintext email addresses with permutive.identify.

To protect user privacy, generally only internal non-public identifiers should be used with permutive.identify. You can also send in a hashed email address as an alias, which may be required by some of our integrations which rely on the user's email address. However these must be tagged with one of our reserved alias tags, such as email_md5 or email_sha256.

Support

If you need support on the SDK, or have any questions please email us at support@permutive.com.