Enabling OGL by Embedding JavaScript

JavaScript method

To embed OGL using the JavaScript method, you will need access to the application codebase and the ability and permissions to modify it. If you do not have access to the code or your do not have the necessary permissions to change it, you may need to consult with an application administrator for your host application.

Examples of such applications include, but are not limited to; custom built VBCS applications, your bespoke company tools, etc.

Note:

If you do not have access to the application code base, please read more about all available embed methods in this User Guide article Embedding Oracle Guided Learning

The JavaScript method is preferred if the web application is not already integrated with OGL because like the integrated method, it does NOT require any changes to the end user’s machine.

From an OGL perspective, web applications are divided into two families: regular applications and single-page applications (SPAs). Depending on the type of your application, the way to embed OGL will differ. With regular applications, navigation from one page to another involves a full-page refresh.

A SPA (Single Page Application) is a type of web application or website that interacts with the user by dynamically rewriting a single web page, rather than loading entire new pages from the server. This approach aims to provide a more fluid and seamless user experience, as content updates without requiring full-page refresh. In an SPA, since the page is only loaded once, the OGL JavaScript is loaded only once as well. As a result, the application codebase needs to update OGL that the view (aka ‘route’) has changed so that OGL can refresh all the content and update it based on the new route.

Embed OGL in a Regular Application

Creating and Publishing a Sandbox for OGL Configuration

  1. Copy the embed code from the OGL console.
    Your embed code will look something like this:
    
<script type='text/javascript'>
        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="XXXXXXXXXXuGbk5T3yqnxQ";
        
        /*FOR YOUR DEV OR STAGING ENVIRONMENTS PLEASE UNCOMMENT THE NEXT LINE*/
        //iridize.env="dev";
        /*TO ENABLE USER CONDITIONS UNCOMMENT THE NEXT LINE.
        Add as many fields as you would like (e.g. user_role, user_name, etc.) */
        //iridize("api.fields.set", {user_id:"LOGGED_IN_USER_ID_GOES_HERE"});
        var e=document.createElement("script");
        var t=document.body;e.src="https://guidedlearning-uat.oracle.com/player/latest/static/js/iridizeLoader.min.js";
        e.type="text/javascript";e.async=true;t.appendChild(e);

</script>
  2. Paste the embed code into all pages in your application where OGL should be enabled.

    In most applications, you do not need to literally paste the embed code on each page. Generally, there is a global page template that can be used for this. It is recommended to paste the code immediately before the closing </body> tag. This means that OGL will start loading after most of your page has already been loaded.

  3. Configure the deployment mode.
    Your embed code includes a line that is commented out that looks like this:

    OGL supports 2 deployment modes.

    In your testing environment, you must uncomment this line. In your production environment, this line must be commented or changed to:
    OGL allows you to tailor the content based on user parameters (e.g. role, geography, division etc.). To enable this functionality you need to notify OGL who the user is by calling the api.fields.set API:

    The line above notifies OGL that the current logged in user is John Doe and that they are an employee. You can provide any combination of fields of all standard types: string, int, boolean, date. for date fields please add the at suffix (e.g. joined_at).

Embedding OGL in a Single Page Application

  1. Copy the embed code from the OGL console.
    Your embed code will look something like this:
    
<script type='text/javascript'>
        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="XXXXXXXXXXXuGbk5T3yqnxQ";
        
        /*FOR YOUR DEV OR STAGING ENVIRONMENTS PLEASE UNCOMMENT THE NEXT LINE*/
        //iridize.env="dev";
        /*TO ENABLE USER CONDITIONS UNCOMMENT THE NEXT LINE.
        Add as many fields as you would like (e.g. user_role, user_name, etc.) */
        //iridize("api.fields.set", {user_id:"LOGGED_IN_USER_ID_GOES_HERE"});
        var e=document.createElement("script");
        var t=document.body;e.src="https://guidedlearning-uat.oracle.com/player/latest/static/js/iridizeLoader.min.js";
        e.type="text/javascript";e.async=true;t.appendChild(e);

</script>
  2. Paste the embed code into all pages in your application where OGL should be enabled.

    In most applications, you do not need to literally paste the embed code on each page. Generally, there is a global page template that can be used for this. It is recommended to paste the code immediately before the closing </body> tag. This means that OGL will start loading after most of your page has already been loaded.

  3. Configure the deployment mode.
    Your embed code includes a line that is commented out that looks like this:

    OGL supports 2 deployment modes.

    In your testing environment, you must uncomment this line. In your production environment, this line must be commented or changed to:
  4. Notify OGL that this is a single page application:

    This notifies OGL that this application is an SPA. As a result, OGL will defer loading all the content until the first SPA route is loaded (see api.route.update below).

  5. Notify OGL to wait for user fields:

    Normally in a SPA, the embed code above will be called before the user is logged in. This call notifies OGL that you will be providing it with user information later in the code execution. If you do not intend to provide OGL with user information this call can be omitted.

  6. At this stage your embed code should look like this:
    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="XXXXXXXXXXXuHNQyX4zyR2g";
/*FOR YOUR DEV OR STAGING ENVIRONMENTS PLEASE UNCOMMENT THE NEXT LINE*/
//iridize.env="dev";
iridize("api.route.wait", {});
iridize("api.fields.set",{});
var e=document.createElement("script"); var t=document.body;e.src="https://guidedlearning.oracle.com/player/latest/static/js/iridizeLoader.min.js"; e.type="text/javascript";e.async=true;t.appendChild(e);
  7. User identification: To compliment step #5 above, in the loading sequence, when the user is logged in, you will need to provide OGL with all relevant user fields just as in step #4 of the regular application setup.
  8. Route update: This is the most important difference. This is where you let OGL know that the logical page (a.k.a route) has changed and that it should load all content related to the new route:

    Where "/foo/" is the SPA route that is loaded. The api.route.update call should be used for both initial route load and other route changes. It will automatically refresh the OGL 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 OGL will be able to update the content according to the newly loaded route.

    Javascript frameworks normally provide an event for successful route change. this is the prefect place to place this 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 id (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:

Note:

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

separator