Building up visitor profiles

Overview

Every known and anonymous visitor to a web page tagged using RPI Realtime’s JavaScript web client, and a call made directly to an RPI Realtime API method, results in the building up of a unique profile per discrete individual.

Visitor profiles are stored in an in-memory realtime cache. This means that latency is minimized when making decisions based on the information in the visitor profile.

A visitor’s profile can also be built up through the execution of realtime cache offers, and through database lookups using cached attribute lists.

Populating the Visitor Profile

Visitor data in the form of name/value pairs can be added to the visitor profile through a variety of methods:

Querystring parameters: if a visitor navigates to a web page tagged by RPI Realtime using a URL to which querystring parameters have been appended, the parameters’ name/value pairs will be added to the realtime cache.
For example, navigating to ‘http://mylandingpage.com?CustomerKey=12345’ will result in the addition of value ‘12345’ for attribute ‘CustomerKey’ to the visitor profile.
Web form submission: on submission of an RPI web form, the data entered by a visitor within the form will be added to his or her visitor profile if the RPI Realtime web.config setting CacheWebFormData is set to True.
A call to the RPI Realtime API. For more information, please see the API’s Swagger documentation.
The Realtime JavaScript web client provides methods for pushing data in the visitor profiles. In addition, the web client allows for the configuration of “Realtime Lenses” which are mechanisms for capturing and storing Realtime parameters based on the various sources from a web page. Full details on Realtime lenses can be found in the web client documentation in Deployment Files in the following directory: DeploymentFiles\InteractionRealtimeAPI\RPIFormValidation\shared\js\rpiwebclient\documentation\index.html. The following is a summary of the available Realtime lenses:
- Storage Lens: allows the use of web site cookies and local storage values to be collected and stored as parameters in the Realtime profile.
- JavaScript Lens: allows the use of site JavaScript variables or objects values to be collected and stored as parameters in the Realtime profile.
- Search Lens: allows URL query string parameters to be collected and stored as parameters in the Realtime profile. This extends the capture of Querystring parameters described in the first bullet point by providing the ability to rename the parameters as desired.
- Path Lens: allows parts of a web page URL path to be collected and stored as parameters in the Realtime profile.
- Form Lens: allows form field values to be collected and stored as parameters in the Realtime profile. Extends the form submission functionality described above by providing the ability to be more selective about which fields are stored as well as providing the ability to rename the parameters as desired.
- DOM Lens: allows elements of the DOM to be collected and stored as parameters in the Realtime profile.

Data from the data warehouse can also be added to the visitor profile through the following mechanisms:

Data can be retrieved from the data warehouse and stored in the visitor profile at a visitor’s identifying him- or herself to RPI, through the use of a cached attribute list. A cached attribute list is a list of RPI attributes, managed within a dedicated configuration interface in RPI. Identification of a visitor can occur:
- At submission of a web form, when the web form is associated with a cached attribute list.
- On receipt of a name/value pair (e.g. through a querystring parameter) when the name maps to an entry within the RPI Realtime ParameterToDataMappings web.config setting (see Appendix A for details of RPI Realtime web.config settings).
- Via a call to the RPI Realtime API. For more information, please see the API’s Swagger documentation.
Cached attribute lists can also be used to store ‘virtual lookup tables’ in the realtime cache. Calls to the data warehouse to retrieve visitor data can be avoided through the usage of this mechanism.
Visitor profile data can be populated in advance of site visits through the execution of a realtime cache offer. This offer type is executed in the Interaction Designer workflow, within which an audience is used to define the list of potential site visitors for whom profile data is to be loaded. A realtime cache offer is subsequently executed against the audience. Data, the structure of which is defined by the realtime cache offer, is retrieved from the data warehouse and stored in visitors’ profiles in the realtime cache. This data is then available when making decisions about content to be rendered to site visitors.
Visitor profile data can also be populated in batches via the RPI Realtime API. For more information, please see the API’s Swagger documentation.

Visitor ID Management

Each unique unknown visitor of which RPI Realtime becomes aware is by default assigned a GUID identifier, which is used to key their visitor profile. The visitor ID is stored in a cookie to ensure its maintenance across sessions.

When a visitor makes her- or himself know to RPI (via one of the mechanisms listed above), the GUID is replaced with one of a configurable set of IDs. These are defined using the following RPI Realtime appsettings.json configuration settings:

MasterKeyName: this setting facilitates the definition of the name of the principal key to be used to identify known visitors’ profiles.
For example, when ‘CustomerKey’ is defined as the master key, navigating to ‘http://mylandingpage.com?CustomerKey=12345’ will result in the visitor’s profile being keyed on CustomerKey, with value ‘12345’.
MasterKeyAliases: this setting facilitates the definition of an array of alternative names for the master key. For example, a ‘CustomerKey’ master key might be referenced as ‘CK’ in a querystring (e.g. ‘http://mylandingpage.com?CK=12345’.
AlternativeKeys: this setting provides the ability to specify alternative keys that can be used to identify a visitor. The link between the master key and alternative keys can be established by:
- A querystring’s containing both sets of name/value pairs.
- Populating the realtime cache using either a cached attribute list or realtime cache offer containing both the master and additional keys.

If a previously-unknown visitor already has a visitor profile, and is identified using one of the keys listed above, the existing profile is updated with the new visitor ID. In addition, if contents of the unknown visitor profile are merged with any existing known visitor profile, to create a single, unified visitor profile per visitor.

When two profiles are merged, details of the same stored in visitor profile to which merged; e.g.:

CODE

"Merge":[{"fid":"c371b2e2-fb6b-4788-b274-376ae57dca80","tid":"11000","dir":"MergeFrom","mst":"True","mDate":"2021-03-30T08:35:30.7518212+01:00"}].

In addition, if appsettings property EnableProfileMergeEvents is set to true, a ProfileMerge event is raised. If TrackProfileMergeInSourceProfile is set to true, the profile from which merged is updated with the merge details.

A HashVisitorID appsettings property can be used to obfuscate visitor IDs as returned in calls from the RPI Realtime API.

Devices

The devices used by a visitor to access RPI Realtime are stored as an array in the visitor profile. The following are stored for each device:

Device ID
User agent string
First seen (UTC)
Last seen (UTC)

The maximum number of devices that can be persisted is defined by application setting MaxNoVisitorDevicesAllowed, which defaults to 6. If this value is exceeded, the new device replaces the oldest (based on the Last seen date/time).

Sessions

A visitor’s session can be recorded by RPI, with support afforded for the manual provision of a session ID, or a GUID session ID automatically generated by RPI.

Two RPI Realtime application configuration settings are used to manage visitor sessions:

ManageSessionID: this Boolean setting controls whether a GUID session ID is assigned automatically by RPI at a call to RPI Realtime, or can be assigned manually when making a call to one of the following Realtime API endpoints:
- Smart Asset: api/v2/smart-assets/results
- Events: api/v2/events
- Cache: api/v2/cache/visit
TimeoutSeconds: this setting is used when ManageSessionID is set to True. It allows for specification of the number of seconds within which a visitor will be assigned the same session ID when making a call to RPI Realtime. If a call is made again within the specified number of seconds, the same session ID is used and the time period is reset.

A single session ID can be persisted in a visitor's realtime profile. In addition, SessionID can be persisted by the Web cache data importer in the RPI_Web* data warehouse tables, and written to files (details of both contexts are provided elsewhere in this documentation).