overview
getting started
what's new
In the video advertising industry, a Macro refers to a placeholder or variable that is used within a Video Ad Serving Template (VAST) tag URL to dynamically add values such as a user's location or device type. Macros enable advertisers, publishers, and ad servers to serve more relevant and targeted ads to users.
Macros are useful because users do not need to directly update ad assets. If users need to make changes, they can update the Macro reference. For each Macro, you need to provide suggestions on how a Synamedia Iris user might use it. Note that Macros can be put to whatever use Synamedia Iris users or advertisers find most useful. Macros can be included in any code that is processed by the Ad Server during delivery: third-party VAST tags, third-party beacons, or click-through URLs.
Note: Synamedia Iris currently does not support click-through URLs.
Most of the Synamedia Iris Macros depend on the decision request itself. This means that a Macro can resolve into different values for different decision requests. The main use case of Synamedia Iris Macros is to enable users to send data from Synamedia Iris and the client-side integration to third parties without additional integrations. This also enables better workflows for the users, as it usually decreases the number of tracking tags in use.
By using Macros in VAST tag URLs or external tracking links, advertisers and publishers can deliver more personalized and relevant ads to users, which can result in higher engagement and better campaign performance. Macros also enable more efficient ad serving by eliminating the need to create and update separate VAST tag URLs for each unique user or context.
Note: Synamedia Iris Macros are formatted as capital letters within square brackets and will be filled in by the Ad Server when properly implemented in multiple places: endpoint URLs of demand tags, event pixels, and landing page URLs for creative asset demand.
The Macros must be correctly applied while setting up your third-party demand tags to send the values to your demand partners. Currently, you need to manually replace the Macros.
Synamedia Iris Macros can be used in the following:
Third-party ad URLs (VAST)
External tracking links URLs
The following steps illustrate the use of a VAST Tag URL with Macros:
This is the third-party VAST ad tag URL with the Macro replacement option (highlighted text).http://search. example.com/vast/2.00/85394?VPI=MP4&app=[replaceme]&app_domain=[replaceme]&device_ifa=[replaceme]
Synamedia Macros are then placed at each of the following placeholders, as shown below: http://search. example.com/vast/2.00/85394?VPI=MP4&app=[APPBUNDLE]&app_domain=[DOMAIN]&device_ifa=[DEVICEID]
Macros are then replaced by real values during the ad call: http://search. example.com/vast/2.00/85394?VPI=MP4&app=[com.abc.abc]&app_domain=[https://www.abc.com.my/]&device_ifa=[123e4567-e89b-12d3-a456-426614174000]
The following table describes a list of Macros supported:
Macro | Source | Description | Example |
|---|---|---|---|
ADCATEGORIES | Creative data | IAB's content categories of the creative | IAB17 |
ADOMAIN | Creative data | Advertiser domain of the creative. | cocacola.com |
ADPLAYHEAD | Decision query parameter - playPos | Media playhead position. {HH:MM:SS.mmm} | 00:30.000 |
TIMESTAMP | Hardcoded | Decision time ISO string format: YYYY-MM-DDTHH:mm:ss.sssZ | 2023-01-08T08:15:18.475Z |
CACHEBUSTING | Hardcoded | Decision time EPOCH format. | 1673165909150 |
PUBLISHERID | Hardcoded | 'Synamedia' | Synamedia |
PUBLISHERNAME | Hardcoded | 'Synamedia' | Synamedia |
BREAKMAXADS | Hardcoded | '1' | 1 |
BREAKMAXADLENGTH | Creative data | Creative duration in seconds. | |
BREAKMAXDURATION | Creative data | Creative duration in seconds. | |
BREAKMINADLENGTH | Creative data | Creative duration in seconds. | |
ADCOUNT | Hardcoded | '1' | 1 |
SESSIONID | Decision query parameter - sessionId | Session ID of the player. | |
HOUSEHOLDID | Decision query parameter - subscriberId | Household ID. | |
DEVICEMAKE | Decision Header - "x-device-vendor" | Device Make | Apple |
DEVICEID | Decision query parameter - deviceId | Advertising ID for the device. | |
DEVICEMODEL | Decision Header - "x-device-marketing-model" OR "x-device-model" | Device Model | iPhone |
DEVICEOS | Decision Header -"x-device-os" | Device OS | iOS |
DEVICEOSV | Decision Header -"x-device-os-version" | Device OS Version | 16.2 |
DEVICETYPE | Decision Header -"x-device-type" | Device Type | SmartPhone |
APPBUNDLE | VAST query parameter - appBundle | Platform-specific application identifier. | synamediaapp.com |
LENGTH | Creative metadata | Ad length in seconds | 00:00:15:00 |
LINEUP | Targeted lineups as defined in the selected line item. | Line up IDs (comma separated list) for Linear only. | lineup2, lineup3 |
LIMITADTRACKING | Decision query parameter - lat | The Limit Ad Tracking setting of a device-specific advertising ID. | |
PLAYERSIZE | Decision query parameter - playerSize | Integer width and height of the player separated by a comma. | |
DOMAIN | Decision query parameter - domain | Domain of the publisher. | |
GDPRCONSENT | Decision query parameter - gdprConsent | IAB TCF consent string | |
USERAGENT | Decision Header - "user-agent" | URL-encoded version of the user agent. | |
SUBIP | Decision Header - "X-Device-IP" or "X-Forwarded-For" | Device IP address | |
STREAMTYPE | Decision API | 'vod' or 'linear' | vod |
BREAKPOSITION | Decision query parameter - position | 'pre'/'mid'/'post' | mid |
CHANNELID | The channel's data | Channel Id. '-1' for VOD | |
CONTENTID | Decision query parameter - contentId | VOD content Id: '-1' for Linear | |
CHANNEL | The channel's data | Channel name. '-1' for VOD | |
GDPR | Tenant configuration | '0' or '1' | 1 |
REGULATIONS | Tenant configuration | 'gdpr' for gdpr-Compliant tenant. Otherwise, empty string. | gdpr |
CAMPAIGNID | Decision service | Campaign ID | campId1 |
LINEITEMID | Decision service | Line Item ID | Li1 |
CREATIVEID | Decision service | Creative ID | cre1 |
Related article:
