The Adzerk Developer Hub

Welcome to the Adzerk developer hub. You'll find comprehensive guides and documentation to help you start working with Adzerk as quickly as possible, as well as support if you get stuck. Let's jump right in!

GDPR Compliance and Consent Settings

This document describes specific integration instructions to ensure compliance with the European Union's General Data Protection Regulation (GDPR).

Please refer to our Adzerk & GDPR doc for a high-level overview of how to prepare for the GDPR.

GDPR compliance and consent settings are also applicable to Swiss traffic as per the Swiss Federal Data Protection Act (DPA).

Setting Consent on the Ad Request - Decision API

To set GDPR consent on a Decision API request, add a top-level consent object:

"consent": {"gdpr": true}

Note that GDPR consent will default to false unless it is explicitly set.

An example Decision API request with consent set to true:

{
  "consent": {
    "gdpr": true
  },
  "placements": [
    {
      "divName": "div1",
      "networkId": 1234,
      "adId": 12345,
      "siteId": 12345,
      "adTypes": [
        5
      ]
    }
  ]
}

Frequency capping and RTB user matching will not work for EU users unless consent is set. See below for details.

Setting Consent on the Ad Request - Ados.js

To set GDPR consent on an ados.js JavaScript ad request, add the following line to your requests:

ados_setConsent({gdpr: true});

Note that GDPR consent will default to false unless it is explicitly set.

An example of JavaScript ad tags with consent set to true:

<script type="text/javascript">
2    var ados = ados || {};
3    ados.run = ados.run || [];
4    ados.run.push(function() {
5      ados_add_placement(1234, 123456, "azk829044", 5);
6      ados_setConsent({gdpr: true});
7      ados_load();
8    });

Frequency capping and RTB user matching will not work for EU users unless consent is set. See below for details.

Setting Consent on UserDB

If consent is not set on the user record OR the request, and the request originates from the EU, then no data from the user record can be used for ad targeting.

You can set GDPR consent for a specific user in UserDB with the GDPR Consent Endpoint. The consent status will be honored anytime the UserKey is used in a request.

Setting Additional Consent and Regulatory Parameters

In addition to the gdpr parameter, there are optional parameters in the consent object that will set consent within Adzerk, declare a user subject to GDPR or pass consent to downstream providers. The parameters are available for both the Decision API and ados.js.

Parameter
Type
Description
Example

gdprConsentString

string

Passes a user's consent to downstream providers via an IAB consent string. Does not pass Adzerk consent, which must be passed via the gdpr parameter OR when an allowed gdprVendorId is passed and the user specifies ad selection consent (purpose number 3) in the consent string.

gdprConsentString will be passed to downstream providers regardless of whether the request's IP address originates from the EU.

"ALONGSTRINGGOESHERE"

gdprConsentRequired

boolean

Requests with gdprConsentRequired set to true treat the user as requiring GDPR consent, even if the request or UserDB record doesn't use an EU IP address. Likewise, setting to false identifies the user as being outside of the EU and not subject to GDPR.

true

gdprVendorId

integer

A vendor ID that is used to compute the boolean gdpr consent from a consent string in gdprConsentString
(if one is provided). The vendor ID is from the IAB vendor
list
. Consent will only be calculated if the vendor ID is allowed and the user specifies ad selection consent (purpose number 3) in the consent string.

1234

You can also set an IAB consent string via RTB advertiser settings.

Note that consent strings passed in via the request will take precedence over consent strings passed via RTB advertiser settings.

The requests below are examples of the additional consent strings being used to set regulations and derive GDPR consent:

gdprConsentRequired is true, which indicates that the user is subject to GDPR regulation and therefore consent defaults to false. However, the request passes the user's gdprConsentString and the applicable gdprVendorId, and the consent string contains ad serving consent for that allowed vendor ID. Adzerk will calculate GDPR consent to true.

## Decision API

