Client Documentation

Parrable context in Snowplow

Snowplow is a data collector that saves data either in real-time or batch into your own AWS account and allows 'context' extensions to collect partner's data.

Parrable is a proprietary technology that allows you to map different page impressions from the same browser into a browser id and, in future releases, map different browser ids to the same device id.

By having the Snowplow JS tracker and the Parrable loader in a page, the data from the Parrable object can be passed into the Snowplow collector and saved the schemas setup on the AWS account where data is being collected. Besides capturing the eid and optout, by configuring the API Enrichment setup on Snowplow, the eid can be decrypted into browserid, allowing all this data to be available for analysis.

snowplow

Before you setup

This documentation assumes a current Snowplow account and a correct implementation of the setup.

To complete the integration, you need to have access to

modify the JS setup of the page Snowplow is loading on
your data schemas
Setup an Enrichment

Information needed to do the integration

The following information from Parrable is needed

Parrable loader with a unique tracker
Authentication information for the dereferencing (username and password)

Please contact [email protected] or your current integration manager to obtain this data.

How to setup the Parrable context in Snowplow

Include the script of the Parrable loader with your assigned tracker before the snowplow collector script, since the data needs to load before snowplow can collect it.
The Parrable-enabled Snowplow loader hasn't yet been released by Snowplow. In the meantime, our Snowplow reviewed version that enables the Parrable context is found at https://cdn.parrable.com/js/snowplow/sp.js. Change the current path of the sp.js to this URL.
Activate the capture of the context by adding parrable: true in the context configuration of snowplow

For example:

//(1) Your parrable tracker should nbe above this line
<!-- Snowplow starts plowing -->
<script type="text/javascript">

    ;(function(p,l,o,w,i,n,g){if(!p[i]){p.GlobalSnowplowNamespace=p.GlobalSnowplowNamespace||[];
    p.GlobalSnowplowNamespace.push(i);p[i]=function(){(p[i].q=p[i].q||[]).push(arguments)
    };p[i].q=p[i].q||[];n=l.createElement(o);g=l.getElementsByTagName(o)[0];n.async=1;
    n.src=w;g.parentNode.insertBefore(n,g)}}(window,document,"script","https://cdn.parrable.com/js/snowplow/sp.js","snowplow"));// (2) url change 

    window.snowplow('newTracker', 'co', '---.collector.snplow.net', {//modify with your data
      platform: 'web',
      post: true,
      contexts: {
        webPage: true,
        performanceTiming: true;
        parrable: true //(3) include parrable context
      }
    });
    window.snowplow('enableActivityTracking', 30, 30); // Ping every 30 seconds after 30 seconds
    window.snowplow('enableLinkClickTracking');
    window.snowplow('trackPageView');
</script>
<!-- Snowplow stop plowing -->

After all these steps have been correctly setup, you should be able to see the schema com_parrable_encrypted_payload_1, in your snowplow data that contains the encrypted id eid and optout

To collect the decrypted browser id, the API Request Enrichment needs to be setup

API Request Enrichment

Configure an API Request Enrichment in your Snowplow installation which follows this template:

{
  "schema": "iglu:com.snowplowanalytics.snowplow.enrichments/api_request_enrichment_config/jsonschema/1-0-0",

  "data": {
    "name": "api_request_enrichment_config",
    "vendor": "com.snowplowanalytics.snowplow.enrichments",
    "enabled": true,
    "parameters": {
      "inputs": [
        {
          "key": "encryptedId",
          "json": {
            "field": "contexts",
            "schemaCriterion": "iglu:com.parrable/encrypted_payload/jsonschema/1-*-*",
            "jsonPath": "$.encryptedId"
          }
        }
      ],
      "api": {
        "http": {
          "method": "GET",
          "uri": "https://ad.parrable.com/?id={{"{{encryptedId}}"}}",
          "timeout": 5000,
          "authentication": {
            "httpBasic": {
              "username": "{{secret "parrable_api_username"}}",
              "password": "{{secret "parrable_api_password"}}"
            }
          }
        }
      },
      "outputs": [ {
        "schema": "iglu:com.parrable/decrypted_payload/jsonschema/1-0-0",
        "json": {
          "jsonPath": "$"
        }
      } ],
      "cache": {
        "size": 3000000,
        "ttl": 0
      }
    }
  }
}

populating it with the credentials provided by Parrable in the username and password fields in the api > authentication> httpBasic fields,

"api": {
          "authentication": {
            "httpBasic": {
              "username": "{{secret "parrable_api_username"}}",
              "password": "{{secret "parrable_api_password"}}"
            }
          }
        }

The template can be found at https://github.com/snowplow-proservices/com.parrable-snowplow-pipeline/blob/master/jobs/qa/snowplow/enrichments/api_request_enrichment_config.json.tmpl

Please refer to the Snowplow documentation on how to setup Enrichments for your setup.

After all these steps have been correctly setup, you should be able to see the schema com_parrable_decrypted_payload_1 containing the browserid (and an empty deviceid which will be populated in future releases of parrable) in addition to the com_parrable_encrypted_payload_1, with the encrypted id eid and optout found before.

Provide feedback

Saved searches