JavaScript Consent Tag Spec

The JavaScript Consent Tag will provide a callable wrapper around the Consent & Consumer Webservice API when you have the Audience Studio Control Tag on the page. The API call will happen asynchronously, and then you can provide a callback to handle the response.

The JS Consent Tag acts as the Control Tag for that domain, knows that consent has been set, and ignores the GET request because it has more recent information saying "can collect data". Additionally, Event tags that are fired using the Javascript tag are also checked against this consent information. The inverse is also true. If the Consent Tag doesn't know about consent, it cannot accidentally send on data as an event pixel (non-Javascript) would.

However, if you are using the API directly, instead of the Javascript Tag (that fires the API call), then you may have to wait up to 4 hours before you receive the response, "these are the flags for consent".  The Audience Studio control tag can only start collecting data after the application has received your "get" request verifying that consent is valid.

Tag Format

Use the following guidelines to create your JavaScript Consent Tags:

Domains

Since the domain information is stored in localStorage, it is limited by the browser to a combination of:

• subdomain
• AND domain
• and HTTP vs HTTPS

  Each of the examples below has a completely different localStorage store because browsers dictate this, and the client needs to send on consent to collect from these. An alternative is to not use subdomains, and keep all traffic on HTTPS. 

  • http://www.mycompany.com
  • https://www.mycompany.com
  • https://sub.mycompany.com

Tag Format Overview

The JavaScript Consent Tag snippet can be retrieved by navigating to Manage>> Sites in the Audience Studio UI and clicking the </> (Actions) button on the right. If you retrieve the snippet from the Audience Studio UI, then the namespace will automatically be populated. Otherwise you can contact your CSG Team Lead for your account's namespace.

Krux('ns:NAMESPACE', 'consent:ROUTE', parameters, callback)

NAMESPACE — the namespace used on the DPM Customer's site. 

Note regarding ’ns:NAMESPACE’: If your organization is not configured with a namespace, then do not provide this argument when calling the JavaScript Consent Tag. Instead, the tag should be called with three arguments as follows: Krux('consent:ROUTE', parameters, callback). If you are unsure whether your organization has a namespace configured, contact your CSG lead or retrieve and use the tag from the Audience Studio UI as described above. The tag generated in the UI will only include the namespace argument if a namespace is configured.

ROUTE — the type of API request. The four available routes are get, set, remove, and portability (same as in the Consent & Consumer Webservice documentation).

Parameters

parameters — a JSON object of parameters to be sent with the API request. The parameters available to each route mirror the Consent & Consumer Webservice documentation, except any callback function should be specified as the fourth argument of the Krux method instead of via the parameters object (cb key).

Parameter	Data Type	Description	Required Routes
idt	string	The type of identifier that will be used:  bk or device	get, set, remove, portability
dt	string	If idt is device, this field is used to define which type of device is being used:  kxcookie, idfa, aaid, other (first party ID)	get, set, remove, portability (used only if idt = device)
bk	string	Bridge key name; the attribute name of the bridge key passed in. This can be any bridge key attribute defined in your account.	get, set, remove, portability (used only if idt = bk)
idv	string	An ID value, which may be a Krux cookie, advertiserId (from Android), IDFA (from iOS), first party ID, bridge key value (e.g., hashed), or some other identifier. Leave blank to have the Krux cookie looked up off the request.	set, set, remove, portability
pr	string	Policy Regime the user falls under. If not given and we are unable to determine the policy regime through other means, the default policy regime will be used as configured for your organization. Currently, we support gdpr and global as the values.	optional for all routes
callback	string	A callback to invoke for JSONP response. This must begin with Krux and the function should be defined on page before calling.	get
dc	boolean	Consent flag for whether data collection is allowed (true, false)	set
al	boolean	Consent flag for whether analytics is allowed (true, false)	set
tg	boolean	Consent flag for whether targeting is allowed (true, false)	set
cd	boolean	Consent flag for whether cross-device linking is allowed (true, false)	set
sh	boolean	Consent flag for whether data sharing is allowed (true, false)	set
re	boolean	Consent flag for whether re-identification is allowed (true, false)	set