{
  "consent": {
    "gdprConsentRequired": true,
    "gdprConsentString": "EXAMPLESTRING",
    "gdprVendorId":1234
  },
  "placements": [
    {
      "divName": "div1",
      "networkId": 1234,
      "adId": 12345,
      "siteId": 12345,
      "adTypes": [
        5
      ]
    }
  ]
}


## ados.js

<script type="text/javascript">
2    var ados = ados || {};
3    ados.run = ados.run || [];
4    ados.run.push(function() {
5      ados_add_placement(1234, 123456, "azk829044", 5);
6      ados_setConsent({gdprConsentRequired: true,gdprConsentString: "EXAMPLESTRING","gdprVendorId":1234});
7      ados_load();
8    });

Consent Setting Hierarchy

Adzerk calculates a user's GDPR consent based on the method that sets consent, where certain ways of passing consent will take precedence over others. In the table below, a higher ranked method will override any consent settings beneath it.

Rank
Method
Notes

1

"consent":{"gdprConsentRequired":true} or "consent":{"gdprConsentRequired":false} on the request

While gdprConsentRequired does not pass user consent itself, its settings will effect the user's consent status. For example, if gdprConsentRequired is set to false, a user that has not set consent will have effectively consented (since the request is considered out of GDPR jurisdiction).

2

"consent":{"gdpr": true} or "consent":{"gdpr": false} on the request

Consent/non-consent that takes place at request time takes precedence over consent that has occurred earlier (such as in the IAB consent string or on the UserDB record).

3

"consent":{"gdprVendorId":1234, "gdprConsentString": "...."} on the request

Note that the allowed vendor ID must be present in the consent string, and that user must have specified ad selection consent (purpose number 3) in the consent string.

4

Consent via the user's UserDB record

5

No consent passed

If the request is subject to GDPR regulation (via the IP address of the request or via gdprConsentRequired set to true), consent defaults to false. Otherwise, it defaults to true.

Right to Be Forgotten with UserDB

The Forget User Endpoint goes further than the User Opt-Out Endpoint by removing a UserDB record entirely and unsetting the azk cookie that contains the UserKey. It provides users tracked by Adzerk customers with the right to be forgotten.

Frequency Capping and GDPR Non-Consent Requests

If:

  • A request is subject to GDPR regulation AND
  • The user has not consented to tracking AND
  • The ad selected by the decision engine is frequency capped

Then one of two ad serving behaviors will take place:

  • Strict Frequency Capping: The ad will not be shown to the user. No cookies will be set in the user's browser.
  • Lenient Frequency Capping: The ad will be shown to the user, but it will not be frequency capped. No cookies will be set in the user's browser.

Whether the decision engine uses strict or lenient frequency capping is set per network. Contact Adzerk support for more details about your network.

Treating All Traffic as GDPR-Regulated

You can optionally treat all Adzerk requests as GDPR-regulated regardless of the IP address from the request or user record. Users will then need to pass consent as if they were located in the EU.

Note that the All Traffic as GDPR-Regulated feature:

  • Does not affect how the location of Adzerk requests is processed in ad serving or reporting. Impressions, clicks etc. will still be recorded as originating from the country resolved from the IP address, and geotargeting will not be affected.
  • Does not set or change GDPR consent. Consent still must be obtained via the request, user record, or consent string.

To enable this feature, you must first contact your Adzerk account manager.

Writing IP Addresses to Data Shipping When GDPR Doesn't Apply

By default, IP addresses associated with Adzerk requests are not logged to data shipping regardless of whether the request originated in a GDPR-regulated area. With the IP logging feature, you can log IP addresses to data shipping when they do not originate in areas where GDPR applies.

Note that when the feature is on, you still cannot log the IP addresses of GDPR-regulated requests, regardless of whether consent is passed.

IP addresses will only be logged to data shipping if all of the following are true:

  • The IP logging feature is enabled
  • The IP address associated with the user record or request is not from a GDPR-regulated area
  • The "All Traffic as GDPR-Regulated" feature is disabled

To enable this feature, you must first contact your Adzerk account manager.

GDPR Compliance and Consent Settings


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.