Reserved Keys

Overview

Zerkel is bundled with a number of reserved keys that allow for targeting using databases and lookups integrated with Kevel, such as Kevel's Geo-IP database.

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, userDB, contentDB, userAgent, url, referral url, site, zones, ad types, divName, language, and date/time.

🚧

Caution

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

🚧

Caution

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

$device

πŸ“˜

Note

For "$device" API calls, you must pass User-Agent in the request.

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 object contains the following properties:

Zerkel KeyType
$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"
$device. deviceIdentified
(boolean)
Whether WURFL matches the user agent with a known device

🚧

Caution

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

πŸ“˜

Note

For "$keywords" API calls, you must pass Keywords in the request.

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

πŸ“˜

Note

For "$location" API calls, you must pass ip in the request.

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 object contains the following properties:

Zerkel KeyType
$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)
A two or three-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.

🚧

Caution

Kevel 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, Kevel will only target the ad to a request from an IPv6 address, not from the equivalent IPv4 address.

$user

πŸ“˜

Note

For "$user" API calls, you must pass the key value in the user object.

Zerkel KeyType
$user.custom.[insert custom data interest]Custom Properties Targeting
$user.interestsInterest Targeting
$user.retargetingSegments.[insert advertiserID]Retargeting
$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:

TargetingExample
Custom Interest$user.custom.faveFood = "milksteak"
Interest$user.interests CONTAINS "ghouls"
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

$content

ContentDB is a server-side database for storing and targeting contextual metadata. You can target data stored in ContentDB via the below key:

Zerkel KeyType
$content.custom.[Schema].[The JSON Object Key of the ContentKey]ContentDB targeting against a Schema/ContentKey

For example, for a music site with the below Schema (Song) and ContentKey Records within it, they would set up the Zerkel query as depicted below.

Schema: Song

Song 1234:
{
  "title": "Somebody To Love",
  "artist": "Queen",
  "genres": ["classic rock", "electric guitar"]`
  }

Song 4567:
{
  "title": "Why Can't This Be Love",
  "artist": "Van Halen",
  "genres": ["classic rock", "electric guitar"]`
  }
TargetingExample
Target any song with "love" in its title$content.custom.song.title contains "love"
Target only requests that have schema data$content.custom.song <> null

$userAgent

πŸ“˜

Note

For "$userAgent" API calls, you must pass useragent in the request.

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

Zerkel KeyType
$userAgent.text
(string)
The actual text of the user agent
$userAgent.browser
(object)
Information about the user's web browser
$userAgent.os
(object)
Information about the user's operating system
$userAgent.device
(object)
Information about the user's mobile device, if any

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

PropertyType
.name
(string)
The name of the browser (i.e. Chrome) or operating system (i.e. Mac OS X)
.version
(object)
An object 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.name 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

πŸ“˜

Note

For "$url" API calls, you must pass url in the request.

For Ados.js, modern browser default privacy settings may block full url path.

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://www.kevel.co/ and http://www.kevel.co/ 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

πŸ“˜

Note

For "$referralUrl" API calls, you must pass referrer in the 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 Kevel request is placed inside of an iframe. To target ads that originate from iframes on www.kevel.co:

$referralUrl contains "adzerk.com"

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

$site

πŸ“˜

Note

For "$site" API calls, siteID is already a required field

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

$site = "Adzerk"

And

$site.id = 99201

$zones

πŸ“˜

Note

For "$zones" API calls, you must pass zoneIDs in the request.

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

$zones contains 8675309

$adTypes

πŸ“˜

Note

For "$adTypes"API calls, you must pass adTypes in the request.

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 "$divName". 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

πŸ“˜

Note

For "$acceptLanguage" API calls, you must pass the "Accept-Language header" in the request`.

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

πŸ“˜

Note

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

Target based on date/time information.

🚧

Caution

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 KeyType
$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 milliseconds since the Unix Epoch

Examples:

GoalExample
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 KeyDescription
$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 known datacenter IP address - includes Microsoft, AWS, Google, and TAG (Trust Accountability Group) identified data centers.

Zerkel KeyDescription
$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