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!

Reserved Keys

Overview

Zerkel is bundled with a number of reserved keys that allow for targeting using databases and lookups integrated with Adzerk, such as MaxMind.

These reserved keys do not require key value pairs to be passed into the ad request.
zone
Reserved Keys include targeting by device, location, keywords, user, userAgent, url, referral url, site, zones, ad types, divName, language, and date/time.

Many Reserved Keys involve knowing the useragent. For Decision API requests, you'll need to grab and pass the ad viewer's useragent in the Adzerk HTTP request. Otherwise, the default will be your server - which won't help with targeting!

All key names beginning with "$" are reserved. If a request contains custom properties beginning with "$", they will be ignored.

$device

For API calls, requires the passing of useragent.

Targets based on characteristics of the device making the ad request. This is particularly useful for mobile targeting to display ads appropriate for each device.

The $device hash contains the following properties:

Zerkel Key
Type

$device.brandName
(string)

Brand (ex: Nokia)

$device.modelName
(string)

Model (ex: N95)

$device.marketingName
(string)

In addition to Brand and Model, some devices have a marketing name (for ex: BlackBerry 8100 Pearl, Nokia 8800 Scirocco, Samsung M800 Instinct).

$device.os
(string)

Operating system name

$device.osVersion
(object)

Operating system version

$device.osVersion.string
(string)

Full representation of the version string

$device.osVersion.major
(integer)

Major version number (group of digits before dot) if available. Defaults to 0 if no number represented

$device.osVersion.minor
(integer)

Minor version number (group of digits after dot) if available. Defaults to 0 if no number represented

$device.browser
(string)

Information about the device browser

$device.browserVersion
(string)

Which version of the browser

$device.resolutionWidth
(integer)

Screen width in pixels

$device.resolutionHeight
(integer)

Screen height in pixels

$device.maxImageWidth
(integer)

Image's maximum viewable width in pixels

$device.maxImageHeight
(integer)

Image's maximum viewable height in pixels

$device.physicalScreenWidth
(integer)

Screen width in millimeters

$device.physicalScreenHeight
(integer)

Screen height in millimeters

$device.formFactor
(string)

Either "desktop", "phone", or "tablet"

Due to how Apple has chosen to not reveal the device name within the User Agent string, it is not always possible to determine the specific model of an Apple device. We will determine that a device is an iPhone, but we will not always tell you the precise model, resolution, or physical screen size.

In these cases, we fallback to reporting the device as an "iPhone" with the most modest screen capabilities. In other words, we will under-report the resolution and screen size to the original iPhone capabilities.

Examples:

"iPhone 5S"
"Mozilla/5.0 (iPhone; CPU iPhone OS 7_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Mobile/11D167 [FBAN/FBIOS;FBAV/23.1.0.8.11;FBBV/6660503;FBDV/iPhone6,1;FBMD/iPhone;FBSN/iPhone OS;FBSV/7.1;FBSS/2; FBCR/AT&T;FBID/phone;FBLC/en_US;FBOP/5]"
$device.brandName = "Apple"
$device.modelName = "iPhone 5S"
$device.marketingName = ""
$device.os = "iOS"
$device.osVersion.string = "7.1"
$device.browser = "Safari"
$device.browserVersion = "7.1"
$device.resolutionWidth = 640
$device.resolutionHeight = 1136
$device.maxImageWidth = 320
$device.maxImageHeight = 480
$device.physicalScreenWidth = 50
$device.physicalScreenHeight = 89
$device.formFactor = "phone"


"iPhone 6 Plus"
"Mozilla/5.0 (iPhone; CPU iPhone OS 8_0 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12A366 Safari/600.1.4"
// NOTE: The iPhone 6 Plus cannot be detected precisely via its user agent string,
// so it is reported as an "iPhone" with much smaller resolution and screen size.
$device.brandName = "Apple"
$device.modelName = "iPhone"
$device.marketingName = ""
$device.os = "iOS"
$device.osVersion.string = "8.0"
$device.browser = "Safari"
$device.browserVersion = "8.0"
$device.resolutionWidth = 640
$device.resolutionHeight = 960
$device.maxImageWidth = 320
$device.maxImageHeight = 480
$device.physicalScreenWidth = 50
$device.physicalScreenHeight = 74
$device.formFactor = "phone"


