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!

Macros/Tokens

Overview

A macro is a variable that you can use to dynamically generate or return data wherever the macro is used.

Macros in Adzerk can be used in:

  • the creative content body
  • the creative ClickUrl
  • the creative metadata

Adzerk macros are designated with double curly braces "{{ }}".

Macros do not expand in creative previews. Most of the time the preview is unable to access data that allows it to expand, such as request data.

Macro Filters

You can additionally use macro filters to change the output of the macro. Filters are added to the macro using pipe (|) after the macro name. You can add multiple filters to one macro.

Filter
Description
Example

url_encode

URLencodes the output of the macro

{{url | url_encode}}

json_encode

JSON encodes the output of the macro

{{user.interests | json_encode}}

Time and Date Macros

Macro
Description

{{timestamp}}

Shortcut for {{datetime.timestamp}}. Generates a random 18 digit number. It is typically used in a third-party creative as a cache buster and/or unique identifier. If your third-party ad code has a placeholder like [timestamp], you'll want to replace it with {{timestamp}}

{{datetime.dayofweek}}

The current day of the week as a numeric index (starting with Sunday, range is 1-7)

{{datetime.hour}}

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

{{datetime.minute}}

Minutes (0-59)

{{datetime.seconds}}

Seconds (0-59)

{{datetime.timestamp}}

Number of seconds since the Unix Epoch (same as {{timestamp}})

ClickURL Macros

For a full explanation of how these macros should be used in ad trafficking, refer to the 3rd-Party Click Tracking article.

Macro
Description

{{url}}

Returns the click URL for an HTML/JavaScript creative. If you have multiple landing pages it will return a random one. This macro enables Adzerk to track the clicks of third-party creatives. It's usually added to the end of a URL in the form of click={{url}}. If you need to append the click URL to another URL, or use it as a URL parameter, use {{url|url_encode}}

{{urls[1]}}, {{urls[2]}}, {{urls[n]}}...

For use with multiple click URLs in the same creative. {{urls[1]}} corresponds to the first click URL, {{urls[2]}} corresponds to the second, and so forth

{{url|url_encode}}

Returns a click URL like {{url}}, but encodes all non-standard characters. Use {{url|url_encode}} if you need to append the click URL to another URL, or if you need to use the click URL as a parameter

Request Macros

Note

The {{request}} macros will only display a URL if the referrer header is accessible. Therefore, if you are serving a creative via a Decision API request, the referrer property should be passed in with the request.

Macro
Description

{{request.keywords|join ","}}

Returns a comma separated list of keywords from an ad call. You can set keywords for your ad calls and pass them into the creative. That way, if a third-party creative requires keyword targeting, you can provide it. This macro is commonly added to the end of a URL in the form of keywords={{request.keywords|join ","}}

{{request.url.host}}

Generates the base domain of the site where the ad was served

{{request.url.href}}

The absolute URL of the page on which an ad is displayed

{{request.ip}}

The IP address of the user the ad is being displayed to

{{request.userAgent}}

The useragent of the user the ad is being displayed to

Referrer Macros

Macro
Description

{{referrer.protocol}}

The protocol of the referrer, such as https:

{{referrer.hostname}}

The domain of the referrer, such as adzerk.com

{{referrer.port}}

The port of the referrer, such as 9000

{{referrer.host}}

The combined hostname and port, such as adzerk.com:9000

Decision Macros

Macro
Description

{{decision.id}}

The impression ID for this impression

{{impressionUrl}}

The impression tracking pixel for the decision, i.e. i.gif

Ad Object Macros

These macros pull data from the ad, or Creative Flight Map.

{{ad.isActive}}

Whether the ad is active (boolean)

{{ad.created}}

Date and time of the ad creation

{{ad.ecpm}}

The calculated eCPM of the ad

{{ad.goals.impression}}

If the ad is in an impression goal flight, the total impression goal

{{ad.flight.campaignId}}

The campaignID of the ad

{{ad.flight.priorityId}}

The priorityID of the ad

{{ad.flight.advertiserId}}

The advertiserID of the ad

