.png){kind=logo}
ViewLift Macros
- 18 Dec 2023
- 6 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
ViewLift Macros
- Updated on 18 Dec 2023
- 6 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
About AdTag Macros in ViewLift
A macro is a predefined code that is used to insert dynamic values into a program. In the context of ads, a macro is a predefined code that is used to insert dynamic values into an ad tag. For example, the "lat" macro dynamically populates the user's latitude into the ad tag. This enables advertisers to target ads more effectively by providing them with dynamic information about the user, such as their location, device type, or other factors.
The ViewLift Player supports a number of ad macros that can be added to your VAST tag URL. The ViewLift macros are formatted as a query string that can be used to pass values to the endpoint on the frontend (ViewLift Player). When a video ad is requested on the ViewLift Player, ViewLift will pass in the macro/variable tags to the VAST tag.
For example, if you want to target ads based on the user's location, you could use the following macros:
ads.lat=37.7749
ads.lon=-122.4194
In this example, ads.lat macro is being used to insert the value 37.7749 into the ad tag. This value will be replaced with the user's latitude when the ad is served.
You can pass Viewlift macros in AdTag URLs, content URLs, and other places, such as the header of a web page or in the HTML code of a video player. In content URLs, you can pass the values via SSAI using SCTE markers. SSAI is a technique for inserting ads into video content without having to make changes to the video player. This can be useful for live broadcasts, where it is not possible to make changes to the video player.
Here's an example code block for an original m3u8 file URL before replacing macros:
"https://example-cloudfront.net/v1/master/placeholder/master_placeholder/index.m3u8?ads.iu=/placeholder/placeholder/placeholder/appletv&ads.w=VIEWLIFT_WIDTH&ads.h=VIEWLIFT_HEIGHT&ads.size=VIEWLIFT_SIZE&ads.ua=VIEWLIFT_USER_AGENT&ads.app_id=TBDv1&ads.did=VIEWLIFT_DEVICE_ID&ads.device_make=VIEWLIFT_DEVICE_MAKE&ads.pp=OTT&ads.vl_paln=VIEWLIFT_PALN&ads.vl_ppid=VIEWLIFT_PPID&ads.idtype=tvOS&ads.us_privacy=VIEWLIFT_US_PRIVACY&ads.ic=VIEWLIFT_IAB&ads.gdpr=VIEWLIFT_GDPR&ads.consent=VIEWLIFT_CONSENT&ads.lat=VIEWLIFT_LAT&ads.lon=VIEWLIFT_LON&ads.dnt=VIEWLIFT_DNT&ads.ip=VIEWLIFT_IP&ads.coppa=VIEWLIFT_COPPA&ads.ipadd=VIEWLIFT_IP"
The original URL includes placeholder values for various parameters. These placeholders are intended to be replaced dynamically when the video is played.
ViewLift AdTag macros for MRSS Feed content
Prerequisites
- You have generated an MRSS feed that contains information about your media files, including the location of the ad breaks.
- You have configured your ad-serving platform to fetch and parse the MRSS feed and set up the targeting criteria for your ads.
About MRSS Feed
An MRSS feed is a file that contains information about the media files, including the location of the ad breaks. It does not contain the actual ads themselves. The ads are served by an ad server, which is a separate system that is responsible for delivering ads to websites and other channels.
When a user plays a video that is included in an MRSS feed, the player will first request the MRSS feed from the server. The server will then return the MRSS feed, which the player will parse to get the information about the media files, including the location of the ad breaks. The player will then request the media files from the server. The server will then return the media files, and the player will play them.
If the MRSS feed includes information about ad breaks, the player will insert the ads into the video at the specified locations. The ads will be served by the ad server, which will select the appropriate ads for the user based on a variety of factors, such as the user's location, interests, and demographics.
Here's a list of ViewLift AdTag macros that you can populate dynamically to your AdTag URL.
| Supply tag query parameter | VIEWLIFT PARAM NAME | Macro description | Example macro values |
|---|---|---|---|
| w= | VIEWLIFT_WIDTH | Width of the ViewLift Player | 300 |
| h= | VIEWLIFT_HEIGHT | Height of the ViewLift Player | 250 |
| size= | VIEWLIFT_SIZE | Size of the player (SpotX only) | S Size is parsed into dimensions that are passed to demand tags. |
| domain= | VIEWLIFT_DOMAIN | Page Domain | weather.com |
| url= | VIEWLIFT_URL | Page URL | "https://weather.com/weather/radar /interactive/1/1037891:5:US" This passes the full page URL on the demand tag. |
| encoded_url= | VIEWLIFT_ENCODED_URL | Encoded page URL | "http%3A%2F%2Fwww.weather.com% 2Fweather%2Fradar %2Finteractive%2F1%2F1037891%3A5% 3AUS" |
| double_encoded_url= | VIEWLIFT_DOUBLE_ENCODED_URL | Double-encoded page URL | "http%253A%252F%252Fwww.weather.com% 252Fweather %252Fradar%252Finteractive%252F1% 252F1037891 %253A5%253AUS" |
| cb= | VIEWLIFT_CACHEBUSTER | Random number to prevent caching by the browser. | 3708662946268 |
| ts= | VIEWLIFT_TIMESTAMP | Save content with UNIX timestamp | 1589919931 |
| ts_ms= | VIEWLIFT_TIMESTAMP_MS | UNIX timestamp w/ milliseconds | 1589919931035 |
| ip= | VIEWLIFT_IP | User IP address | 52.52.52.52 IP address is used for geotargeting. SpringServe will detect if the macro is excluded from exported supply tag. |
| ua= | VIEWLIFT_USER_AGENT | User-agent string | Mozilla/5.0 (iPhone; CPU iPhone OS 6 0 like Mac OS X) AppleWebkit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10A5376e Safari/8536.25 User-agent used for device and operating system. SpringServe will detect if the macro is excluded from exported supply tag. |
| lat= | VIEWLIFT_LAT | User latitude | 33.543682 |
| lon= | VIEWLIFT_LON | User longitude | -86.779633 |
| dnt= | VIEWLIFT_DNT | Do not track | 0 or 1 dnt 1 = true and essentially means to opt-out of advertisements |
| desc= | VIEWLIFT_DESCRIPTION | Video description | IAB19 |
| ic= | VIEWLIFT_IAB | IAB Category ID of site content | IAB19 |
| dur= | VIEWLIFT_DURATION | Video duration length in seconds | 15 |
| min dur= | VIEWLIFT_MIN_DURATION | Minimum duration in seconds | 5 |
| max_dur= | VIEWLIFT_MAX_DURATION | Maximum duration | 30 |
| ap= | VIEWLIFT_AUTOPLAY | 1 if player set to autoplay, 0 if not | 0 or 1 |
| ad_pos= | VIEWLIFT_AD_POS | Position of ad | 1 Position of the ad relative to other ads on the page. ex. 1 for first, 2 for second etc. |
| mute= | VIEWLIFT_MUTE | Is player muted | 1 (muted) 0 (not muted) |
| device_make= | VIEWLIFT_DEVICE_MAKE | Device brand | Samsung, Apple |
| device_model= | VIEWLIFT_DEVICE_MODEL | Device Model | Galaxy, F8332 |
| os= | VIEWLIFT_OS | Operating System | IOS, Android, Linux, Windows, etc. |
| os_ver= | VIEWLIFT_OS_VER | Version of the Operating System | 70.0.3538.110 |
| isp= | VIEWLIFT_ISP | Internet Service Provider | comcast |
| app_bundle | VIEWLIFT_APP_BUNDLE | App bundle | 591560124, com.pic.photoeditor |
| app_name= | VIEWLIFT_APP_NAME | App name | photoeditor |
| app_store_url= | VIEWLIFT_APP_STORE_URL | App store URL | https://play.google.com/store/apps/details?id=com.pic.photoeditor&hl=en_US |
| did= | VIEWLIFT_DEVICE_ID | This macro should be replaced with the respective device ID when a user plays a stream URL on any platform. | 437825ef-a4a6-4575-8b70-81630c6d76e5 |
| kwds= | VIEWLIFT_KEYWORDS | Keywords | Comma-separated list of keywords associated with the ad request. |
| mid= | VIEWLIFT_MEDIA_ID | Media id | 1234 |
| vt= | VIEWLIFT_ENCODED_VIDEO_TITLE | Encoded video title | my%20video%20content |
| vid= | VIEWLIFT_VIDEO_ID | Unique identifier for the video content | 12345 |
| v_url | VIEWLIFT_VIDEO_URL | Encoded video url | https%3A%2F%2Fmy video content.mp4 |
| consent= | VIEWLIFT_CONSENT | A consent string passed from various Consent Management Platforms (CMP's) | TBD Mandatory for all European traffic for GDPR. |
| gdpr= | VIEWLIFT_GDPR | A flag for European Union traffic consenting to advertise | 1 (true, consenting) or 0 (false, non-consenting) Mandatory for all European traffic for GDPR. |
| us_privacy= | VIEWLIFT_US_PRIVACY | A mandatory string for all publishers in which they must pass the privacy consent for users from California | ViewLift fills in "1YNN" value in the default case and if user opts out of Email Consent, then the value is passed as "1YYN". This setting is configured on AppleTV, IOS, Web, Android app and TV, Roku, and FireTV. Other values: "1NYN" or "1-Y-" or "1---" where the N character means No, Y= Yes, - = Not Applicable) Mandatory for all traffic from California. |
| coppa= | VIEWLIFT_COPPA | A flag indicating traffic that is subject to the Children's Online Privacy Protection Act | 1 (true) or 0 (false) This is a pass-through macro that must be set by the supply partner on the top-level supply tag. |
| brand_name= | VIEWLIFT_BRAND_NAME | Connected TV brands | Samsung, Apple TV, Vizio SpringServe will detect if the macro is excluded from exported supply tag. |
| ctv_ad_dur_ms= | VIEWLIFT_CONTENT_DURATION_MS | Used as a demand tag macro. Will multiply CREATIVE_DURATION by 1000 | This is for demand tags that require duration in milliseconds instead of seconds. |
| ctv_ad_dur= | VIEWLIFT_CONTENT_DURATION | Used as a demand tag macro. Duration of the mediafile | 0:00:07 |
| prod_max_dur= | VIEWLIFT_MAX_POD_DURATION | Used to set the maximum duration of an ad pod in seconds | 90 Optional - if blank, the default duration is 300 seconds. Could also use the UI to create custom settings. |
| ctv_ad_dur_ms= | VIEWLIFT_MAX_POD_DURATION_MS | Used as a demand tag macro. Will multiply pod_max_dur by 1000 | 90000 This is for demand tags that require duration in milliseconds instead of seconds. |
| content id= | VIEWLIFT_CONTENT_ID | ID for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | 24!vch192b7 |
| content_episode= | VIEWLIFT_CONTENT_EPISODE | Episode for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | 11 |
| content_title= | VIEWLIFT_CONTENT_TITLE | Title for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | A%20New%20Hope |
| content series= | VIEWLIFT_CONTENT_SERIES_TITLE | "Content Series" in the context of PC and SSHB bid requests pertains to the categorization of content into thematic series, and it allows advertisers to make informed decisions about which ads to display based on the type of content being consumed by users. | “The Office” (television), “Star Wars” (movie), or “Arby ‘N’ The Chief” (made for web). |
| content_season= | VIEWLIFT_CONTENT_SEASON | Content season | 5 |
| content_genre= | VIEWLIFT_CONTENT_GENRE | Genre for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | Comedy |
| app_id= | VIEWLIFT_APP_ID | App store id is a 6 or 10-digit numeric number - mainly applicable to Apple | 591560124 |
Populate macros on third-party feeds
If you are ingesting content as a third-party feed and like ViewLift to populate macros as part of feed ingestion you can also do that as follows. If you are uploading content to ViewLift directly, you can skip this step.
To create a feed with customized macros:
- Enable Macros checkbox on feed creation view.
- Check the necessary macros.
- Update Query Parameters if it does not fit the endpoint.
Users can also check and enable/disable macros for existing feeds by clicking the Check Macros button.
Notes
- You can add macros only when if the feed input is Video/Episodic.
- You cannot edit macros for the existing feed.
- Categories and tags are directly picked from video metadata added in the CMS. These can't be overridden using macros.
Was this article helpful?