HUMAN WebsiteBlogConsoleStatus PageContact Us

Integration with Google Analytics

Suggest Edits

Overview

This document provides an integration guide for using PerimeterX’s Binary Score and Data Classification Enrichment features with Google Analytics.

Prerequisites

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:

790

Create the following rule for Clean Segment:

807

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:

785
  • 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

  1. 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:
782
  1. Download both dictionaries and keep them somewhere safe. We will need to use them later.
  2. 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:

1000

📘

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:

  1. Name the new segment Good Bot Segment.
  2. Under Advanced click Conditions
  3. In the Conditions screen’s filter, select PerimeterX Good Bot Flag
  4. Change contains to is one of
  5. 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'
  1. 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