## 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. | | `{{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](https://en.wikipedia.org/wiki/Unix_time) (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}}` | Returns a click URL like `{{url}}`, but encodes all non-standard characters. | ## Request Macros | 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. | | `{{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}}` | * * *