Note regarding identity parameters: since the JavaScript Consent Tag will be called after the Audience Studio Control Tag, if the device type is kxcookie, then you are not required to pass the parameters idt, dt, idv. However, if the device type is aaid, idfa, other, or a bridge key, then you must explicitly pass the identity parameters.

Note regarding consent flag parameters: for more detail on Consent Flag definition, conflict resolution, and format, please refer to the Consent Flags section of the Audience Studio Consent Management Concept and Glossary. For the JavaScript Consent Tag, you should use the following format to set the consent flag parameters:

dc: true,
tg: true,
al: true,
cd: true,
sh: false,
re: true

Callback

callback — a function that will be called after the API request completes, in both success and failure cases. The first parameter of the callback function will receive the errors object of the API response in JSON form. The second parameter of the callback function will receive the body of the API response in JSON form. The specific fields of the errors and body objects are specified per-route in the Consent & Consumer Webservice API documentation. When calling the get route, the callback function is required because its body parameter will provide the caller with the data subject's consent flags. For other routes, the callback function is optional, but can be used to parse and receive errors, verify the request's format, and trigger events upon success and failure.

callback function(errors, body) — A function that will be called after the asynchronous request completes. It will be passed with two arguments:

• errors object — An object containing any errors encountered in validating the request.
• body object — An object that contains the following fields:
  • dc integer — Whether data collection is allowed.
  • al integer — Whether analytics is allowed.
  • tg integer — Whether targeting is allowed.
  • cd integer — Whether cross-device linking is allowed.
  • sh integer — Whether data sharing is allowed.
  • re integer — Whether re-identification linking is allowed.
  • api — a call to this service to set the consent (1st party).
  • file — a file import directly from Audience Studio customer containing consent (1st party).
  • indir — Indicates consent came from an event which inherited the second party consent defaults from the UI configuration.
  • nai — Indicates consent came from a generic opt out through the NAI.
  • daa — Indicates consent came from a generic opt out through the DAA.
  • dmp — Indicates consent came from a generic opt out through the Audience Studio consumer privacy page.
  • unk — Indicates user has not given any direct or indirect consent, and therefore consent is not known.
• request_id string — A unique token for the request. Store this value if you need to audit the settings later.
• timestamp integer — The timestamp of the request, using Unix time conventions.
• code string — A string representing the response, one of (success, warning, specific failure message).
• idt string — The type of identifier, must be bk (bridge key) or device.
• dt string — The type of the idv (e.g., idfa).
• idv string — An ID value, which may be a Krux cookie, first party ID, advertiserId (from Android), IDFA (from iOS), bridge key value (e.g., hashed), or some other identifier.
• bk string — Bridge key name; the attribute name of the bridge key passed in. This can be any bridge key attribute defined in your account.
• settings object — An object containing the user's consent settings:
• source — A representation of where the consent came from. We will overwrite 3rd party consent with 2nd party and 2nd party with 1st party, but not the opposite (e.g., 2nd party cannot be overridden by 3rd party). There are 7 possible values:

Routes

get: Get Consent Flags

The consent:get method can be called to get the consent settings for a data subject. The function call should be executed as follows, with optional parameters:

Krux('ns:mynamespace', 'consent:get', parameters, callback);

get: Examples 

Example 1: Get the consent flags for a data subject identified by the Krux Cookie, and perform an action if the data subject allows targeting. Note that the identity parameters are not required since the device type is kxcookie.

Krux('ns:mynamespace', 'consent:get', function(errors, body) {
  if (errors) {
    console.error(errors);
  } else {
    if (body.settings.tg) {
      console.log('This data subject allows targeting.');
    }
  }
});

Example 2: Get the consent flags for a data subject identified by an aaid with a test value and perform an action if the data subject allows data collection.

