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 content body
  • the creative ClickUrl
  • the creative metadata

Kevel 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.





URLencodes the output of the macro

{{url | url_encode}}


JSON encodes the output of the macro

{{user.interests | json_encode}}

Time and Date Macros




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'll want to replace it with {{timestamp}}


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


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


Minutes (0-59)


Seconds (0-59)


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.




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


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



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.



{{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 ","}}


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


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


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


The useragent of the user the ad is being displayed to

Referrer Macros




The protocol of the referrer, such as https:


The domain of the referrer, such as


The port of the referrer, such as 9000


The combined hostname and port, such as

Decision Macros




The impression ID for this impression


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.


Whether the ad is active (boolean)


Date and time of the ad creation


The calculated eCPM of the ad


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


The campaignID of the ad


The priorityID of the ad


The advertiserID of the ad


Whether the flight of the ad is active (boolean)


The keyword targeting set on the flight


The start date of the flight


The flightID of the ad


The rate type of the flight


The goal type of the flight


The name of the flight


The value of a custom field set on a campaign


If the campaign is deleted (boolean)


If the campaign is active (boolean)


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


The channelID of the flight


The value of a custom field set on a flight


The custom targeting (Zerkel query) of the flight


If the flight is deleted (boolean)


The price of the flight


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


The end date of the flight


The behavioral targeting categories of the flight


The custom targeting (Zerkel query) on the ad level


The ID of the ad


If the ad is deleted (boolean)


The ID of the ad's creative


The adType ID of the ad's creative


The width of the ad's creative


The height of the ad's creative


The name of the creative


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


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


If the creative is active (boolean)


If the creative is deleted (boolean)


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


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


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

Creative Image Macros




The path to a creative image hosted on Kevel. Unless the static domain is overridden, this will always be Otherwise, it will be


The file name of the creative image hosted on Kevel


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


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}}/{{}} instead of {{externalUrl}}.

Creative Template Macros




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




The title of the site making the request


The siteID of the site making the request

Placement Macros




The name of the div where the ad is serving


An array of zoneIDs where the ad is served

Device Macros

Displays characteristics of the device making the ad request.




Brand (ex: Nokia)


Model (ex: N95)


In addition to Brand and Model, some devices have a marketing name (for ex: BlackBerry 8100 Pearl, Nokia 8800 Scirocco, Samsung M800 Instinct).


Operating system name


Operating system version


Full representation of the version string


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


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


Information about the device browser


Which version of the browser


Screen width in pixels


Screen height in pixels


Image's maximum viewable width in pixels


Image's maximum viewable height in pixels


Screen width in millimeters


Screen height in millimeters


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.




The city of the user


The numeric Nielsen designated market area code


The two-character country code


The full name of the country


The latitude of the IP


The longitude of the IP


The metro code, such as ZIP code


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


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.




The headline of the RTB ad.


The external image URL of the ad.


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 utilising UserDB to store user data.




Returns a string.


Returns an array.


Returns an array.


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


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.



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




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


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

Deprecated Macros

Formerly, Kevel 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:












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