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:

🚧

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:

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 using the "$user" dimensions below, you must pass the key value in the user object in Ad Requests.

Examples:

$content

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

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"]`
  }

$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:

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

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.

Examples:

$reg

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

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.

To target requests from known datacenters:

$datacenter

To target requests not from known datacenters:

not $datacenter