What are ad tag macros?
Ad tag macros are special parameters that can be added to an ad tag URL that will send dynamic data back to your ad partners (ad servers and SSPs). Typically ad partners use this data to optimize fill against ad requests, as well as to store data about the individual user or device the ad is being served to.
Depending on the macro being used, Zype will send corresponding data about the content (e.g., video title or description), where the content is being served (e.g., the website URL the player is on, or the player height and width), and so on.
Read on below to get more info about the macros supported by Zype, as well as some basic instructions for how to configure these. For each macro, we've provided suggestions on typical use case best practices, but you can of course use these however you see fit according to your ad partners.
What ad tag macros does Zype support?
You can use the following macros in your ad tag. We will send their respective values back to your ad partner when the player is rendered as part of the ad request.
Please note that you must include the brackets in the ad tag URL, and generally should separate each macro using an ampersand "&" character. We've included a sample ad tag URL with macros included for reference below.
Macros supported on all devices:
|[id] ID of the video||X||X||X|
|[title] Title of video||X||X||X|
|[description] Description of video||X||X||X|
|[keywords] Comma separated list of video’s keywords||X||X||X|
|[episode] Episode number of the video if available||X||X||X|
|[season] Season number of the video if available||X||X||X|
|[duration] duration of the video||X||X||X|
|[autoplay] 0 if Autoplay is off, 1 if Autoplay is on||X||X||X|
|[random] A randomly generated string. Useful for cachebusters||X||X||X|
|[user_agent] User agent string||X||X||X|
|[position] Indicates if the position of the ad request is being sent from pre-roll, mid-roll, or post-roll||X||X||X|
|[custom_attributes] Sends URL-encoded key value pair 'Name' and 'Value' metadata added to individual videos within the 'Custom Attributes' metadata field in the following format: <name>=<value>. If a video has multiple sets of Name and Value key value pairs, each set will be separated by a URL-encoded ampersand symbol as follows: <name1>=<value1>&<name2>=<value2>. Used when you are pairing specific ad creatives/campaigns to keyword values. Read more here.||X||X||X|
|[custom_attributes.key] Sends URL-encoded 'Value' metadata for a video matching the key specified in the macro within the 'Custom Attributes' metadata field. For example, if you have a custom attribute Name of "Promo" with example Value "FallCampaign" then you would configure your macro as follows: [custom_attributes.Promo] which would be replaced with "FallCampaign" for that specific video during ad requests.||X||X||X|
|[url] URL-encoded value of the URL where the player is being rendered||X|
|[non_encoded_url] Non-encoded URL of the page the video player is embedded on||X|
|[domain_url] The URL-encoded value of the domain where the player is being rendered. E.g., https://example.com/page/123 would return 'example.com'.||X|
|[player_width] Width, in pixels, of the player in which the ad is played||X||X|
|[player_height] Height, in pixels, of the player in which the ad is played||X||X|
|[player_dimensions] The width and height of the player, in pixels, returned as WIDTHxHEIGHT||X||X|
|[ip_address] The IP address of the consumer who generated the ad request.||X||X||X|
|[uuid] Unique identifier for each user and/or device||X||X|
|[app_name] Name of the app where ads are being played. Example: Zype Template||X|
|[app_bundle] App bundle ID value. Example: com.exampleapp.example||X|
|[app_domain] Domain of an app. Example: myapp.foo.com||X|
|[device_make] Manufacturer of a device. Example: Apple||X|
|[device_ifa] Device identifier in the value format required by IAB IFA (e.g. 8-4-4-4-1)
used for advertising. Examples: Apple IDFA, Google Advertising ID, or Roku RIDA
|[device_model] Model of a device. Example: AppleTV||X|
|[app_id] App ID as often provided by marketplaces. Example: If a standardized App ID is available on the device, such as a ROKU_ADS_APP_ID||X|
Keep in mind that Zype's naming convention for macros may not always match up to the naming convention used by your ad server. Not to worry! Just remember to find the macro whose value matches up with the value being requested by your ad server, and the data should be sufficient.
For example, if your ad server wants the URL of the webpage the player is embedded on, but they want you to use the parameter "content_url" you can still use Zype's [url] macro to send back the page URL value.
What does an example ad tag URL look with macros included?
If we deconstruct the URL above, you can see that the ad partner is asking us to send back the following values, and we're doing so using the Zype tag macros:
- name: the ad partner is asking for the name of the video for which we're requesting an ad, so we're sending this back using the [title] macro, which sends back the video title you've entered in the dashboard
- page_url: the ad partner wants the URL of the webpage the video player is embedded on, so we're sending this back using the [url] macro, which dynamically grabs the page URL using the web player
- duration: the ad partner wants the duration of the video, so we're sending this back using the [duration] macro which will send back the total duration of the video
- cachebuster: often you'll see an ad server ask for a "cachebuster" or some other random string value to include in your ad macros; here we've filled that value using the [random] macro value
What if I don't see a macro on this list that's required by my ad server?
We're always on the look out to support more types of ad macros. While we may not be able to add every specialized macro that exists, we're happy to receive your request for consideration.
If you see a macro missing from this list that's required by your ad server, please reach out to email@example.com with the following information: the name of your ad partner, details about the macro you need, and which endpoints (e.g., web, Roku, Apple TV, etc.) that this macro is needed for.