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.

Mandatory Macro

{CONVERSION_ID} - Mandatory Macro required to track unique bid ID. This Macro is used to track your App/website events.
Example: Coversion_ID can be 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

{CAMPAIGN_NAME}, {CREATIVE_NAME} - Campaign_Name and Creative_Name that is provided by advertisers.

{CAMPAIGN_ID},{CREATIVE_ID},{ORDER_ID},{ADVERTISER_ID} - Campaign_ID, Creative_ID, Order_ID or Advertiser_ID are internally generated by Kayzen.
Example: Campaign_ID, CREATIVE_ID, Order_ID, Avdertiser_ID are numeric digits like this 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.

📱 Publisher specific Macros

{EXCHANGE_NAME},{EXCHANGE_ID} - Exchange name and Kayzen internal exchange ID.

Example: Exchange_Name can be Mopub and Exchange_ID can be 23.

{PUBLISHER_ID} - Exchange specific alphanumeric ID for publishers.
Example: Publisher_ID can be c475b45495a57e2e3a242542a98e249b.

{APP_NAME} - Publisher’s app name that is present in the bid request. (including special characters)
Example: App_Name can be "Color by Number #Coloring Book"

{APP_ID} - Exchange specific unique ID corresponding to the publisher app.
Example: App_ID can be 3b3614b0d8814fceaad20

{APP_DOMAIN} - The domain of the publisher site/app.
Example: App_Domain can be vrtcl.com

{APP_BUNDLE} - Publisher app bundle.
Example: iOS App Bundle: 234672221 and Android App Bundle: com.whatsapp

{APP_NAME_ALPHANUM} - Publisher’s app name after removing all the non-alphanumeric characters.
Example: App_Name_alphanum can be "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

{DEVICE_OS_NAME} - Operating System of the user's device.
Example: Device_OS_Name can be Android or iOS.

{MANUFACTURER_NAME} - Device Manufacturer’s Name.
Example: Manufacturer_Name can be Samsung.

{MODEL_NAME} - Device Model Name.
Example: Model_Name can be Galaxy M01.

{CARRIER_NAME} - Carrier Name of the user's network.
Example: Carrier_Name can be Vodafone.

{USER_IP} - User's IP Address for the impression or click.
Example: User_IP can be 45.51.3.76

{DEVICE_ID} - Device 15 digit IMEI number.
Example: Device_ID can be 123456789009876.

{DEVICE_RAW_ID} - OS-specific Advertising ID of the Devicein RAW format if it is available in the RAW format in the bid request.
Example: Device_Raw_ID can be 7e9547bd-3459-4ad1-870d-0c40a51f57bc

{DEVICE_SHA1_ID} - OS-specific Advertising ID of the Device in SHA1 format if it is available in the SHA1 format in the bid request.
Example: Device_SHA1_ID can be 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.
Example: Device_Platfrom_ID can be 7e4567bd-3249-4dg1-876d-0c67j78o57df.

Sample click URL: https://kayzen.com/5345r?bid_id={CONVERSION_ID}&carrier={CARRIER_NAME}&device={DEVICE_PLATFORM_ID}

🌏 Geo specific Macros

{COUNTRY_CODE} - User's Country Code as defined by ISO-3166-1 alpha 3 standard.
Example: Country_Code will be the USA ( for the United States of America).

{STATE_NAME} - User’s State name.
Example: State_Name can be California

{STATE_CODE} - State Code as defined by ISO-3166-2 standard of all countries coded in ISO 3166-1.
Example: State_Code will be US-CA (California state of the United State of America).

{CITY_NAME} - User’s City name.
Example: City_Name can be San Francisco.

{ZIP_CODE} - User’s Zipcode
Example: Zip_Code will be 94105 (San Francisco Zipcode).

{GPS_LAT}, {GPS_LON} - Latitude and Longitude coordinates of the user's device.
Example: GPS_Lat can be 52.521802 and GPS_lon can be 23.898763

Sample click URL: https://kayzen.com/5345r?bid_id={CONVERSION_ID}&country={COUNTRY_CODE}&state={STATE_NAME}&city=[CITY_NAME]


✍️ Other Macros

{TIMESTAMP} - Unix TimeStamp of the click or impression served.
Example: Timestamp will be 1,593,561,601

{DNT} - Do not track the value of a request (TRUE/FALSE).
Example: DNT will be either True or False

{CACHEBUSTER} - Random number in the URL that is used to limit caching.
Example: Cachebuster can be 3468392872

{CLICK_URL} - This macro is prefixed before the advertiser click URL. It is replaced by Kayzen Click URL.

{CLICK_URL_ESC} - This Macro is added in the advertiser click URL. It is replaced by encoded escaped Kayzen click URL.

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}

Did this answer your question?