Incisively DOCS back to main site

JavaScript SDK

A simple wrapper around the Incisively API that makes website / web app integration as easy as possible.

Setup

Include the library, then create an instance for your Account ID like so:

<script src="//cdn.incisive.ly/incisively.min.js"></script>
<script>
  window.incisively = new Incisively(1234567);
</script>

Now you’re ready to roll.

Important note: The JavaScript SDK is designed to run in a browser only. This is because it relies on document.cookie to store details for each client. For node.js or other server-side implementations, you should use the REST API directly.

If your website uses multiple subdomains, you must pass a second option to the constructor to set the cookie domain. For instance, if your website uses browse.example.org and payment.example.org, you should set it like so:

new Incisively(1234567, '.example.org')

Suggestions

Whenever you want to use an optimised value, ask Incisively to suggest it.

incisively.suggest(options);

options is an object with the following properties:

key type description
lab String The Lab ID from which you want a suggestion. (This can be found in the web app.)
segment String optional The segment ID for which to cluster this user into. Can be any string. Try to keep buckets large enough that it will have enough users to optimize over though.
ignore List(String) optional A list of variant names which will not be suggested. Useful for excluding specific variants for spefic users.
force String optional Force a specific variant, can still be rewarded.
success Function The suggestion callback, which will be passed an object detailing the suggestion. Its content property contains the value to use in your application.
failure Function optional The callback to handle a case where the request timed out or otherwise errored (e.g. network issues).
timeout Int optional The maximum acceptable time in milliseconds for the suggestion to arrive. If the request takes longer than this, the success callback will not be fired (and failure callback will be fired if you specified one).

N.B. Do not cache the suggestion under any circumstances, or else the lab will become biased and will no longer maximise results. A suggestion must be requested every time.

Example

Suppose we have a lab with ID cb3e1f60-1006-441a-a74f-167f4dcfb801, which is set up to optimise a heading inside <h1 id="myElement"></h1>. The heading must be set within 1 second, or else we want to fall back to a safe default. We could use the following implementation:

var myElement = document.querySelector('#myElement');

incisively.suggest({
  lab: 'cb3e1f60-1006-441a-a74f-167f4dcfb801',
  timeout: 1000,
  success: function(suggestion) {
    myElement.innerHTML = suggestion.content;
  },
  failure: function() {
    myElement.innerHTML = 'Default Heading';
  }
});

Rewards

When a goal occurs, immediately inform Incisively of the lab(s) it is applicable to using the reward method.

incisively.reward(options);

options is an object with the following properties:

key type description
lab String The Lab ID whose suggestion you wish to reward.
context Object optional Any additional context around the reward. (Currently this is only used by Real Value labs to provide a reward value.)
callback Function optional Any code that should execute once the reward has been sent (e.g. navigation to another page).

You don’t need to worry about whether a suggestion has actually been requested for this lab - the SDK will take care of figuring out whether or not a reward is appropriate.

You may also reward multiple labs for a given goal - just call reward once for each Lab ID.

Examples

Suppose the goal of lab cb3e1f60-1006-441a-a74f-167f4dcfb801 is to maximise clickthrough rate to a product page. You might place the following code on the product page:

incisively.reward({
  lab: 'cb3e1f60-1006-441a-a74f-167f4dcfb801'
});

Or, suppose the lab is a Real Value lab designed to maximise basket value, you might place the following code on the ‘Payment Complete’ page:

var basketValue = /* your code that returns the basket value */;

incisively.reward({
  lab: 'cb3e1f60-1006-441a-a74f-167f4dcfb801',
  context: {
    value: basketValue
  }
});

Events

Send events to Incisively using the track method:

incisively.track(eventName, [eventProperties]);

The arguments are:

argument type description
eventName String Any unique name that describes this event. We recommend following a noun_verb pattern, such as product_view or checkout_complete.
eventProperties Object optional Arbitrary attributes associated with this particular event. Each attribute value must be either a JSON number, string or bool. Events with attribute values of other types will be rejected.

You must call track after any calls to suggest have been made, otherwise Incisively can’t associate those suggestions with the event(s) being tracked. (You don’t need to worry about waiting for suggestions to fire their callbacks, though – the SDK takes care of that.)

Batching

When you have a large number of events to send, rather than firing off many separate requests to Incisively, you can use Batch Mode to efficiently send many events in a single request:

incisively.batch(true);
incisively.track('category_view', { category_name: 'Special Offers' });
incisively.track('product_view', { product_id: 'ACEJUMPBL', product_name: 'Ace Blue Jumper' });
incisively.track('product_view', { product_id: 'BASICWIDGET', product_name: 'Basic Widget' });
// ...
incisively.track('product_view', { product_id: 'ACMEFOO', product_name: 'Acme Foo Multipack' });
incisively.batch(false);

If you use batch mode, you must call batch(false) when you are done adding events, so that the SDK can send the data back to Incisively.

Examples

Imagine you want to start finding optimisation opportunities, as well as seeing how different variants may be affecting other metrics or particular attribute cohorts of your existing site. You start considering events that you care about, and decide to start with newsletter signups, checkouts and product page views. Let’s start tracking them.

We’ll start with newsletter signups. Simply add the following call to your ‘Thanks for signing up’ page:

incisively.track('newsletter_signup');

Next on the list is checkouts. You might want to be able to segment on some additional detail related to these events, so this time you provide the optional properties object:

var orderValue = /* your code that returns the order value */;
var deliveryOption = /* your code that returns the selected delivery option */;

incisively.track('checkout_complete', {
  order_value: orderValue,
  delivery_option: deliveryOption
});

Finally, you add product page view tracking. You already have a Lab running on that screen to optimise the Call To Action design, so you make sure that you place the track call after the suggest call:

/* existing code */
incisively.suggest({
  lab: '0e8c599d-309e-4f51-a899-34759d2c7bcb',
  success: function(suggestion) {
  	// some code that sets the CTA design
  }
});

/* new code (assuming a suitable `product` is already defined) */
incisively.track('product_page_view', {
  product_id: product.id,
  product_revenue: product.price
});

Once you deploy these changes, your event tracking is up and running.