RPI web client initialization

Overview

This topic provides information about initializing the rpiWebClient. The rpiWebClient is a client-to-server Realtime deployment, which means that the scripts mentioned below and the Real-time API need to be publicly accessible, because the code is executed by the client browser. You should consider deploying the scripts on a content delivery network (CDN) to ensure that the call to the scripts will return quickly, regardless of where the browser is.

Before loading and initializing the client as documented in this topic, make sure to review the following configuration and rpiWebClient JavaScript files:

Loading the client library and the configuration

In order to use the rpiWebClient, you need to load the client and configuration scripts.

The scripts for loading the rpiWebClient and configuration script should be at the top of the page or load as early as possible to ensure they are available when the rpiWebClient is initialized.
Typically these libraries are kept as separate scripts to minimize the updates when new versions of the rpiWebClient are published. The idea is that when a new web client is available only that needs to be published and not the configuration, as that will most likely stay the same most of the time unless additional configuration features are added and being deployed.
Although the client can be configured as a part of initialization, we recommend using a configuration file to ensure consistency of deployment across application and pages.
You need to ensure that the configuration file loads before the rpiWebClient is initialized, otherwise you will not get the expected results.
If you notice that you are seeing a new Visitor ID every time, that is a good indication that the rpiWebClient is initializing before the configuration file was loaded or that there are items missing within the configuration file.

Reference in HTML for configuration and client library

The {hosted_location} below should be replaced with the public location of where the JavaScript files are located, which is best to be deployed on a CDN.

An example of a local reference for this would be as follows: https://local.rphelios.net/InteractionRealtimeAPI/rpiwebclient

Details related to the strategy for naming and storing the configuration and rpiWebClient files can be found in the “RPI Web Client” page noted above.

HTML JavaScript references

JS

<!-- RedPoint Realtime JavaScript References   -->
<script type="text/javascript" src={hosted_location}/rpiWebClient.config.js></script>
<script type="text/javascript" src={hosted_location}/rpiWebClient-latest.js></script>

Tag manager deployment

The deployment of the scripts and the initialization of the rpiWebClient can be done by a tag manager. If this is the approach that is being used, you need to ensure that the configuration and the rpiWebClient are loaded before the initialization of the client. In some cases, with tag managers this may be difficult to control. So, it may make sense to combine the configuration file and the rpiWebClient to ensure they are both loaded before the client is initialized.

RPI web client initialization details

With the scripts listed above in the webpage, you are able to initialize the rpiWebClient.

Initialize web client with default configuration

To use the default settings defined in the configuration file, you can just initialize the Web Client without any additional information.

The initialization of the rpiWebClient should be as close to the bottom of the page as possible to ensure all the other components of the page have loaded. If it is done too early, then things like link clicks may not get tracked if the links load after the rpiWebClient was initialized.

Example in HTML

JS

<script type="text/javascript">
//Initialize WebClient 
rpiWebClient.init();
</script>

Push parameter and initialize web client

This allows you to push parameters to the visitor profile when the Web Client is initialized. This may be used to store data in the visitor profile based on known information about the visitor when the page loads. This may be a user id or persona or anything else known about the visitor you want to capture in the visitor profile. Generally, this is used to capture data from the page or about the visitor to execute a Realtime Decision based on the information.

Example in HTML

JS

<script type="text/javascript">
//Push Realtime Paramater "userId" and "persona"
rpiWebClient.pushRealtimeParameter("userId", "987654321");
rpiWebClient.pushRealtimeParameter("persona", "info_Seeker");
//Initialize WebClient
rpiWebClient.init();
</script>

Initialize web client and execute a Realtime decision

This allows you to execute a Realtime decision (Realtime Context) as a part of the Web Client initialization. In this case, the context is "home-page". The expectation is that the Realtime decision will either replace an HTML element on the page or return data to the page that can be used to inform other software on the page. Adding the context to this call allows for more concise usage of Realtime decisions, as opposed to initializing the client and then calling the Realtime decision.

Below is the reference of the default "SearchOperator" mode, which is set in the configuration file, and is also the same if the property is set as undefined. Unless defined otherwise, it will execute all smart assets that match the Contexts Path or Sub Context of the Path.

The Context SearchOperator(ContextSearchMode) controls how the ContextPath will be used to identify the smart assets to be evaluated.
IncludeSubcontexts(0) : Evaluate all smart assets that match the ContextPath or any sub context of the path provided.

Example in HTML

JS

<script type="text/javascript">
//Initialize WebClient and execute any Realtime Decisions with a context of "home-page"
rpiWebClient.init( { contexts: ["home-page"] });
</script>

Pushing parameters before initialization to support decisions and Master/Alternate Keys

Here is an example of the same call but combined with pushing the parameters in the previous step. This is a common use as you are loading data to the visitor profile to support the Realtime Decisions and ideally make the decision more personalized.

This example also illustrates how you could pass a Master or Alternate Key, so that the visitor profile would be aligned with the Master key defined in the Realtime configuration. In this example below, if the Master Key was defined as "userId", passing this parameter upon initialization causes the rpiWebClient to automatically override the default visitor id with the Master Key.

The visitorProfileMergeMode setting in the configuration file will determine how a Profile Merge will be handled if a Visitor goes from anonymous to known (Master Key).

More details related to Master/Alternate Keys are defined here: Realtime - Visitor Profiles & IDs

Example in HTML

JS

<script type="text/javascript">
//Push Realtime Paramater "userId" and "persona"
rpiWebClient.pushRealtimeParameter("userId", "987654321");
rpiWebClient.pushRealtimeParameter("persona", "info_Seeker");
//Initialize WebClient and execute any Realtime Decisions with a context of "home-page"
rpiWebClient.init( { contexts: ["home-page"] });
</script>