Last Update: Dec, 2023
Overview
Macros enable advertisers to collect more information from click or impressions trackers of their campaign. For example device ID, publisher ID, country code, etc. Macros are a string of text that can be included in any code that’s processed by the Kayzen platform (third-party HTML tags, VAST tags, click-through URLs, impression pixels, etc.) and are dynamically replaced with their corresponding values.
Macros and their Description
When a Macro is implemented, it will be replaced by a value that is generated each time a bid takes place for an impression or click.
Kayzen supports Macros in the following categories
Mandatory Macro
Campaign specific Macros
Publisher specific Macros
User-specific Macros
Geo specific Macros
SKAdNetwork Macros
Other Macros
Mandatory Macro
Name | Description | Example |
{CONVERSION_ID}
| Mandatory Macro required to track unique bid ID. This Macro is used to track your App/website events. | 2167783501-152389708-822-1-3-130-jdezs-a2c0ee2d104b48a9ba102cd3abe1665c-34-143684-50257831. |
Sample click URL: https://kayzen.com/5345r?bid_id={CONVERSION_ID}
Sample impression URL: https://kayzen.com/impression/52682?bid_id={CONVERSION_ID}
💻 Campaign specific Macros
Name | Description | Example |
{CAMPAIGN_NAME} | Campaign name that is provided by advertisers during campaign setup | - |
{CREATIVE_NAME} | Creative name that is provided by advertisers during creative setup | - |
{CAMPAIGN_ID} | Internally generated by Kayzen | Numeric digits like 12389 |
{CREATIVE_ID} | Internally generated by Kayzen | Numeric digits like 12389 |
{CREATIVE_TYPE} | Internally generated by Kayzen | video, img, html, native |
{ORDER_ID} | Internally generated by Kayzen | Numeric digits like 12389 |
{ADVERTISER_ID} | Internally generated by Kayzen | Numeric digits like 12389 |
Sample click URL: https://kayzen.com/5345r?bid_id={CONVERSION_ID}&campaign={CAMPAIGN_ID}_{CAMPAIGN_NAME}&creative={CREATIVE_ID}_{CREATIVE_NAME}
Note: {CAMPAIGN} and {CREATIVE} are old Macros for {CAMPAIGN_NAME} and {CREATIVE_NAME} respectively. This will be deprecated in the near future.
The hybrid macro {CAMPAIGN_ID_CAMPAIGN_NAME} is already deprecated and should not be used.
📱 Publisher specific Macros
Name | Description | Example |
{EXCHANGE_NAME} | Name of the Exchange that was responsible to show the ad | Mopub |
{EXCHANGE_ID} | Kayzen internal exchange ID. It can be used to form {EXCHANGE_ID}_{APP_ID}, the value of which is used in whitelisting or blacklisting of publisher apps | 23 |
{PUBLISHER_ID} | Exchange specific alphanumeric ID for publishers | c475b45495a57e2e3a242542a98e249b. |
{APP_NAME} | Publisher’s app name that is present in the bid request. (including special characters) | "Color by Number #Coloring Book" |
{APP_ID} | Exchange specific unique ID corresponding to the publisher app | 3b3614b0d8814fceaad20 |
{APP_DOMAIN} | The domain of the publisher site/app | vrtcl.com |
{APP_BUNDLE} | Publisher app bundle | iOS App Bundle: 234672221 Android App Bundle: com.whatsapp |
{APP_NAME_ALPHANUM} | Publisher’s app name after removing all the non-alphanumeric characters | Color by number Coloring Book |
Sample click URL: https://kayzen.com/5345r?bid_id={CONVERSION_ID}&exc={EXCHANGE_ID}_{APP_ID}&pub={PUBLISHER_ID}
📲 User-specific Macros
Name | Description | Example |
{DEVICE_OS_NAME} | Operating System of the user's device. | Android or iOS |
{DEVICE_OS_VERSION} | Operating System Version of the user's device. | 10, 14.5 |
{DEVICE_TYPE} | User device category | phone, tablet |
{MANUFACTURER_NAME} | Device Manufacturer’s Name | Samsung |
{MODEL_NAME} | Device Model Name | Galaxy M01 |
{CARRIER_NAME} | Carrier Name of the user's network | Vodafone |
{USER_IP} | User's IP Address for the impression or click | 45.51.3.76 |
{USER_AGENT} | User Agent of the user's device. Url encoded. | Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_2%20like%20Mac%20OS%20X)%20AppleWebKit%2F605.1.15%20(KHTML%2C%20like%20Gecko)%20Mobile%2F15E148 |
{DEVICE_ID} | Device 15 digit IMEI number | 123456789009876 |
{DEVICE_RAW_ID} | OS specific Advertising ID of the device in RAW format if available in the bid request | 7e9547bd-3459-4ad1-870d-0c40a51f57bc |
{DEVICE_SHA1_ID} | OS specific Advertising ID of the Device in SHA1 format if available in the bid request | 7b23aeac50a2cc97b7e5c0afdaf1a6045080ba0f |
{DEVICE_PLATFORM_ID} | Unique OS-specific Advertising ID of the Device (For e.g, iOS it will be IOS_IDFA and for Android, it will be GAID). This Macro might fetch you the advertising ID in RAW, SHA1 or MD5 format depending on what is received in the bid request | 7e4567bd-3249-4dg1-876d-0c67j78o57df |
{IDFV} | Only available on iOS. Vendor's Identifier assigned to User on apps that can be shared across all apps under one developer. | f325g3gt-12fc-352f-c9c4-dt52f0f690c8 |
{DEVICE_LANGUAGE} | Language of the user device. | IN, US |
Sample click URL: https://kayzen.com/5345r?bid_id={CONVERSION_ID}&carrier={CARRIER_NAME}&device={DEVICE_PLATFORM_ID}
🌏 Geo specific Macros
Name | Description | Example |
{COUNTRY_CODE} | User's Country Code as defined by ISO-3166-1 alpha 3 standard | USA (for the United States of America) |
{STATE_NAME} | User’s State name | California |
{STATE_CODE} | State Code as defined by ISO-3166-2 standard of all countries coded in ISO 3166-1 | US-CA (California state of the United States of America) |
{CITY_NAME} | User’s City name | San Francisco |
{ZIP_CODE} | User’s Zipcode | 94105 (San Francisco Zipcode) |
{GPS_LAT}, {GPS_LON} | Latitude and Longitude coordinates of the user's device from Maxmind | GPS_Lat can be 52.521802 and GPS_lon can be 23.898763 |
{GPS_LAT_BID}, {GPS_LON_BID} | Latitude and Longitude coordinates of the user's device from bid request. | Format same as {GPS_LAT}, {GPS_LON} |
Sample click URL: https://kayzen.com/5345r?bid_id={CONVERSION_ID}&country={COUNTRY_CODE}&state={STATE_NAME}&city=[CITY_NAME]
SKAdNetwork Macros
Name | Description | MMP |
{SKAN_CAMPAIGN_ID} | SKAN campaign ID assigned by Kayzen | Kochava, Adjust MMP integrations |
{SKAN_NETWORK_ID} | 4468km3ulz.skadnetwork for Kayzen enterprise | Adjust |
{SKAN_ADJUST_NETWORK_TOKEN} | xylyea2j143k for Kayzen enterprise | Adjust |
✍️ Other Macros
Name | Description | Example |
{TIMESTAMP} | Unix TimeStamp of the click or impression served | 1,593,561,601 |
{DNT} | Boolean value for "Do not track" field in the bid request | True or False |
{CACHEBUSTER} | Random number in the URL that is used to limit caching | Cachebuster can be 3468392872 |
{APP_API_KEY} | Replaced by app/site object's API key. |
|
Macro to be added in your HTML code in the place of your click URL. This macro will be replaced by the Kayzen {CLICK_URL} macro followed by the click URL available in the Tracker Asset. |
| |
Macro to be added in your HTML code used as video end card in the place of your click URL. This macro will be replaced by the Kayzen companion click URL followed by the click URL available in the Tracker Asset. |
| |
{CLICK_URL} | This macro is prefixed before the advertiser click URL. It is replaced by Kayzen click URL. Soon to be deprecated, please use {HTML_CLICK_URL} | - |
{CLICK_URL_ESC} | This Macro is added in the advertiser click URL. It is replaced by encoded escaped Kayzen click URL | - |
{GDPR} | If value is "0" GDPR does not apply; If value is "1" GDPR applies. | 0, 1 |
{GDPR_CONSENT} | Encoded Transparency Consent string | COvFyGBOvFyGBAbAAAENAPCAAOAAAAAAAAAAAEEUACCKAAA.IFoEUQQgAIQwgIwQABAEAAAAOIAACAIAAAAQAIAgEAACEAAAAAgAQBAAAAAAAGBAAgAAAAAAAFAAECAAAgAAQARAEQAAAAAJAAIAAgAAAYQEAAAQmAgBC3ZAYzUw |
Sample click URL: https://kayzen.com/5345r?bid_id={CONVERSION_ID}&time={TIMESTAMP}
Note:
You can combine Macros with an underscore, for example, {EXCHANGE_ID}_{APP_ID}, this is used in the campaign for whitelisting/blacklisting of app ids.
The two Macros {CLICK_URL} and {CLICK_URL_ESC} are used only in HTML creative type to track clicks. It is recommended to use {CLICK_URL}.
HTML sample
<script src="https://tags.abc.com/myapp/creative/768x1024-dynamic-js-call.js"
data-pixelId="OMMB15"
data-ios_idfa="{DEVICE_PLATFORM_ID}"
data-cid="{CAMPAIGN_ID}"
data-app="{APP_NAME_ALPHANUM}"
data-channel="inapp"
data-DNT="{DNT}"
data-ip="{USER_IP}"
data-userAgent="361"
data-ts="{TIMESTAMP}"
data-clickUrl="{CLICK_URL}">
</script>
<img src="https://pixel-ad.abc.com/pixel/event/OMMB15?&android_gaid={DEVICE_PLATFORM_ID}&cid={CAMPAIGN}&app={APP_NAME_ALPHANUM}&channel=inapp&cv=786x1024-myapp&dnt={DNT}&ts={TIMESTAMP}" heigh="1" width="1">
<img src="https://bs.serving-sys.com/serving/adServer.bs?cn=display&c=19&mc&pli=27474997&P1uID=0&ord=[timest]&rtu=1" width="1" height="1" alt="">
Video
Implement the Macros you might need to track in the Client VAST wrapper.
Banner / Native sample
https://jackrayn.com/id467291?campaign={CAMPAIGN_NAME}&app_siteid={APP_ID}&clickid={CONVERSION_ID}&idfa={DEVICE_PLATFORM_ID}&app1={APP_NAME}&creative={CREATIVE_NAME}&exchange={EXCHANGE_NAME}&device_model={MODEL_NAME}&campaign_id={CAMPAIGN_ID}