This documentation explains how to integrate your webpages/portal with Pixel Customer Experience Script (CX Script)
The CX Script is a javascript that runs in client's browser. CX Script gathers timings and metrics for any page on which it is placed. It also serves to correlate the user between sites on which it is placed. It also allows HTML pages to pass CustomData. The metrics collected by the script along with Custom Fields sent by the page are sent to Pixel as Client Side Events (CSE) or simply Events
NOTE : To allow correlation of various ID's in use throughout UHG, the CX Script must be called from the pixel repo servers using above URLs. | Environment | URL | Description |
|---|---|---|
| Stage | https://stage-repo.rakanto.com/rakanto/cx/cx.js | Point to this URL for your lower environment |
| Prod | https://repo.rakanto.com/rakanto/cx/cx.js | Point to this URL for your production deployment |
Make remote calls to the Pixel Repo URLs. Do not download the script and place in your source control.
Make CX Script the first thing in your HTML. This helps CX Script to collect accurate metrics on the page.
<html>
<head>
<script type="text/javascript">
(function (cx, darids, a, m) {
i = window; s = document, o = 'script', r = 'Rakanto',
i['RakantoObject'] = r; i[r] = i[r] || function () {
(i[r].q = i[r].q || []).push([1 * Date.now()].concat(Array.prototype.slice.call(arguments)))
}, i[r].l = 1 * new Date(); a = s.createElement(o),
m = s.getElementsByTagName(o)[0]; a.id = 'rakanto'; a.src = cx;if (darids){a.setAttribute('data-px-darids', darids)}; a.async = 1; m.parentNode.insertBefore(a, m)
})('https://stage-repo.rakanto.com/rakanto/cx/cx.js', 'UHG.Optum.Pixel.CXScriptExample');
</script>
</head>
<body>
<h1>Pixel Customer Experience Script - A simple example</h1>
</body>
</html>
Just copy the above code in a HTML file and open it in a browser. That's it!!!
UHG.Optum.Pixel.CXScriptExample in the example is Digital Analytics Reporting IDs (DARIDs). Details about DARID can be found in later sections.
Data collected by the CX Script in lower environment can be viewed and analyzed in the Pixel Self Service kibana.
Click on CSE Self Service to View the Kibana Desktop
(Login with your MSID and Password)
Filter in kibana on YOUR-DARID. Details about DARID can be found in later sections.
Note : Please reach out to Pixel team if you need help accessing/using the above kibanaUBRID is a GUID embedded in CX Script source code, this allows it to act as a "Super Cookie"
Browser gets the CX Script from the Pixel Repo Server that runs on the Rakanto domain UBRID is also set in a cookie in the browser by Rakanto Server. Expiration for that cookie is two years
The expiration of the script itself is set at 30 minutes. So every 30 minutes, the browser will check whether the script has changed. This comes in handy when we release new version of script. Browser will not have stale version for more than 30 minutes
When the browser checks for update, if the script has changed, a new script will be downloaded by the browser. The repo server will check for the cookie and if it is present, it will get the UBRID from the cookie and set it in the Script. If the cookie is not present or if the UBRID is not present in the cookie, a new UBRID will be generated.
The Repo server will set the UBRID in the CX Script itself. So the script has it until browser tries to download the new version of the script
The CX Script stores the UBRID in a global variable window.Rakanto.ClientSideData.ubrid
The CX Script creates another cookie in the website's domain and it places the UBRID along with other information in that cookie. This cookie is used for our Server Side Processing of the events. This code is also known as Scriptlet
The Digital Analytics Reporting Id, is a tag which identifies a business unit within UHG. These IDs are used to identify and group your events in Pixel System.
Note : DARIDS need to be AllowListed! Work with Pixel Team to get the DARID(s) you should tag your pages withExample 1: login page in MnR Member Medicare solution implementation would tag the page with the following DARID UHG.UHC.MnR.MedicareSolutions.Member.LoginPage
Note: Pixel will be generating more DARIDs based on the DARID provided. For example, the above DARID UHG.UHC.MnR.MedicareSolutions.Member.LoginPage will be parsed into
UHG.UHC
UHG.UHC.MnR
UHG.UHC.MnR.MedicareSolutions
UHG.UHC.MnR.MedicareSolutions.Member
UHG.UHC.MnR.MedicareSolutions.Member.LoginPageExample 2: login page shared by Mnr Medicare Solutions Member page and Acquisition page may pass two DARIDs UHG.UHC.MnR.MedicareSolutions.Member.LoginPage and UHG.UHC.MnR.MedicareSolutions.Acquisition.LoginPage
Note : Pixel will be generating the following DARIDs from the DARIDs provided above
UHG.UHC
UHG.UHC.MnR
UHG.UHC.MnR.MedicareSolutions
UHG.UHC.MnR.MedicareSolutions.Member
UHG.UHC.MnR.MedicareSolutions.Member.LoginPage
UHG.UHC.MnR.MedicareSolutions.Acquisition
UHG.UHC.MnR.MedicareSolutions.Acquisition.LoginPageIn stage environment, the CX Script will automatically send in a special DARID UHG.Optum.Pixel.SelfService along with the DARIDs set in the page.
This DARID (UHG.Optum.Pixel.SelfService) is allowlisted in Pixel Environment allowing events to flow through the Pixel Pipeline in the stage environment without needing any additional setup.
Clients will need to work with Pixel team to make sure their primary DARID is Allowlisted in Pixel Production environment.
Darids may be declared in different places, depending on their expected lifetime, when the CX Script reports something, the darid set used, is chosen in the following precidence, highest to lowest.
As a direct input into an api call.
From attributes of the script tag The code to include the script on your page. This is the easiest way call the CX Script.
From a session object Store the DARIDs in sessionStorage. CX Script will use the DARIDs defined in Session Storage
<html>
<head>
<script type="text/javascript">
sessionStorage.setItem('darids','UHG.Optum.Pixel.CXScriptExample.DaridInSessionStorage');
(function (cx, darids, a, m) {
i = window; s = document, o = 'script', r = 'Rakanto',
i['RakantoObject'] = r; i[r] = i[r] || function () {
(i[r].q = i[r].q || []).push([1 * Date.now()].concat(Array.prototype.slice.call(arguments)))
}, i[r].l = 1 * new Date(); a = s.createElement(o),
m = s.getElementsByTagName(o)[0]; a.id = 'rakanto'; a.src = cx;if (darids){a.setAttribute('data-px-darids', darids)}; a.async = 1; m.parentNode.insertBefore(a, m)
})('https://stage-repo.rakanto.com/rakanto/cx/cx.js');
</script>
</head>
<body>
<h1>Pixel Customer Experience Script</h1>
<h2>Darids from session object</h2>
</body>
</html>
From the page data layer.
Pass one or more DARIDs using the data layer (window.optumPageDataLayer). The window.optumPageDataLayer is used to set DARIDs that gets sent in the pixel call
In stage and qa environments there are test pages, which send requests to kibana. You can model your calls after these pages if you would like.
https://stage-repo.rakanto.com/rakanto/js-test
In addition to darids partitioning your data for reporting, custom data may be sent along as well. The purpose of which may be for A/B testing; reporting on site specific metric; or just to capture site specific information
The custom data is a object in the form of
CUSTOM_DATA_OBJECT = {'namespace':'darid_from_darid_list_on_page','key1':'value1','key2':'value2', ... }
custom fields will show up in Event as:
CF_*namespace*_key1=value1
CF_*namespace*_key2=value2The custom data object must not exceed 3000 bytes in total. for example the following string is 62 bytes long:
{'namespace':'darid_from_darid_list_on_page','key1':'value1'}
If the field exceeds that length, an error message is placed in javascript log, and the base64 encoded px_custom_data is set to cx_error_${event}` = 'send custom data size exceeded limit' this will show up in event.
The namespace is a required field and is used to generate a namespaced custom field as part of the event. These fields will be top level searchable fields in kibana.
The namespace provided in pxCustomData should match one of the DARIDs in the "darids" list
The namespace will be used to coin the field name for the custom field It will take the form CF_namespace_key1=value1
If namespace is not provided in pxCustomData, you will see "you must include a namespace in the custom data message." in console log You also will see an error message "error: Custom fields namespace is empty" in the event
If the provided namespace does not match with one of the DARIDs, you will get an error message "error: Custom fields namespace is invalid" in the Event
NOTE :
NOTE : Please do not send custom data messages from events which will rapidly fire, such as mouse movements.
We have tested against very large loads, however when we tested this exact scenario, one browser was generating over 1000 requests per second.CUSTOM_DATA_OBJECT = {'namespace':'darid_from_darid_list_on_page','key1':'value1','key2':'value2', ... }
apicall
Make an method call from your javascript.
window.pxSendCustomData(CUSTOM_DATA_OBJECT)
sessionStorage.getItem('pxCustomData');
Session storage only accepts STRINGS. So a STRING must be made from your CUSTOM_DATA_OBJECT
To do this, JSON.stringify your CUSTOM_DATA_OBJECT first.
Assign that string to the sessionStorage.pxCustomData object, the custom data will be sent on each pixel request, overriding any custom data on optumPageDataLayer.
sessionStorage.setItem( 'pxCustomData', JSON.stringify( CUSTOM_DATA_OBJECT ) )
Example
<html>
<head>
<script type="text/javascript">
sessionStorage.setItem('darids','UHG.Optum.Pixel.CXScriptExample.CustomData');
custom_data_object = {'namespace':'UHG.Optum.Pixel.CXScriptExample.CustomData','key1':'value1'}
sessionStorage.setItem('pxCustomData', JSON.stringify(custom_data_object) );
(function (cx, darids, a, m) {
i = window; s = document, o = 'script', r = 'Rakanto',
i['RakantoObject'] = r; i[r] = i[r] || function () {
(i[r].q = i[r].q || []).push([1 * Date.now()].concat(Array.prototype.slice.call(arguments)))
}, i[r].l = 1 * new Date(); a = s.createElement(o),
m = s.getElementsByTagName(o)[0]; a.id = 'rakanto'; a.src = cx;if (darids){a.setAttribute('data-px-darids', darids)}; a.async = 1; m.parentNode.insertBefore(a, m)
})('https://stage-repo.rakanto.com/rakanto/cx/cx.js');
</script>
</head>
<body>
<h1>Pixel Customer Experience Script</h1>
<h2>Custom Data</h2>
</body>
</html>
window.optumPageDataLayer
The window.optumPageDataLayer can also have a darid list, used for calls on the page. If custom data is specified, those key values are sent as well.
To use custom data, add an element called pxCustomData to the optumPageDataLayer, the value must be in the form of a javascript object. the custom data will be sent with each pixel request.
<html>
<head>
<title>CX Script Page</title>
<script type="text/javascript">
window.optumPageDataLayer = {
darids: ['UHG.Optum.Pixel.CXScriptExample.CustomData'],
pxCustomData: {'namespace':'UHG.Optum.Pixel.CXScriptExample.CustomData','key1':'value1'}
};
(function (cx, darids, a, m) {
i = window; s = document, o = 'script', r = 'Rakanto',
i['RakantoObject'] = r; i[r] = i[r] || function () {
(i[r].q = i[r].q || []).push([1 * Date.now()].concat(Array.prototype.slice.call(arguments)))
}, i[r].l = 1 * new Date(); a = s.createElement(o),
m = s.getElementsByTagName(o)[0]; a.id = 'rakanto'; a.src = cx;if (darids){a.setAttribute('data-px-darids', darids)}; a.async = 1; m.parentNode.insertBefore(a, m)
})('https://stage-repo.rakanto.com/rakanto/cx/cx.js');
</script>
</head>
<body>
<h1>Pixel Customer Experience Script</h1>
</p>(Darids from a Window Page Data Layer)</p>
</body>
</html>
Sending an event RIGHT AT CODE INVOCATION.
The CX Script is asynchronodataus, you cannot use window.pxSendCustomData, right after the call for the code, that method hasn't been loaded yet. You CAN however send events using the following method.
NOTE THE Rakanto() method at the bottom.
<html>
<head>
<title>CX Script Page</title>
<script type="text/javascript">
sessionStorage.setItem('darids','UHG.Optum.Pixel.CXScriptExample.CustomData');
(function (cx, darids, a, m) {
i = window; s = document, o = 'script', r = 'Rakanto',
i['RakantoObject'] = r; i[r] = i[r] || function () {
(i[r].q = i[r].q || []).push([1 * Date.now()].concat(Array.prototype.slice.call(arguments)))
}, i[r].l = 1 * new Date(); a = s.createElement(o),
m = s.getElementsByTagName(o)[0]; a.id = 'rakanto'; a.src = cx;if (darids){a.setAttribute('data-px-darids', darids)}; a.async = 1; m.parentNode.insertBefore(a, m)
})('https://stage-repo.rakanto.com/rakanto/cx/cx.js');
Rakanto('sendCustomData', {}, {namespace:'UHG.Optum.Pixel.CXScriptExample.CustomData', foo: 'bar'});
</script>
</head>
<body>
<h1>Pixel Customer Experience Script</h1>
</p>(This example will also send custom data upon initiation)</p>
</body>
</html>
Using in an Angular site.
Here’s the snippet of code an Angular developer would need to add to the component, directive, service, or where ever they will be sending custom data using the window.
This extends the Window global interface with a CX Script method reference you will use.
pxSendCustomData(CUSTOM_DATA_OBJECT) method:
declare global {
interface Window { pxSendCustomData: any; }
}
If you would prefer to use the optumPageDataLayer to send in data only on page app startload, load, and onbeforeunload, use the following.
declare global {
interface Window { optumPageDataLayer: any; }
}
open chrome inspector and view the network tab, click record
in a chrome console window, type:
window.pxSendCustomData({'namespace':'darid1','key1':'value1'})
To verify custom data, in osx:
in chrome inspector, look at the get request issued. copy the px_custom_data value, from the querystring in headers
run the command in osx terminal pbpaste | base64 -D -
This will base64 decode the value, your original hash data will show up.
The CX Script server includes a header
add_header Cache-Control 'private';This header makes it so the CX Script is not cached by edge caches, and is only cached by the browser. The CX Script is custom for each user. There are variables which are inserted into the script by the CX server, These variables are used for a correlation id, api endpoints and other things.
When the cache expires a session is checked when the new file is downloaded, based on the session values, variables are inserted into the new script.
The CX Script has multiple versions. If you would like to pin the version of the CX Script, append the version number to the url. You may find the version in the cx code, look for: exports={name:'@pixel/customer_experience',version:'VERSION_HERE' Ex. https://stage-repo.rakanto.com/rakanto/cx/cx-3.1.1.js
TIP : Not recommended. Pinning to a specific version limits you from benefitted from the latest features that gets added to CX Script.
Please work with Pixel team if you have an absolute need to pin to a specific version
The following bolded fields are searchable in Kibana.
cx variable name: px_custom_data
event: all
description:
create a object in the form of
{'namespace':'YOURDARID, 'key1':'value1', ... }
assign it to sessionStorage.pxCustomData, or pass it in via a page data layer, or set it with an api call.
it will show up in the pixel call as a base64 encoded representation of the object.
it will show up in Kibana as:
CF_YOURDARID_key1
cx variable name: px_pt
event: startPageLoad
description: when the script is first parsed. A list of the last 10 or less URLs visited and the timestamp of when they visited it by the user this session as a JSON array. pageUrl is the page viewed. pageViewDurationMillis is time on page updated every second. unixTimestampMillis is milliseconds since Jan 1, 1970. Ex:
"userPageHistory": [
{"pageUrl":"<https://rcpt-cs-tms.ocp-ctc-core-nonprod.optum.com/ubes/>","pageViewDurationMillis": 1000,""unixTimestampMillis": 1582050811076},
{"pageUrl":"<https://rcpt-cs-tms.ocp-ctc-core-nonprod.optum.com/ubes/>","pageViewDurationMillis": 1000,""unixTimestampMillis": 1582050862150}
]