{{ad.flight.isActive}}

Whether the flight of the ad is active (boolean)

{{ad.flight.keywordTargeting.include}}

The keyword targeting set on the flight

{{ad.flight.startDate}}

The start date of the flight

{{ad.flight.id}}

The flightID of the ad

{{ad.flight.rateType}}

The rate type of the flight

{{ad.flight.goalType}}

The goal type of the flight

{{ad.flight.name}}

The name of the flight

{{ad.flight.campaign.customFields.*nameOfCustomField*}}

The value of a custom field set on a campaign

{{ad.flight.campaign.isDeleted}}

If the campaign is deleted (boolean)

{{ad.flight.campaign.isActive}}

If the campaign is active (boolean)

{{ad.flight.campaign.isMediaPlan}}

If Sales Management is enabled, if the campaign is a media plan

{{ad.flight.channelId}}

The channelID of the flight

{{ad.flight.customFields.*nameOfCustomField*}}

The value of a custom field set on a flight

{{ad.flight.customTargeting}}

The custom targeting (Zerkel query) of the flight

{{ad.flight.isDeleted}}

If the flight is deleted (boolean)

{{ad.flight.price}}

The price of the flight

{{ad.flight.siteZoneTargeting.include}}

A list of site/zone targeting objects for the flight.

{{ad.flight.endDate}}

The end date of the flight

{{ad.flight.categories}}

The behavioral targeting categories of the flight

{{ad.customTargeting}}

The custom targeting (Zerkel query) on the ad level

{{ad.id}}

The ID of the ad

{{ad.isDeleted}}

If the ad is deleted (boolean)

{{ad.creative.id}}

The ID of the ad's creative

{{ad.creative.adType}}

The adType ID of the ad's creative

{{ad.creative.width}}

The width of the ad's creative

{{ad.creative.height}}

The height of the ad's creative

{{ad.creative.name}}

The name of the creative

{{ad.creative.contents[index].type}}

If the ad's contents are raw data or an image

{{ad.creative.externalImageUrl}}

The URL of the creative's image if it is hosted elsewhere

{{ad.creative.isActive}}

If the creative is active (boolean)

{{ad.creative.isDeleted}}

If the creative is deleted (boolean)

{{customData.[key]}}

Returns a value from the creative's custom JSON metadata. For example, {{customData.foo}} returns bar given "foo":"bar" on the creative

{{rawClickUrl}}

The raw URL of the creative. Will NOT track a click in reporting - instead use a ClickURL Macro

{{rawClickUrls[n]}}

Returns one of multiple raw click URLs. Will NOT track a click in reporting - instead use a ClickURL Macro

Creative Image Macros

Macro
Description

{{contentUrl}}

The path to a creative image hosted on Adzerk. Unless the static domain is overridden, this will always be https://static.adzerk.net/Advertisers. Otherwise, it will be https://CNAMEd-domain.com/Advertisers.

{{fileName}}

The file name of the creative image hosted on Adzerk

{{externalUrl}}

The full path (including file name) of a creative image hosted outside of Adzerk.

{{creativeContent.data.fileName}}

This has the same output as {{fileName}} but can be used within a creative template.

To output the full path of an hosted image in a creative template field, you should use {{contentUrl}}/{{creativeContent.data.fileName}} instead of {{externalUrl}}.

Creative Template Macros

Macro
Description

{{ct*VariableName*}}

The value of the Variable from a creative template field. This is set when creating a creative that uses a creative template.

Site Object Macros

Macro
Description

{{site.title}}

The title of the site making the request

{{site.id}}

The siteID of the site making the request

Placement Macros

Macro
Description

{{placement.divName}}

The name of the div where the ad is serving

{{placement.zoneIds}}

An array of zoneIDs where the ad is served

Device Macros

Displays characteristics of the device making the ad request.

Macro
Description

{{device.brandName}}

Brand (ex: Nokia)

{{device.modelName}}

Model (ex: N95)

{{device.marketingName}}

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}}

Operating system name

{{device.osVersion}}

Operating system version

{{device.osVersion.string}}

Full representation of the version string

