Skip to content

Integration Guide

Jump to bottom
Sam Tingleff edited this page Jun 12, 2017 · 56 revisions

Background

DigiTrust is designed to provide an anonymous, persistent and secure identifier for publishers and trusted third parties on all browser platforms, including those which do not support third party cookies by default.

The mechanism by which we acquire a cookie is to use javascript to rewrite links to send a redirect through the digitru.st domain, which provides a first party context in the browser for a cookie write. Note that this only occurs once within the cookie lifetime - subsequent page views after the redirect (on any publisher domain) will not require or cause a redirect.

Publisher Integration

The (current) reference version of the tag is available at https://cdn.digitru.st/prod/1.3.3/digitrust.js.

The javascript tag is either added to the page as a <script> element

 <script src="https://cdn.digitru.st/prod/1.3.3/digitrust.js"
   integrity="sha384-fT+oPpsIdRinek7W/EPvLcsaSgGqrSozTobC2FW6Mg2YzpN5850EFMGFqtXaPQ6A"
   crossorigin="anonymous"></script>
 <script type="text/javascript">
   DigiTrust.initialize({
       member: 'nQjyizbdyF',
       site: "FL6whbX1IW"
     },
     function (digiTrustResult) {
     });
 </script>

Or programmatically added to the DOM

<script type="text/javascript">
(function() {
  var s, r, t;
  r = false;
  s = document.createElement('script');
  s.type = 'text/javascript';
  s.src = "https://cdn.digitru.st/prod/1.3.3/digitrust.js";
  s.onload = s.onreadystatechange = function() {
    if ( !r && (!this.readyState || this.readyState == 'complete') )
    {
      r = true;
      DigiTrust.initialize( {
        member: "nQjyizbdyF",
        site: "FL6whbX1IW",
      },
      function(digiTrustResult) {
       console.log(digiTrustResult);
      });
    }
  };
  t = document.getElementsByTagName('script')[0];
  t.parentNode.insertBefore(s, t);
}());
</script>

Subresource Integrity

Note that the recommend integration via <script> tag includes SRI attributes, which guarantee (on browsers which support SRI) that the browser will not execute the resource if the contents (file hash) have changed. This is intended to allow publishers to test and deploy a specific version with confidence that it will not change.

Behaviors

Behavior is exposed in the DigiTrust.initialize method:

DigiTrust.initialize = function (options, callback) {
 ...
};

Parameters

Name Description Type Required Default Example(s)
options.member Unique member identifier string yes n/a nQjyizbdyF
options.site A unique site identifier, such as the domain or an ad server ID string yes n/a FL6whbX1IW

Third Party Integration

DigiTrust.getUser = function (options, callback) {
 ...
};

Parameters

Name Description Type Required Default Example(s)
options.member Unique member identifier string yes n/a h89wWpG06u

Return Value

The return value is an IdentityResponse object. An Identity object is included if one can be read from publisher cookies.

Examples

Synchronous

var identityResponse = DigiTrust.getUser( );

In this model, no callback function is provided, and if an identity is available via low-latency/synchronous methods, it is returned within the Identity Response object.

Asynchronous

DigiTrust.getUser( { }, function(identityResponse) {
});

In this example a callback function is provided. The behavior is to provide an Identity Response object to the callback after communicating with the digitru.st hosted invisible iframe.

Objects

Identity

An Identity object is the primary container for attributes persisted within the browser.

Attributes

Name Description Type Always Provided Example(s)
id Unique device identifier 64 bits of crypto-quality random data, base-64 encoded, encrypted via RSA and base-64 encoded (again) (string) no cBJ1bz5YDROPuB9LWHyZvL83UThTzFx7VXdS+V1E2H1zogB3USRT4ao3bq0mg311DDM6yW9R1dbUCxTsc5NNb03yxZDN7Za75s3EychyihLG08ZQ0ox4jnYPYw4iD3Q4xkKmhJbpHb4Yl6gPa9GmzINBQz9dWFvG97aV3K0Fn458ZXPQ46r5GUpi3aiIXyBe3nXL7eDGjzjxawxcJPGdF8ctqAxWJVg7/9RdRvz/robgXylKpOpbB/dv9dzhb64PnEBS4nv0ng/AEnmrfWSlmhmtkX1l58h/fAv8kUVn1430ylZwD0ixf5Nd/uzHHAtclZyoCVUGt8MjySeHGXCNZA==
keyv Key version used to encrypt the id integer yes 4
privacy Device privacy settings Privacy object yes See the Privacy object below

Example

{
 "id":"cBJ1bz5YDROPuB9LWHyZvL83UThTzFx7VXdS+V1E2H1zogB3USRT4ao3bq0mg311DDM6yW9R1dbUCxTsc5NNb03yxZDN7Za75s3EychyihLG08ZQ0ox4jnYPYw4iD3Q4xkKmhJbpHb4Yl6gPa9GmzINBQz9dWFvG97aV3K0Fn458ZXPQ46r5GUpi3aiIXyBe3nXL7eDGjzjxawxcJPGdF8ctqAxWJVg7/9RdRvz/robgXylKpOpbB/dv9dzhb64PnEBS4nv0ng/AEnmrfWSlmhmtkX1l58h/fAv8kUVn1430ylZwD0ixf5Nd/uzHHAtclZyoCVUGt8MjySeHGXCNZA==",
 "keyv": 1,
 "privacy":
  {
   "optout": false
  }
}

ID Values

The id field is produced in the browser approximately with

var buffer = new Uint32Array(2);
crypto.getRandomValues(buffer);
return btoa(buffer);

Note that

  • this is intended to provide 64 bits of entropy
  • values may exceed Long.MAX_VALUE in java (it is unsigned) or similar constructs in other languages
  • this value is RSA-encrypted at all times outside of the digitru.st cookie space

Privacy

The Privacy object includes all privacy related settings attached to a given device.

Attributes

Name Description Type Always Provided Example(s)
optout whether or not the user has opted out boolean yes false,true

Example

{
 "optout": false
}

Identity Response

An identity response object is provided in the initialize() callback.

Attributes

Name Description Type Always Provided Example(s)
success Indicator of success or failure boolean yes true, false
identity The persisted device identity Identity object no See below
Clone this wiki locally