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'sUser-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 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" |
$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 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) | 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 using the "$user" dimensions below, you must pass the
key
value in theuser
object in Ad Requests.
Zerkel Key | Type |
---|---|
$user.custom.[insert custom data interest] | Custom Properties Targeting |
$user.interests | Interest 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 |
$user.key | Target a specific user. This should only be used for testing purposes, and not to target lists of users as Custom Targeting is limited to 1000 characters. |
Examples:
Targeting | Example |
---|---|
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 |
Specific user for testing purposes | $user.key = "935e5450-fe05-42c2-b3e4-c4842f6430f3" |
$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 Key | Type |
---|---|
$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"]`
}
Targeting | Example |
---|---|
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 Key | Type |
---|---|
$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:
Property | Type |
---|---|
.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 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 milliseconds 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 known datacenter IP address - includes Microsoft, AWS, Google, and TAG (Trust Accountability Group) identified data centers.
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
Updated 6 months ago