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:
- the creative template fields
- the creative content body
- the creative ClickUrl
- the creative metadata
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 | 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 13 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 will 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 Kevel 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 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
These macros pull data from the ad, or Creative Flight Map.
{{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.advertiser.customFields.*nameOfCustomField*}} | The value of a custom field set on an advertiser. |
{{ad.flight.isActive}} | Specifies 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.name}} | The name of the campaign. |
{{ad.flight.campaign.customFields.*nameOfCustomField*}} | The value of a custom field set on a campaign. |
{{ad.flight.campaign.isDeleted}} | Specifies if the campaign has been deleted (boolean). |
{{ad.flight.campaign.isActive}} | Specifies if the campaign is active (boolean). |
{{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}} | Specifies if the flight is deleted (boolean). |
{{ad.flight.price}} | The price of the flight. |
{{ad.flight.siteZoneTargeting.include|json_encode}} | 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}} | Specifies 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}} | Specifies 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}} | Specifies if the creative is active (boolean). |
{{ad.creative.isDeleted}} | Specifies 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 Kevel. Unless the static domain is overridden, this will always be https://s.zkcdn.net/Advertisers; otherwise, it will be https://CNAMEd-domain.com/Advertisers. |
{{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. |
{{creativeContent.data.fileName}} | This has the same output as {{fileName}} but can be used within a creative template. |
Caution
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}} | Specifies which version of the browser is being used. |
{{device.resolutionWidth}} | The screen width in pixels. |
{{device.resolutionHeight}} | The screen height in pixels. |
{{device.maxImageWidth}} | The image's maximum viewable width, in pixels. |
{{device.maxImageHeight}} | The image's maximum viewable height, in pixels. |
{{device.physicalScreenWidth}} | The screen width, in millimeters. |
{{device.physicalScreenHeight}} | The screen height, in millimeters. |
{{device.formFactor}} | Specifies the form factor of the device. This can be 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 Kevel 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 are utilizing UserDB to store user data.
| 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 is 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. |
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.
Use this table to convert these inactive macros into active ones:
| Inactive | Active |
|---|---|
%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}} |
Updated about 2 months ago