"iPad 3"
"Mozilla/5.0 (iPad; CPU OS 5_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B176 Safari/7534.48.3"
$device.brandName = "Apple"
$device.modelName = "iPad"
$device.marketingName = ""
$device.os = "iOS"
$device.osVersion.string = "5.1"
$device.browser = "Safari"
$device.browserVersion = "5.1"
$device.resolutionWidth = 768
$device.resolutionHeight = 1024
$device.maxImageWidth = 768
$device.maxImageHeight = 1024
$device.physicalScreenWidth = 148
$device.physicalScreenHeight = 198
$device.formFactor = "tablet"


"Samsung Galaxy Tab"
"Mozilla/5.0 (Linux; U; Android 4.2.2; nl-nl; GT-P5210 Build/JDQ39) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Safari/534.30"
$device.brandName = "Samsung"
$device.modelName = "GT-P5210"
$device.marketingName = "Galaxy Tab 3 10.1"
$device.os = "Android"
$device.osVersion.string = "4.2"
$device.browser = "Android Webkit"
$device.browserVersion = ""
$device.resolutionWidth = 800
$device.resolutionHeight = 1280
$device.maxImageWidth = 320
$device.maxImageHeight = 400
$device.physicalScreenWidth = 136
$device.physicalScreenHeight = 218
$device.formFactor = "tablet"


"Amazon Kindle Fire"
"Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_3; en-us; Silk/1.0.13.81_10003810) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16 Silk-Accelerated=true"
// NOTE: This User Agent indicates a Kindle Fire in "desktop mode",
// but we can still identify it as a tablet.
$device.brandName = "Amazon"
$device.modelName = "D01400"
$device.marketingName = "Kindle Fire"
$device.os = "Android"
$device.osVersion.string = "2.3"
$device.browser = "Android Webkit"
$device.browserVersion = ""
$device.resolutionWidth = 600
$device.resolutionHeight = 1024
$device.maxImageWidth = 600
$device.maxImageHeight = 875
$device.physicalScreenWidth = 90
$device.physicalScreenHeight = 154
$device.formFactor = "tablet"


"HTC Z710 Sensation"
"Mozilla/5.0 (Linux; U; Android 4.0.3; de-ch; HTC Sensation Build/IML74K) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30"
$device.brandName = "HTC"
$device.modelName = "Z710"
$device.marketingName = "Sensation"
$device.os = "Android"
$device.osVersion.string = "4.0"
$device.browser = "Android Webkit"
$device.browserVersion = ""
$device.resolutionWidth = 540
$device.resolutionHeight = 960
$device.maxImageWidth = 360
$device.maxImageHeight = 640
$device.physicalScreenWidth = 54
$device.physicalScreenHeight = 96
$device.formFactor = "phone"

Two common $device queries are used to split traffic between desktop/tablet and phone devices.

To target desktops and tablets:

$device.formFactor = "desktop" OR $device.formFactor = "tablet"

To target mobile:

$device.formFactor = "phone"

$keywords

For API calls, requires the passing of Keywords.

With $keywords you can target by keywords passed in the request. This can be used even without setting up Keyword Targeting at the flight or ad level.

The reason for using this would be because of the advanced logic you can apply when using Custom Targeting.

For instance, the below example would not be doable with Keyword Targeting, but is with $keywords reserved key:

($keywords contains "tuna") and not ($keywords contains "dolphins")

$location

For API calls, requires the passing of ip.

Targets geographical information about the request, derived from the user's IP address. If no geographical information could be found, all properties within $location will be undefined.

The $location hash contains the following properties:

Zerkel Key
Type

$ip
(string)

Targets a user's IP address. Works best with the like operator: $ip like "74.125.*"

$location.city
(string)

City name

$location.dmaCode
(integer)

