Client ID Management

The CX Tag provides an easy way to implement your Client ID persistence strategy. You can use this capability to reuse user identifiers from your internal systems to be passed as Client IDs to the tag and append them to the behavior events captured from user interactions with your web applications. The Client ID can be persisted in the cookies for the time allowed by the browsers. This way, you can easily track returning behavior of visitor(s) to your web apps and analyze their behavior.

The Client ID persistence capability can be leveraged by any of the modules in the CX Tag and can be used in analyzing the cross-product user journey for a user.

See the Oracle Infinity User Help Center - Client ID Management to learn more about Client ID Management.

Important: To request access to this feature, please contact My Oracle Support.

In this topic:

Technical Reference

ORA.getClientID(callbackFn)

This method is used for the following capabilities:

  1. Retrieving an existing Client ID from a visitor's session

  2. Creating a new Client ID when the website implementation engineer uses the OOB Client ID management capability

This method is used to retrieve the Client ID that is available in the browser session. Once the Client ID is available the callbackFn function is called with the Client ID string as an argument. If the Client ID is already available in the persistent storage then it returns the Client ID from it. If the Client ID is not available in the persistent storage, then it generates a new Client ID, stores it in the persistent storage, and callbackFn is called with the new Client ID.

Customer managed Client ID capability is enabled

In this case, a flag if WaitforSetClientID is enabled when creating the CX Tag. When the ORA.getClientID method is called before setting a Client ID, the method doesn't return the Client ID available in the persistent storage. Instead, it waits for the ORA.setClientID to be called at least once. Once the ORA.setClientID is called by any module, then the callbackFn method is called with the value provided in ORA.setClientID. For all subsequent calls to the ORA.getClientID, it provides the Client ID from the persistent storage.

Arguments

callbackFn {function}

Callback function must be called once the client ID is available. This function accepts a single argument client ID string.

Returns

None

Example

ORA.getClientID(function(clientID){

console.log('The client ID is: ' + clientID);

}

);

ORA.setClientID(clientID)

This method is used for the following capabilities:

  • Setting a new Client ID in case of customer managed Client ID capability

  • Modifying the Client ID in case of customer managed Client ID capability

This method helps website implementation engineers to set their own Client ID and store it in the persistent storage. If a Client ID is already available in the persistent storage, this method replaces the old Client ID with new Client ID value.

Customer managed Client ID capability is enabled

When a page is loaded, a PageView event is triggered. The event is decorated with the Client ID and transmitted to the server. When the customer managed Client ID capability is enabled, the Tag waits until the response for the ORA.setClientID method is received.

The customer managed Client ID capability by a flag called WaitforSetClientID. This flag is set to false by default.

Arguments

clientID {string/function}

ORA.setClientID accepts either a string or a function as an argument.

If the website implementation engineer passes a Client ID as a string, it is stored in the persistent storage as a Client ID.

If the website implementation engineer passes chooses to pass a function as an argument instead of a string, the function is executed by setClientID method. The function passed by website implementation engineer returns a string value which is stored in the persistent storage as a Client ID.

In both the cases, the Client ID string should meet the following criteria:

  • Should not be empty

  • Should not contain white spaces

  • Should not contain special characters (;, ^, =)

  • Max length is 100 characters.

Returns

Boolean value true if Client ID is set & stored successfully, false otherwise.

If the setClientID method fails to set a Client ID, a console error is displayed as follows:

setClientID failure - either no client ID passed or client ID has illegal character

Example

A persistent client identifier can be enabled by the following process.

  • Wait for the Core Module (common.js) of the CX Tag to load

    • This is because the ORA namespace is only available in the Core Module

    • Check whether the ORA namespace is available using window.ORA object

  • After the Core Module is loaded, call the setClientID method as follows

  • Use the ORA.productReady.push() method to validate tag has loaded prior to calling the setClientID method

  • After the Client ID is set, the core module triggers a notification

  • Any module that subscribed to notifications from the Core Module will be able to listen to this notification

setClientID method call
if (!window.ORA) {
				window.ORA = {
				productReady: []
				}
				}
				ORA.productReady.push(["common", function() {
				ORA.setClientID("xxxx-xxxx");
 
			}]);

Any module will be able to access the client ID using the getClientID method.

After the Core module (common.js) is loaded, the website implementation engineers must call the setClientID method to set the client ID.

SetClientID method for Infinity module

The setClientID method must be called using analytics instead of common as an argument if you are using the Infinity module. This will check whether the Infinity module has been loaded or not prior to setting client ID.

The Infinity module requires additional cookie parameters to be set. In this case, the setClientID method must be called after the Core module and Infinity modules are loaded. The setClientID method must be called as shown here.

setClientID method
if (!window.ORA) {
				window.ORA = {
				productReady: []
				}
				}
				ORA.productReady.push(["analytics", function() {
				ORA.setClientID("xxxx-xxxx");
 
				}]);

ORA.clearClientID()

This method clears the Client ID if it has already been set. This method also clears the Client ID from the persistent storage.

Arguments

None.

Returns

None.

Example

ORA.clearClientID();

Sample Implementation

Client ID sample implementation
					<!DOCTYPE html>
					<html>
					<head>
					<title>Who is Raiders?</title>
					<style>
					body {background-color: powderblue;}
					h1 {color: blue;}
					p {color: red;}
					</style>
					<script src="//c.dev.infinitycloud.io/acs/account/i4er4dpqjy/js/sampleimplementation/odc.js"></script>
					<script async>
					if (!window.ORA) {
					window.ORA = {
					productReady: []
					}
					}
					ORA.productReady.push(['analytics', function() {
					console.log("RAIDERS ANALYTICS READY");
					ORA.setClientID("raidersmach01");
					}]);
					</script>
					</head>
					<body>
 
					<h1>Test Page</h1>
					<p>This Test Page Demonstrates a Sample Implementation of Client ID capability</p>
					</body>
				</html>

Learn more

Oracle Infinity User Help Center - Client ID Management- End user-focused guide on Client ID Management.

Oracle CX Tag - Learn about to enable various CX products on your websites using the Oracle CX Tag.