Customization & Personalization using the JS API

Javascript API Documentation

Introduction

The iridize Javascript API (JS API) can be used to customize and personalize the your end-users experience. The API makes it is possible to set end-user fields which can be used for setting complex activation rules for your guides. Additionally, you may use the API for personalizing and dynamically set the content of iridize guides. The API also extends the support for single page applications (SPA), ensuring that customers with SPAs can enjoy the full range of iridize features that non SPAs can.

The API can also be used to attain granular control over the activation of iridize guides within your web application. Using the API you can start or stop guides based on your custom business logic, as well as monitor the progress of a specific customer through your guides, by binding to guide-level or step-level events.

Using the API

The API commands are issued by a call to the iridize method, which is defined on the global scope as part of the iridize JS embed scriptlet. As such, API command can be issued from any JS code that is executed after the embed scriptlet is run. The best practice recommended by iridize is to issue the API commands from a script tag embedded directly after the iridize embed scriptlet.

NOTE:While API commands can be issued before the main iridize JS script is loaded and run, they will only be executed when iridize is fully loaded. The order in which commands were issued is preserved, making the loading and scheduling process transparent to the developer. The single exception to this rule is that the first call to api.fields.set in the queue will be executed before all other API commands when the iridize script is loaded.

The anatomy of iridize calls:

Calls to the iridize API are of the following generic form:

iridize("api.foo.bar", {callData:theData},function optionalCallback(data) {});

The first argument is a string indicating the command to be run. For example, “api.guide.start”, is the name of command for starting a guide.

The second argument is a plain object serving as a dictionary of data passed to the API command. For example, when starting a guide with an API name “foobar” using the API the second argument would be of the form {apiName:”foobar”}.

The third argument is a callback function that is run when asynchronous API calls are done or when an API event occurs. This argument is optional and is only executed for API methods that support it, as indicated in the specific method documentation. If data is to be passed to the callback function it is done in the form of a plain object, with the passed data as properties. The specific properties are specified in the individual methods documentation.

NOTE: The second argument is optional for commands that do not require passing data, but it cannot be omitted if a callback function is supplied as the third argument.In such a case it is recommended to pass and empty plain object, {}, as the second argument.

Customization and Personalization Methods

End-User Field Methods:

With iridize you can set complex activation rules for your guides, based on individual end-user fields. For example, you may wish to automatically start an introductory guide for every new user once. Or you may want to make a guide available for a user two days after she have viewed a different guide. In order to be able to use such rules, you need to set some fields for your end-users, using the API.

api.fields.set

Set fields for the current end-user. This method expects a dictionary of one or more fields as the second argument. For example, the iridize embed code includes the following call (commented out) by default:

iridize("api.fields.set", {user_id:"USER_ID_GOES_HERE",joined_at:UNIXEPOCH_TIMESTAMP});

where we set the reserved-name field “user_id”, which can be any string uniquely identifying your end-users, such as a username, user ID or an email address. Here the field joined_at is a date field, set as a numeric unix epoch timestamp (in seconds) giving the time the user signed-up to the application.

NOTE: You must set the user_id in the very first call to api.fields.set on a page. Subsequent calls may omit this field, but it is considered best practice to always include it.

Setting user group/role: you may want to user this method to customize the experience of users based on group participation or user roles. This information could then be used to set up activation rules, such that members of different groups will have different guides available. An example for such call could be:

iridize("api.fields.set", {
    user_id:"simpsons@springfield.us",
    joined_at:629848800,
    role:"admin"
});

Goal Tracking: setting up goal tracking is just a matter of setting a field with the field name prefix “goal_”. This information can then be used to track conversions and set up A/B tests for your guides. For example, if we want to track when a user upgrades her plan from a trial account, we could call:

iridize("api.fields.set", {
    user_id:"simpsons@springfield.us",
    joined_at:629848800,
    goal_upgraded_plan:"silver"
});

on the upgrade confirmation page, where the goal value string is in this cased used to track the type of plan the user converted to.

Field types

There are three basic javascript field types you can use, which are determined by the field value:

  • String
  • Integer
  • Boolean

For example, we could call:

iridize("api.fields.set", {
    user_id:"hpotter",
    joined_at:867618000,
    type:"mage",
    level:3,
    evil:false
});

Additionally, there are two types indicated by a prefix/suffix to the field name, goal fields (which are described above, under Goal Tracking), and time fields.

Time fields: to set a time field, simply name the field with an “_at” suffix. The time value should be provided using a unix epoch timestamp (in seconds). For example, to set the date a user joined the application, we could call:

iridize("api.fields.set", {
    user_id:"simpsons@springfield.us",
    joined_at:629848800,
});

Personalization and Dynamic Content

api.vars.set

Dynamically set page variables which can be used in guides content.

