Setup Iridize in a Single Page Application (SPA)

Before we dive into the steps required to embed Iridize in an SPA, let's explain why a specific setup for SPA's is needed in the first place.

The thing that's different in an SPA is the fact that even though the browser does not perform any standard navigation the view is still changing. As a result the application codebase needs to update Iridize that the view has changed so that Iridize could refresh all of the content.

 

1. basic embed code

To Setup Iridize just as in any other web application by placing the Iridize embed code in the relevant pages. Your specific embed code can be found in your account setup page and should simply be copied before the closing </body> tag.

The code will look something like this:

/* Iridize.com*/window.iridize=window.iridize||function(e,t,n){return iridize.api.call(e,t,n);};iridize.api=iridize.api||{q:[],call:function(e,t,n){iridize.api.q.push({method:e,data:t,callback:n});}};
iridize.appId="XXXXXXXXXXXXXXXXXXX";
iridize.env="prod";
iridize("api.fields.set",{user_id:"USER_ID_GOES_HERE"}); 
(function(){var e=document.createElement("script");var t=document.getElementsByTagName("script")[0];e.src=("https:"==document.location.protocol?"https:":"http:")+"//d2p93rcsj9dwm5.cloudfront.net/player/latest/static/js/iridizeLoader.min.js";e.type="text/javascript";e.async=true;t.parentNode.insertBefore(e,t)})(); 

For a detailed explanation of all configuration options please see this article.

2. notify iridize that this is an SPA

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.

 

3. User Identification (part 1)

Iridize needs to know which use is currently logged in so that it could provide that user with relevant content.

If you do not know who the logged in user when the code of the basic embed code (step #1) is executed. you can notify Iridize that you will be providing this information later.

To do so, you should call the 'api.fields.set' function with an empty object.

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

NOTE: User conditions will be disabled if you do not make this notification.

Your embed code should now look like this:

/* Iridize.com*/window.iridize=window.iridize||function(e,t,n){return iridize.api.call(e,t,n);};iridize.api=iridize.api||{q:[],call:function(e,t,n){iridize.api.q.push({method:e,data:t,callback:n});}};
iridize.appId="XXXXXXXXXXXXXXXXXXX";
iridize.env="prod";
iridize("api.route.wait", {});
iridize("api.fields.set",{})
--- OR ---
iridize("api.fields.set",{user_id:"USER_ID_GOES_HERE"}); 
(function(){var e=document.createElement("script");var t=document.getElementsByTagName("script")[0];e.src=("https:"==document.location.protocol?"https:":"http:")+"//d2p93rcsj9dwm5.cloudfront.net/player/latest/static/js/iridizeLoader.min.js";e.type="text/javascript";e.async=true;t.parentNode.insertBefore(e,t)})(); 

 

4. User Identification (part 2)

If you have already provide user identification in the basic embed code you can skip this step.

If you used iridize("api.fields.set",{}) in the previous step, you will need to update Iridize of the logged in users as soon as possible. To do so call:

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

NOTE: you can provide Iridize other user data (e.g. user_role, location, etc.) by adding more items to the passed javascript dictionary.

5. Update route

Whenever an SPA route is loaded (including the initial SPA route load) you need to notify Iridize of it by calling:

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

Where "/foo/" is the SPA route that is loaded. The api.route.update call knows to handle the initial route load differently than route changes transparently. It will also automatically refresh the content based on the new route. 

The call to "api.route.update" must be made after the route has successfully changed and not before. This way Iridize will be able to update the content according to the newly loaded route.

When using the AngularJS's $route for view routing you can bind on the $routeChangeSuccess event. When using ui-router you can bind on the analogous $stateChangeSuccess event. Both events provide the new route/state which can be passed to the api.route.update call.

BEST PRACTICE: It is recommended to omit random ID's from the route. For example, if you run a CRM and each contact has a unique (e.g. https://myapp.com/dashboard#contact/169627 ) where 169627 is the ID of the contact in your database. Instead of setting the route to '/contact/169627' it is recommended to make the route more generic. For example:

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

IMPORTANT: The people who will be writing the content using the Iridize platform need to know what scheme was used to map the urls to routes in Iridize. This is needed when creating guide activation conditions.

 

For more information please refer to our Javascript API article. The article also includes a special section for SPA's.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.