The numeric Nielsen designated market area code (US only)

$location.countryCode
(string)

The two-character country code

$location.countryName
(string)

Country name

$location.latitude
(string)

Latitude

$location.longitude
(string)

Longitude

$location.metroCode
(string)

Metro Code (US Only)

$location.postalCode
(string)

Postal Code

$location.region
(string)

The two-character code for the state, region, or province

$location.subRegion
(string)

A two or three-character code for a subregion. Certain countries only

For example, to target a flight to visitors in either Canada or Minnesota:

$location.countryCode = "CA" or ($location.countryCode = "US" and $location.region = "MN")

To prevent a flight from being served to Australia:

NOT ($location.countryName = "Australia")

or

$location.countryName <> "Australia"

Some countries use subRegions in addition to regions. These are known as "Second-level subdivisions" in the ISO 3166 standard. For example, in the countryCode "GB" (Great Britain), "BKM" (Buckinghamshire) is a second-level subdivision of "ENG" (England). Refer to the individual country you are targeting in the ISO 3166 standard docs to determine whether this country uses subRegions.

Adzerk supports targeting to both IPv4 and IPv6 addresses. However, custom targeting will only match the IP version found on the request.

For example, if you target a flight to an IPv6 address that is a translation of an IPv4 address, we will only target the ad to a request from an IPv6 address, not from the equivalent IPv4 address.

$user

Requires passing of the key value in the user object, as well as UserDB, a feature in the Business or Enterprise plan.

Zerkel Key
Type

$user.custom.[insert custom data interest]

$user.interests

$user.retargetingSegments.[insert advertiserID]

$user.blockedItems.advertisers
$user.blockedItems.campaigns
$user.blockedItems.flights
$user.blockedItems.creatives

Target to users who have blocked an advertiser, campaign, flight, or creative

Examples:

Targeting
Example

Custom Interest

$user.custom.favePony = "Twilight Sparkle"

Interest

$user.interests CONTAINS "ponies"

Retargeting

$user.retargetingSegments.b422 = 1

Blocked items

$user.blockedItems.advertisers contains 1234
$user.blockedItems.campaigns contains 1234
$user.blockedItems.flights contains 1234
$user.blockedItems.creatives contains 1234

$userAgent

For API calls, requires the passing of useragent.

Targets the user agent provided with the ad request. The $userAgent hash contains four properties:

Zerkel Key
Type

$userAgent.text
(string)

The actual text of the user agent

$userAgent.browser
(hash)

Information about the user's web browser

$userAgent.os
(hash)

Information about the user's operating system

$userAgent.device
(hash)

Information about the user's mobile device, if any

The browser and os properties are themselves hashes, with the following properties:

Property
Type

.name
(string)

The name of the browser (i.e. Chrome) or operating system (i.e. Mac OS X)

.version
(hash)

A hash containing the segments (major, minor, and patch) of the version number of the browser or OS

Targeting rules can use any or all of these properties. For example, to target people using Windows and a version of Chrome earlier than version 30:

$userAgent.os.name = "Windows" and $userAgent.browser contains "Chrome" and $userAgent.browser.version.major < 30

To just target people on a certain mobile device, for example, iPhone:

$userAgent.device.name = "iPhone"

The components of a user agent in Zerkel are represented with the following model:

{ text: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.114 Safari/537.36',
  browser:
  { name: 'Chrome',
    version:
      { major: 35,
        minor: 0,
        patch: 1916 } },
  os:
  { name: 'Mac OS X',
    version: { major: 10, minor: 9, patch: 2 } },
  device: { name: 'Other' } }

$url

For API calls, requires the sending of url in request.

Targets the URL of the page that makes an ad request. Use with contains to target a full URL or a portion of a URL.

$url contains "adzerk.com/about"

Or

$url contains "adzerk"

The $url key matches the characters within the contains string against the request URL. For example, you can target a flight to a secure URL only:

$url contains "https://adzerk.com"

Or you can match against both https://adzerk.com and http://adzerk.com by using:

$url contains "adzerk.com"