For example, you may want to address your end-users in your guides using their names. In such a case the call to api.vars.set could be:

iridize("api.vars.set", {"new user":"F. Bar"});

The variable can then be used in any guide that will be running on the page by enclosing the variable name (“new user”) within double curly brackets ( { {new user}}). When the guide is run and the step is displayed, the part enclosed within curly brackets will be replaced with the value of the page variable if it is set. If it is not set, the variable name will be used instead (without the curly brackets). For example, the text of a welcoming step could be set to:

Hi { {new user}}, thanks for signing up to fooBar. Let us show you around.

With the variable was set as described above, the text of this step will read “Welcome F. Bar, thanks for signing up to fooBar, let us show you around.”. If the variable was not set, the text will open with “Hi new user,…”

Another use case for this API call is for including dynamically generated hyperlinks in your guides text. For example, you may have in your application paths such as “/foo/username/bar/”. If you would like to add a hyperlink to such a path within a guide you could simply set the link target to “/foo/ { {username}}/bar/”, and run “api.vars.set” as follows:

iridize("api.vars.set", {"username":"007"});

This will yield a hyperlink with the target “/foo/007/bar/”.

NOTE: The variable must be set when the guide step is run. However, you may use the below documented “api.guide.onStartStep” event for setting this value immediately prior to the execution of a specific step in a specific guide. This makes it possible to dynamically set the content of a guide step based on the actions of the user in previous steps of the guide.

Single Page Applications (SPA) support

The iridize JS API allows customers with SPAs to easily treat route changes as if they were page url changes. This includes controlling and refreshing the contents of the iridize start panel based on the current route, set guide steps to wait for route change (similar to waiting for page refresh), automatically activating a guide when a specific route is loaded etc.

NOTE: You should only run the iridize embed code, including the call to api.fields.set, once, on the initial page load of the SPA. You should then update the route or refresh the guides on route or state changes. See next sub-sections for further details.

The iridize API provides both low-level and high-level method calls for setting up iridize for your SPA. The high-level methods provide the simplest way to integrate iridize, transparently differentiating between the first page load of the SPA and subsequent route changes. The low-level methods are available for SPAs that require more granular control or setting and updating routes, as well as refreshing the running guides.

Setup using high-level calls

The high-level setup of iridize for an SPA is comprised of two parts. First, we need to tell the iridize JS API to defer running the guides for after the the initial SPA route is loaded. Then, we need to update the iridize JS API whenever the SPA route is loaded, including the first SPA route load.

Waiting for the initial SPA route load

When using the high-level JS API calls to integrate iridize into an SPA you should add a call to api.route.wait to or immediately after the iridize embed code, such-

iridize("api.route.wait", {});

This call notifies the iridize JS API that it should defer loading the iridize guides for after the first SPA route is loaded and a call to api.route.update is made (see below).

Handling SPA route changes

Whenever an SPA route is loaded (including the initial SPA route load), you should make a call to api.route.update, passing the new route that is loaded as part of the parameter object, such-

iridize("api.route.update", {"route":"/foo/"});

Where “/foo/” is the SPA route that is loaded. That’s it. The api.route.update call knows to handle the initial route load differently than route changes transparently, and will issue a call to api.guide.refresh (see below) only when the SPA route is actually changed..

Setting user fields when integrating iridize into an SPA

The details of using the api.fields.set call are provided in the “Customization and Personalization Methods” section above. Please not that if you are not using the api.fields.set call in your iridize implementation you can skip this section. When integrating iridize with an SPA there are two general cases that need to be considered. The simplest case is when the user details are available when the iridize embed code is run. The slightly more involved case is when the user details (such as user_id, joined_at date, account_id etc.) are unavailable when the iridize embed code is run.

User details available when the iridize embed code is run

If the user details are available when the iridize embed code is run, the usage of api.fields.set is identical to that of non SPA setup, regardless of whether the embed code is embedded directly in to the page’s HTML or is only run when the SPA is loaded. In this case the call to api.fields.set should be made as part of or immediately after the iridize embed code, within the same synchronous code flow. An important detail to note is that api.fields.set should only be called once and you should not issue a call for every time the SPA route is changed.

User details only available after SPA is loaded

It is usual for SPAs that the user details are not available when the iridize embed code is run. This usually is the case when the iridize embed code is embedded as part of the page HTML, but the user details are only fetched at a later time, as the SPA loads. In such a case you should add the a call to api.fields.set with an empty fields object as the second parameter as part of or immediately after the iridize embed code (within the same synchronous code flow), such-

iridize("api.fields.set", {});

