JavaScript Consent Tag Spec

The JavaScript Consent Tag will provide a callable wrapper around the Consent & Consumer Webservice API when the DMP Customer has the Salesforce DMP Control Tag on the page. The API call will happen asynchronously, and a callback can be provided to handle the response.

Tag Format

Tag Format Overview

The JavaScript Consent Tag snippet can be retrieved by navigating to Manage>> Sites in the Salesforce DMP UI and clicking the </> (Actions) button on the right. If you retrieve the snippet from the Salesforce DMP 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 Salesforce DMP 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 Salesforce DMP 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 DMP 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:
    • 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:
      • 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.
    • 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:
      • api — a call to this service to set the consent (1st party).
      • file — a file import directly from DMP 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 DMP consumer privacy page.
      • unk — Indicates user has not given any direct or indirect consent, and therefore consent is not known.

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 value “testing,” and perform an action if the data subject allows data collection.

Krux('ns:mynamespace', 'consent:get', {
idt: 'device',
dt: 'aaid',
idv: '38400000-8cf0-11bd-b23e-10b96e40000d'
}, 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: false,
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 value “321”. All consent flags are required with the set method.

Krux('ns:mynamespace', 'consent:set', {
idt: 'device',
dt: 'idfa',
idv: '6D92078A-8246-4BA4-AE5B-76104861E7DC',
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 value “testing,” and log when the request has been successfully received:

Krux('ns:mynamespace', 'consent:remove', {
idt: 'device',
dt: 'idfa',
idv: '6D92078A-8246-4BA4-AE5B-76104861E7DC'
}, 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.');
}
});
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.