You can also use regular expressions with $url for advanced URL targeting. For example, this query will target any URL that contains foo.bar.com in the domain, including secure sites, URLs with ports, and subdomains:

$url =~ "^https?://([^/:]\.)*foo\.bar\.com([:/].*)?$"

This query will target any of three domains (foo.bar.com, micha.rules.co, micha.sucks.co):

$url =~ "^https?://([^/:]\.)*(foo\.bar\.com|micha\.rules\.co|micha\.sucks\.co)([:/].*)?$"

Learn more about using regular expressions to match URLs from the IETF and StackOverflow.

$referralUrl

For API calls, requires the sending of referrer in request.

Targets of the referrer of the URL that makes an ad request. Use with contains. This is useful for targeting the parent page if the Adzerk request is placed inside of an iframe. To target ads that originate from iframes on adzerk.com:

$referralUrl contains "adzerk.com"

The $referralUrl key uses the same matching logic as $url.

$site

For API calls, siteID is already a required field

Targets the name of the Adzerk site (not necessarily the domain that is serving the ads). This hash also contains the property id.

$site = "Adzerk"

And

$site.id = 99201

$zones

For API calls, requires the sending of zoneIDs.

Targets the Adzerk zoneId making the request. This is an array. For more info on Zones, click here.

$zones contains "8675309"

$adTypes

For API calls, requires the sending of adTypes.

Targets the ad types available on the placement making the request. This array can be used to single out a particular ad type, or to target placements that can serve one ad type but not others. Learn more about Ad Types here.

$adTypes contains "5"

$divName

For API calls, divname is already a required field.

Targets the div name (DOM identifier) of the placement making the request. This enables placement-level targeting.

$divName = "728_above_the_fold"

$acceptLanguage

For API calls, requires the sending of useragent.

Targets the language set by a user's browser (also known as "locale") to enable language targeting. Use this list of available language codes for targeting, such as:

$acceptLanguage contains "en-us"

$datetime

Nothing extra needs to be passed in API requests for $datetime targeting.

Target based on date/time information.

The $datetime key is set to the server time, and is defined in GMT. Note that the system treats "12:00 AM - 12:59 AM (or 00:00 - 00:59)" as the first hour, which is represented by "1", which is shown in the chart below.

Zerkel Key
Type

$datetime.dayofweek
(integer)

The current day of the week, numeric index (starts on Sunday, range is 1-7)

$datetime.hour
(integer)

The current hour, 24-hour format (1-24)

$datetime.minute
(integer)

Minutes (0-59)

$datetime.seconds
(integer)

Seconds (0-59)

$datetime.timestamp
(integer)

Number of seconds since the Unix Epoch

Examples:

Goal
Example

Only on Wednesdays

$datetime.dayofweek = 4

Target for one minute, 15 minutes after every hour

$datetime.minute = 15

Between 8pm and 10 PM (GMT)

$datetime.hour >= 21 and $datetime.hour <= 23

Between 8 PM and 4 AM (GMT)

($datetime.hour >= 21 and $datetime.hour <= 24) or ($datetime.hour >= 1 and $datetime.hour <= 5)

$reg

Target based on regulatory data, i.e. GDPR jurisdiction and consent.

Zerkel Key
Description

$regs.gdpr
(boolean)

Is true if the request is GDPR-regulated; i.e. from an European IP address. Is false otherwise.

$consent.gdpr
(boolean)

Is true if the request has GDPR consent. Is false otherwise.

To target EU users who have passed GDPR consent, use:

($regs.gdpr AND $consent.gdpr)

To target EU users who have not passed GDPR consent, use:

($regs.gdpr AND NOT $consent.gdpr)

To target users not subject to EU regulation, use:

not $regs.gdpr

$datacenter

Targets on whether a request originates from a TAG (Trust Accountability Group) known datacenter IP address.

Zerkel Key
Description

$datacenter
(boolean)

Is true if the request originates from a known datacenter.

To target requests from known datacenters:

$datacenter

To target requests not from known datacenters:

not $datacenter

Reserved Keys