Krux('ns:mynamespace', 'consent:get', {
  idt: 'device',
  dt: 'aaid',
  idv: '12345678-1234-1234-1234-123456789012'
}, function(errors, body) {
  if (errors) {
    console.error(errors);
  } else {
    if (body.settings.dc) {
      console.log('This data subject allows data collection.');
    }
  }
});

Example 3: Get the consent flags for a data subject identified by bridge key “bridgekey1” with value “testing,” explicitly using the GDPR policy regime, and perform an action if the data subject allows data collection:

Krux('ns:mynamespace', 'consent:get', {
  idt: 'bk',
  bk: 'bridgekey1',
  idv: 'testing',
  pr: 'gdpr'
}, function(errors, body) {
  if (errors) {
    console.error(errors);
  } else {
    if (body.settings.dc) {
      console.log('This data subject allows data collection.');
    }
  }
});

set: Set Consent Flags

The consent:set method can be called to get the consent settings for a data subject. The function call should be executed as follows, with optional callback:

Krux('ns:mynamespace', 'consent:set', parameters, callback);

set: Examples

Example 1: Set the consent flags for a data subject identified by the Krux Cookie, and perform an action if the data subject allows targeting. Note that the identity parameters are not required since the device type is kxcookie. All consent flags are required with the set method.

Krux('ns:mynamespace', 'consent:set', {
  dc: true,
  al: true,
  tg: true,
  cd: false,
  sh: false,
  re: false
}, function(errors, body) {
  if (errors) {
    console.error(errors);
  } else {
    console.log('Successfully set consent flags.');
  }
});

Example 2: Set the consent flags for a data subject identified by an idfa with a test value. All consent flags are required with the set method.

Krux('ns:mynamespace', 'consent:set', {
  idt: 'device',
  dt: 'idfa',
  idv: '1A23456B-1234-1AA2-1AB2-AB1C-12345678A9BC',
  dc: true,
  al: true,
  tg: true,
  cd: true,
  sh: false,
  re: false
});

remove: Initiate a RTBF Request

The consent:remove method can be called to initiate a RTBF (request to be forgotten) request for a data subject. The function call should be executed as follows, with optional parameters and callback:

Krux('ns:mynamespace', 'consent:remove', parameters, callback);

remove: Examples

Example 1: Initiate a RTBF request for a data subject identified by the Krux Cookie. Note that the identity parameters are not required since the device type is kxcookie. The optional callback is not included in this example.

Krux('ns:mynamespace', 'consent:remove');

Example 2: Initiate a RTBF request for a subject identified by an idfa with a test value and log when the request has been successfully received:

Krux('ns:mynamespace', 'consent:remove', {
  idt: 'device',
  dt: 'idfa',
  idv: '1A23456B-1234-1AA2-1AB2-AB1C-12345678A9BC'
}, function(errors, body) {
  if (errors) {
    console.error(errors);
  } else {
    console.log('Successfully received RTBF request.');
  }
});

portability: Add a User to a Portability Feed

The consent:portability method can be called to initiate a request to add a data subject to a portability feed. The function call should be executed as follows, with optional parameters and callback:

Krux('ns:mynamespace', 'consent:portability', parameters, callback);

portability: Examples

Example 1: Initiate a request to add a data subject to a portability feed, identified by the Krux Cookie. Note that the identity parameters are not required since the device type is kxcookie. The optional callback is not included in this example.

Krux('ns:mynamespace', 'consent:portability');

Example 2: Initiate a request to add a data subject to a portability feed, identified by bridge key “bridgekey2” with value “123,” and log when the request has been successfully received.

Krux('ns:mynamespace', 'consent:remove', {
  idt: 'bk',
  bk: 'bridgekey2',
  idv: '123'
}, function(errors, body) {
  if (errors) {
    console.error(errors);
  } else {
    console.log('Successfully received portability request.');
  }
});