Skip to content

Integration Guide

Jump to bottom
Sam Tingleff edited this page Apr 25, 2019 · 56 revisions

Background

DigiTrust is designed to provide an anonymous, persistent and secure identifier for publishers and trusted third parties on all browser platforms.

IDs are produced in the browser using Web Crypto API to generate 64 bits of random data, which is base-64 encoded:

VJ+TjrjhnvU=

See the ID encryption page for more details about how IDs are produced and shared.

Publisher Integration

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

The javascript tag is added to the page as a <script> element directly, using a CMS/tag manager, or programmatically in javascript. This should execute before any ad serving, allowing for ad tech platforms to access the DigiTrust ID via API.

 <script src="https://cdn.digitru.st/prod/1/digitrust.min.js"></script>
 <script type="text/javascript">
   DigiTrust.initialize({
       member: "nQjyizbdyF",
       site: "FL6whbX1IW",
       redirects: true
     });
 </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/digitrust.min.js';
  s.onload = s.onreadystatechange = function() {
    if ( !r && (!this.readyState || this.readyState == 'complete') )
    {
      r = true;
      DigiTrust.initialize( {
        member: 'nQjyizbdyF',
        site: 'FL6whbX1IW',
        redirects: true
      });
    }
  };
  t = document.getElementsByTagName('script')[0];
  t.parentNode.insertBefore(s, t);
}());
</script>

Semantic Versioning and Subresource Integrity

Note that the recommended integration via <script> tag points to a "major release" version at /prod/1/digitrust.min.js. This path is subject to (non-breaking) changes as DigiTrust fixes bugs, adds minor features, etc.

Alternatively publishers and platforms can link to a specific minor release at a path like /prod/1.5.31/digitrust.min.js (the contents of which will not change), and may also include SRI attributes. SRI provides the 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 DigiTrust members to test and deploy a specific version with confidence that it will not change.

A tool like SRI hash generator may be used to generate the appropriate hash value for the integrity attribute in an SRI deployment:

 <script src="https://cdn.digitru.st/prod/1.5.31/digitrust.min.js"
         integrity="sha384-FOJqaxeGAQRQxm/+qwT645rLaF5NUkRt8cPTwS2mmWgDELBGX1ubMQ2393eklTDT"
         crossorigin="anonymous"></script>

The cost of linking to a specific minor version is that from time to time we may ask (possibly very urgently) that you upgrade to a new version for specific bug fixes.

Critical: note that in order to use SRI you must link to a specific minor version (/prod/1.5.31/digitrust.min.js as in the example immediately above) rather than to a major version (such as /prod/1/digitrust.min.js) as the major version release is subject to change.

API Behaviors

Behavior is exposed in the DigiTrust.initialize method:

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

Parameters

Name Description Type Required Default Example(s)
member Unique member identifier string yes n/a "nQjyizbdyF"
site A unique site identifier, such as the domain or an ad server ID string yes n/a "FL6whbX1IW"
redirects Whether or not link-rewriting behavior should be enabled to acquire a first party context (and write a cookie) boolean no false true
sample Random sample rate at which behavior(s) should be enabled float value between 0 and 1 no 1 0.25

Third Party Integration

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

Parameters

Name Description Type Required Default Example(s)
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 Vb0YJIxTMJV4W0GHRdJ3MwyiOVYJjYEgc2QYdBSG+48eThEDnz45f9/d3oVw3l4PvucuLvgSsZbTCYIIUas635/ORnpentSP6eNt/aPCg/0366FjICCj8Q/zNI+GmhFvl0IB12t2+s+rOxxoSi+XuItLUyPHpw7oUz30JJHUMTH7qylDXdRQEG2a1ofFzEaxd4SBmKyQwXaSm3HC4lmFdsXJjJhkQItGJhybdHGVggd74mll63USLrTOnGJWGyynTNdnr9dYUXRIys3pSiLFam6HjbSpyy9YCf5O0D2b2ViJ3Or72mlV2i0bQFN2uGI+ZBDrYn9GjB1jNHCwbhwppw==
keyv Key version used to encrypt the id integer yes 4
version ID version (see notes below) integer no (assume v1 if not present) 2
privacy Device privacy settings Privacy object yes See the Privacy object below

Example

{
 "id":"Y4SEEda7hs8Bh4j7WIxyxMvzMz1OGj/Cbg9EiveEwK0ctK3Aj0Gi/VMpNJFY/4MT61lxVb2qVkYr9MDl4j/YegqZOmAwQm+Y6b6hCzyMYUslbnKvCLjTSVWdqR3oaId8avgwwILH/eE/Qp6azONQideye28VlzIllzWRUIIlA7miCbXaMVaBBKWmbkGKjoL8aCMsOy+l3u35yLHO8CyoeGl2fgwtafVFbN2TkwoBZQpdtdT2csOXa/jpQ+8DnKCv0ux+6GhCddhbXPOMWg30/23Q7QmdmATLiA/xiPRYIFmAViRheF32J1g9oLmRGrXRrlzqYgPyI1M/t5FzFnByBA==",
 "keyv": 1,
 "version": 2,
 "privacy":
  {
   "optout": false
  }
}

ID Values

The id field is produced in the browser approximately with

var buffer = new Uint8Array(8);
crypto.getRandomValues(buffer);
return arrayBufferToBase64String(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

In un-encrypted form this can be represented as a byte array

[86, 74, 43, 84, 106, 114, 106, 104, 110, 118, 85, 61]

Or a 64 bit integer

6217829877101521512

However the canonical form of the ID is the base-64 encoded version.

VJ+TjrjhnvU=

ID Versions

The version field is intended to allow for changes in ID size and encodings. The following versions have been in production in some form or another.

  • 1: did not see production usage.
  • 2: 64 bits of random data, base-64 encoded.

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