Then, once the user details are available you should run the api.fields.set call with the user details as usual. With this setup the iridize JS API will know to wait with the guides initiation for after the user details are provided with the second call to api.fields.set. Please note you should only call api.fields.set with the user details once, and not repeat it every time the SPA route is changed.
NOTE: When using the api.route.wait call, it is possible to setup the JS API calls in a way that makes calling api.fields.set with an empty fields object unnecessary. After calling api.route.wait, the iridize JS API would await an api.route.update call before loading and running any guides. If it is possible to ensure that the call to api.fields.set takes place before any call to api.route.update, then the initial call to api.fields.set with an empty fields object can be omitted.

Setup using low-level calls

Initial Page Load – api.route.set

When integrating iridize to a SPA, you should add a call to “api.route.set” to the initial iridize embed code. The call expects a single property, “route”, in the second argument. For example, if the initial route for your application is “/foo/” the call will be:

iridize("api.route.set", {"route":"/foo/"});

NOTE: if you use hash-based navigation in your SPA you may include the hash sign in the route or not as you prefer. Leading and trailing “/” are also optional.

Route Change or State Refresh – api.guide.refresh

Unlike regular web application, SPA do not have page loads as natural points for refreshing the state of your guides. With the use of the “api.guide.refresh” API call you can refresh the state on demand, optionally updating the current route. The best practice is to call “api.guide.refresh” after each route change.

For example, if the route was changed to “/foo/bar/” the call would be:

iridize("api.guide.refresh", {"route":"/foo/bar/"});

NOTE: it is best to issue the “api.guide.refresh” call immediately after the route changes, rather then immediately before. The important thing is that the originating route UI should already be removed from the DOM or hidden when the call is issued.

NOTE: in some applications a route change event is fired immediately after a page reload. In such cases please use force:false to allow for better performance by allowing iridize to test that the passed route is different than the current route set.

The Guide API Methods

API methods that have to do with guides are all namespaced as “api.guide.methodName”.

Control Methods:

api.guide.list

Get the list of all available guides for the current domain.

For example, to getch the guides list and print it to the browser console, you could do:

iridize("api.guide.list",  {}, function(data)  {
    var guidesList,guide,i;
    // get the array of guide information objects
    guidesList = data.guides;
    // print the guides to browser console
    for (i = 0; i < guidesList.length; i++)  {
        guide = guidesList[i];
        console.log(guide.apiName + " | " + guide.displayName);
    }
});

api.guide.start

Starts a specific guide. The method expects the api name of the guide as the “apiName” property of the second argument. For example, to start a guide with an apiName “foobar” the call would be:

iridize("api.guide.start",  {apiName : "foobar"});

This method also accepts an additional optional “force” property to the second argument. If this property is set to false, the API method will not force start the guide, as is its default behavior.

NOTE: The apiName of guides can be found and modified under that advanced tab of the Guide options page in the iridize dashboard.

NOTE: The force:false option must be set in order for end-user activation rules to apply for guides started using the API.

api.guide.stop

Stops a specific guide if an apiName is supplied, or all currently running guides if not .

To stop a specific guide if it is running, pass the api name of the guide as the apiName property of the second argument. For example, to stop a guide with an apiName “foobar” the call would be:

iridize("api.guide.stop",  {apiName : "foobar"});

To stop all currently running guides, simply don’t pass an apiName property, so the call would be:

iridize("api.guide.stop", {});

NOTE: The apiName of guides can be found and modified under that advanced tab of the Guide options page in the iridize dashboard.

Events:

api.guide.onStartGuide

The startGuide event is triggered every time the a guide is started. The callback is passed two properties – the apiName of the guide for which the event was triggered and a parameter indicating the type of guide activation. The main types of activation values of the runType variable are “autoload”,”startPanel” and ”apiStart”.

For example, the following call would log every guide started to the browser console:

 

iridize("api.guide.onStartGuide",  {}, function(data)  {
    var apiName = data.apiName;
    var runType = data.runType;
    // print the guide’s api name and the activation type
    console.log(apiName + " | "+ runType);
});

 

api.guide.onStartStep

The startStep event is triggered every time the end user progresses along any guide. The callback is passed two properties – the apiName of the guide for which the event was triggered and the id of the step which the user have reached (this id is usually the step number in the guide).

For example, the following call would log every step started to the browser console:

iridize("api.guide.onStartStep",  {}, function(data)  {
    var apiName = data.apiName;
    var step = data.step;
    // print the guide’s api name and the id of the step reached
     console.log(apiName + " | "+ step);
});

api.guide.onStopGuide

The stopGuide event is triggered every time a guide is stopped, either by the user reaching the guide’s end, or due to the user clicking the close button (x) on the tip. The callback is passed the apiName of the guide which was stopped.

NOTE: data.userClosed will be true if the user has manually closed the guide. If ‘remind me later’ was clicked it will be false.

For example, the following call would log every guide when it is stopped:

iridize("api.guide.onStopGuide",  {}, function(data)  {
        var apiName = data.apiName;
    // print the api name of the guide that was stopped

      console.log(apiName);
    });