{{device.osVersion.major}}

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

{{device.osVersion.minor}}

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

{{device.browser}}

Information about the device browser

{{device.browserVersion}}

Which version of the browser

{{device.resolutionWidth}}

Screen width in pixels

{{device.resolutionHeight}}

Screen height in pixels

{{device.maxImageWidth}}

Image's maximum viewable width in pixels

{{device.maxImageHeight}}

Image's maximum viewable height in pixels

{{device.physicalScreenWidth}}

Screen width in millimeters

{{device.physicalScreenHeight}}

Screen height in millimeters

{{device.formFactor}}

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

Location Macros

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

Macro
Description

{{location.city}}

The city of the user

{{location.dmaCode}}

The numeric Nielsen designated market area code

{{location.countryCode}}

The two-character country code

{{location.countryName}}

The full name of the country

{{location.latitude}}

The latitude of the IP

{{location.longitude}}

The longitude of the IP

{{location.metroCode}}

The metro code, such as ZIP code

{{location.region}}

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

{{datacenter}}

Boolean. If the request originates from a TAG known datacenter, returns true.

RTB Macros

Any Adzerk macro can be placed in an RTB creative that uses a Custom Native Template. There are also RTB-specific macros that will display content from the RTB provider inside the template.

Macro
Description

{{title}}

The headline of the RTB ad.

{{externalUrl}}

The external image URL of the ad.

{{rtb.nurl}}

The notification URL for the RTB ad. When hit, it completes the auction so revenue is recorded for the winning bidder.

UserDB Macros

UserDB uses its own set of macros to supply values from the database. These macros will only work if you have the UserDB extension installed in your Adzerk account.

Macro
Description

{{user.key}}

Returns a string.

{{user.interests}}

Returns an array.

{{user.retargetingSegments}}

Returns an array.

{{user.partners}}

Returns an array of partner IDs if you are using user matching.

{{user.custom.*myKey*}

Returns any custom properties you've created, like {{user.custom.favoritePony}}

ContentDB Macros

ContentDB macros allow you to dynamically include data from ContentDB records in ad copy. Learn more here.

Macro
Description

{{content.custom.[schema name].[the JSON object key of the contentkey]

Returns what's being requested from ContentDB

User Agent Macros

The macro {{userAgent}} passes the user agent provided with the ad request. For more information, refer to the custom targeting documentation for Reserved Keys.

Properties Macros

The macro {{properties.nameOfKey}} returns the value of a custom property from the ad request.

For example, if you pass the key/value pair "weather":"sunny" in the request, the macro {{properties.weather}} will return "sunny". For more information, see our Custom Targeting article.

Event Macros

The macro {{event(eventId)}} returns the URL for tracking an event. For example, the event URL could be passed in on the click URL and later used to track a conversion or other custom event. For more information, see our Event Tracking article.

Regulatory Macros

The regulatory macros return true or false depending on whether the request is subject to certain regulations.

Macro
Description

{{regs.gdpr}}

Returns true if the request is subject to GDPR regulation, i.e. it originates from an EU IP address. Otherwise returns false.

{{consent.gdpr}}

Returns true if the request has passed GDPR consent. Otherwise returns false.

Deprecated Macros

Formerly, Adzerk used a set of macros enclosed by percentage signs (%). Those macros are now deprecated, but they are still available to use for backward compatibility. However, we highly recommend that you update all creatives that use the deprecated macros, as they are no longer supported.

Use this table to convert your deprecated macros into active ones:

Old
New

%url%

{{url}}

%urlenc%

{{url|url_encode}}

%dfaurl%

{{url|add("&url=%u")}}

%timestamp%

{{timestamp}}

%keywords%

{{request.keywords|join ","}}

%siteurl%

{{request.url.host}}

%sitefullurl%

{{request.url.href}}

%siteid%

{{site.id}}

%sitetitle%

{{site.title}}

%zoneid%

{{placement.zoneIds[0]}}

%advertiserid%

{{ad.flight.advertiserId}}

Macros/Tokens


Suggested Edits are limited on API Reference Pages

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