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 Kevel can be used in:

Kevel macros are designated with double curly braces: {{ }}.

📘

Note

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
json_encode JSON encodes the output of the macro `{{user.interests

Time and Date Macros

Macro Description
{{timestamp}} Shortcut for {{datetime.timestamp}}. Generates a 13 digit number. It is typically used in a third-party creative as a cache buster and/or unique identifier.
{{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

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 Kevel to track the clicks of third-party creatives.
{{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}}`

Request Macros

Macro Description
`{{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 where the ad is being displayed.
{{request.userAgent}} The user agent of the user where the ad is being displayed.

Referrer Macros

Macro Description
{{referrer.protocol}} The protocol of the referrer, such as https:.
{{referrer.hostname}} The domain of the referrer, such as kevel.com.
{{referrer.port}} The port of the referrer, such as 9000.
{{referrer.host}} The combined hostname and port, such as kevel.com:9000.

Decision Macros

Macro Description
{{decision.id}} The decision ID for this placement.
{{impressionUrl}} The impression tracking pixel for the decision, i.e. i.gif.

Ad Object Macros
{{ad.isActive}} Specifies whether the ad is active (boolean).
{{ad.created}} The 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, this is 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}} Specifies whether the flight of the ad is active (boolean).
{{ad.flight.startDate}} The start date of the flight
{{ad.flight.endDate}} The end date of the flight
{{ad.flight.price}} The price of the flight
{{ad.flight.categories}} The behavioral targeting categories of the flight.
{{ad.id}} The ID of the ad.
{{ad.creative.id}} The ID of the ad's creative.
{{ad.creative.name}} The name of the creative.

Creative Image Macros

Macro Description
{{contentUrl}} The path to a creative image hosted on Kevel.
{{fileName}} The file name of the creative image hosted on Kevel.
{{externalUrl}} The full path (including file name) of a creative image hosted outside of Kevel.

Creative Template Macros

Macro Description
{{ct*VariableName*}} The value of the Variable from a creative template field.

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.os}} Operating system name.
{{device.osVersion}} Operating system version.
{{device.resolutionWidth}} The screen width in pixels.
{{device.resolutionHeight}} The screen height in pixels.

Location Macros

Geographical information about the request derived from the user's IP address.

Macro Description
{{location.city}} The city of the user.
{{location.countryCode}} The two-character country code.

RTB Macros

Any Kevel macro can be placed in an RTB creative that uses a Custom Native 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.

UserDB Macros

UserDB uses its own set of macros to supply values from the database. These macros will only work if you are utilizing UserDB to store user data.

Macro Description
{{user.custom.*myKey*}} Returns any custom properties you've created, like {{user.custom.favoritePony}}

Event Macros

The macro {{event(eventId)}} returns the URL for tracking an event. For example, the event URL could be used to track a conversion or other custom event.

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.

Updated Macros

Kevel previously used a set of macros enclosed by percentage signs (%). Since these macros are no longer supported, you should update all of your creatives with these new creatives.

Inactive Active
%url% {{url}}
%timestamp% {{timestamp}}
%siteurl% {{request.url.host}}