Integration with Google Analytics
Overview
This document provides an integration guide for using PerimeterX’s Binary Score and Data Classification Enrichment features with Google Analytics.
Prerequisites
- PerimeterX Sensor deployed on the website
- Admin access to the PerimeterX Portal
- Access to Google Analytics
- Creating custom dimensions - https://support.google.com/analytics/answer/2709828?hl=en
- Access to Google Tag Manager
- Access to update your website code
Integrating with Google Analytics Segments
Enable Score Reporting
In the PerimeterX Portal navigate to Product Settings -> Data & Configuration -> Score Reporting and select the policy associated with your defined application. Then, toggle the Score Reporting button to Enabled and select the Binary radio button. Set the threshold score to 100.
Creating a Custom Dimension in Google Analytics
In the Google Analytics interface navigate to the Admin section and then select custom definitions. Click on the New Custom Dimension button and add the following properties:
- Name: PerimeterX Bot Flag
- Scope: Hit
- Active: box checked
Once saved, the new rule should be visible in the table
Take note of the dimension index as it will be used in your Javascript code later on.
Segmentation
You should create two new segments named Bot Segment and Clean Segment in Google Analytics. These segments can now be used to slice traffic in any reports and dashboards.
Under Personal Tools & Assets click on Segments and create the following rule for Bot Segment:

Create the following rule for Clean Segment:

Javascript Integration
The binary result from PerimeterX evaluation will be returned as an event. In order to receive the event the following function must be created and the result will be stored in a Google Analytics custom dimension:
window.<APPID>_asyncInit = function(px) {
px.Events.on('score', function(score) {
// Set your action for the score here
// The score can go to another variable or function
try {
// Set custom dimension for Google Analytics
ga('send', 'pageview', {
'dimension1': score });
} catch (err) {
console.log("error: " + err);
}
});
};
Note
is replaced by your app ID.
For example, if your APPID is PX12345678 then your function variable will be window.PX12345678_asyncInit.
The Javascript integration can be added to your existing PerimeterX Javascript snippet. An example of a third party JavaScript snippet will look as follows:
<script type="text/javascript">
(function() {
window.<APPID>_asyncInit = function(px) {
px.Events.on('score', function(score) {
// Set your action for the score here
// The score can go to another variable or function
try {
// Set custom dimension for Google Analytics
ga('send', 'pageview', {
'dimension1': score
});
} catch (err) {
console.log("error: " + err);
}
});
};
// Custom parameters
// window._pxParam1 = "<param1>";
var p = document.getElementsByTagName('script')[0],
s = document.createElement('script');
s.async = 1;
s.src = '//client.px-cloud.net/<APPID>/main.min.js';
p.parentNode.insertBefore(s, p);
})();
</script>
Enriching Google Analytics with PerimeterX Data Enrichment
Data Enrichment Overview
Data Classification Enrichment allows you to add enriched data to each request. Every time PerimeterX handles a request, the hashed enriched data is added to the call and returned as an additional cookie called _pxde. The enriched data can also be retrieved on the client side using the enrich event listener.
The data enrichment cookie contains a JSON of hashed data for two data types:
- Access Control - contains all of the custom rules, known bots and IP classifications defined in your application policy.
- IP Categorization - The categories defined in the different services types including Cloud and Proxy, as well as other general categories.
A data classification enrichment cookie will contain a base64 encoded JSON with the following structure:

- Timestamp - the creation time of the cookie.
- f_type - the access control rule type:
- w = whitelist
- b = blacklist.
- f_id - the access control rule ID. The ID is detailed in the access control dictionary in the PerimeterX Console. Possible values for the rule:
- Custom rule
- Known bot
- IP classification
- f_origin - the data is defined either as a Custom Rule or as a PerimeterX rule. Known bots and IP Classification rules will always be marked as “px”.
- f_kb - specifies if the request is made by a known bot or not:
- 1 = known bot
- 0 = other
- ipc_id - an array of IP Categorization IDs. The IDs are detailed in the IP Categorization dictionary in the PerimeterX Console.
Enable Data Enrichment in PerimeterX Console
- In the PerimeterX Console and navigate to Admin -> Policies. Open Data Classification Enrichment and enable the first toggle and either one or both of the data option toggles:

- Download both dictionaries and keep them somewhere safe. We will need to use them later.
- Click Apply.
If you browse your site, you should now see a new cookie is getting baked - _pxde.
Creating the Custom Dimension in Google Analytics
In the Google Analytics interface, navigate to the Admin section and then select custom definitions. Click on New Custom Dimension:
Add the following properties:
- Name: PerimeterX Good Bot Flag
- Scope: Hit
- Active: box checked
Once saved, the new rule should be visible in the table:

Make note of the dimension index as it will be used in your Javascript code.
Creating the Segmentation
You should create a new segment named Good Bot Segment in Google Analytics. These segments can now be used to slice good traffic and differentiate between good bot traffic and regular traffic in any reports and dashboards.
In Personal Tools & Assets, click Segments and create a new rule for the Good Bot Segment:
- Name the new segment Good Bot Segment.
- Under Advanced click Conditions
- In the Conditions screen’s filter, select PerimeterX Good Bot Flag
- Change contains to is one of
- Copy the UUIDs of all the allowed entities from the Access Control JSON that you downloaded earlier, and paste them, one per line, inside the filter text box. Any entity included in this list will be considered as a good bot in your segmentation
- To include all of the allowed entities in your segmentation, run the following command to generate a list of all the UUIDs, one per line:
cat <access control dictionary file>.json | jq '."Known Bots and Crawlers"|to_entries|.[]|select(.value.type =="whitelist")|.key'
- To include the allowed entities from your custom rules, run the following command:
cat <access control dictionary file>.json | jq '."Custom Rules"|to_entries|.[]|select(.value.type =="whitelist")|.key'
- Save the new segmentation.
JavaScript integration
To handle data enrichment on the client side, you can use the enrich event:
window.<APPID>_asyncInit = function(px) {
px.Events.on('enrich', function (value) {
// value - the enriched data, in the form of <HMAC>:<Base64 encoded data>
const base64Data = value.split(":")[1]; // split value to get the base64 encoded data
const dataStr = atob(base64Data); // base64 decode the enrichment data
const data = JSON.parse(dataStr); // get the data as JSON
console.log('DATA', data);
});
};
In the above example, the data variable holds the hashed JSON of the data enrichment cookie, similar to what shown in the cookie data example shown in Data Enrichment Overview
To check a possible match against the list of UUIDs we added to the segment, send the f_id property from the hashed JSON to GA on the custom dimension created earlier:
window.<APPID>_asyncInit = function(px) {
px.Events.on('enrich', function (value) {
...
const data = JSON.parse(dataStr); // get the data as JSON
try {
// Set custom dimension for Google Analytics
ga('send', 'pageview', {'dimension2': data['f_id'] });
} catch (err) {
console.log("error: " + err);
}
});
};
Note
If you wish to enrich the Google Analytics model even further, you can set additional segments for known bots (the f_kb property) or type of access control (the f_type property). In addition, you can add the ip categorization of the request using the ipc_id property and the ip categorization dictionary, downloadable from the PerimeterX console.
Appendix
Improving First Page Performance
First page load performance can be improved in modern browsers by adding the following lines to the HTML HEAD section of the webpage to prefetch the DNS when you are not using a first party snippet.
<link rel="dns-prefetch" href="//client.px-cloud.net">
<link rel="dns-prefetch" href="//collector-<APPID>.px-cloud.net">
<link rel="preconnect" href="https://collector-<APPID>.px-cloud.net"/>
<link rel="preconnect" href="//client.px-cloud.net"/>
Note
should be replaced by your app ID. For example, if your APPID is PX12345678 then the hostname will be collector-PX12345678.perimeterx.net
Updated about 1 month ago