Pulse Macros
What Are Pulse Macros?
Pulse macros are placeholders and used to add information to third party tags, external tracking links, and destination URLs in the Pulse UI. Pulse macros are resolved into values when the third party tags, external tracking links, and destination URLs are added to an ad response. Many of the Pulse macros depend on the ad request itself, which means that a macro can resolve into different values for different ad requests.
The main use case of Pulse Macros is to enable the ad ops to send data from Pulse and the client-side integration to third parties without doing additional integrations. This also enables better workflows for the ad ops as it usually decreases the number of different tags in use.
Where to Use Pulse Macros?
- Tags in the 3rd party ad URL (VAST) field of a 3rd Party Ad.
- External tracking links available for each ad type. See Upload or Assign Creative for more information.
- Global external tracking links. See Global Tracking for more information.
- Destination URLs triggered when the ad is clicked. See Upload or Assign Creative for more information.
How to Use Pulse Macros?
You would like to send impression tracking events to a third party and to correlate the data to your video assets, you want to send in the ID of the asset and the duration of the asset. To achieve this, create an external impression tracking link with the ${content.id} and ${content.duration} macros:
http://funkyclip.com/track?event=imp&id=${content.id}&duration=${content.duration}
The ${content.id} and ${content.duration} macros resolve into the asset's ID and duration, respectively, when used in an ad response. If the asset's id is sunday_night_football and it's duration is 1320 seconds, the link above resolves into this link when used in an ad response:
http://funkyclip.com/track?event=imp&id=sunday_night_football&duration=1320
URL Encoding in Pulse Macros
- Letters: A through Z, and a through z
- Numbers: 0 through 9
- Other characters: - (hyphen) _ (underscore) . (dot) ~ (tilda)
- urlenc(): this function percentage encodes the value passed in.
- durlenc(): this function doubly percentage encodes the value passed in. Double encoding is used for nested URLs.
The encoding functions can be used inside any tag that you want to URL encode, for example ${urlenc(tags)} or ${urlenc(request.referrerurl)}. For example:
http://funkyclip.com/track?event=imp&ref=${urlenc(tags)}
If the content item is tagged with this tag abcdefghijklmnopqrstuvwxyzåäö (Swedish alphabet) the link above would resolve into this when used in an ad response:
http://funkyclip.com/track?event=imp&ref=abcdefghijklmnopqrstuvwxyz%C3%A5%C3%A4%C3%B6
They can also be used to encode random parts of a URL with the pattern ${urlenc(WORD)} where WORD is a set of characters, for example:
http://funkyclip.com/track?event=${urlenc(görüntüleme)}
(görüntüleme is Turkish for viewing)
The link above resolves into this when used in an ad response:
http://funkyclip.com/track?event=g%C3%B6r%C3%BCnt%C3%BCleme
For more information, see http://en.wikipedia.org/wiki/Percent-encoding.
Pulse Macro Reference
Content Macros
Content macros carry metadata about the content item. The content item is the clip or video that is being monetised. The combined monetisation of a viewing of a content item by an end-user is called an ad session.
Macro | Description |
---|---|
${content.duration} |
Content duration. Specified by the cd request parameter in an ad request to Pulse. |
${content.form} |
Content form. Specified by the cf request parameter in an ad request to Pulse. Valid content forms: short_form or long_form. |
${content.id} |
Content id is used to identify the content. Specified by the ci request parameter in an ad request to Pulse. |
${content.flags} |
Comma separated flags. Flags are used in Pulse to mark and remove monetisation from specific content items. Specified by the f request parameter in an ad request to Pulse. Valid flags: nocom, noprerolls, nomidrolls, nopostrolls, nooverlays, and noskins. |
${tags} |
Comma separated tags. Tags are used by Pulse to target monetisation. Specified by the t request parameter in an ad request to Pulse. |
${shares} | The content's category + content partner, comma separated. |
Request macros
Request macros carry general information about the ad request.
All ad requests made for a viewing of a content item by an end-user are called an ad session. All ad requests in an ad session use the same ticked id.
Macro | Description |
---|---|
${site.id} | In practice, site id is used as a client id because Pulse does not support several site ids for each account. |
${tid} |
Ticket id. All ad requests in an ad session use the same ticked id, which means that it can be regarded as the session id. |
${pid} |
Persistent id. The persistent id identifies the end-user between ad sessions. |
${devicecontainer.id} |
The ID of the device container from which the ad request is made. For example, 96307a7d-e62e-4705-9aff-9c4b0f449945. |
${devicecontainer.name} |
The name of the device container from which the ad request is made. For example, ios_phones. |
${location.city} |
The name of the city from where the ad request is made. For example: Stockholm. |
${location.country} |
The name of the country from where the ad request is made. For example: Sweden. |
${location.countryiso2} |
The ISO 3166-1 alpha-2 value of the country from where the ad request is made. Alpha-2 is a two-letter country codes. For example: SE. |
${location.countryiso3} |
The ISO 3166-1 alpha-3 name of the country from where the ad request is made. Alpha-3 is a two-letter country codes. For example: SWE. |
${request.referrerurl} | The ad requests HTTP referer: http://en.wikipedia.org/wiki/HTTP_referer. |
${request.protocol} | The protocol over which the ad request is made – HTTP or HTTPS.
It can be used to specify the protocol in 3rd party ad URLs (VAST),
destination URLs, and external tracking links. For example: http://example.com?protocol=${request.protocol} or ${request.protocol}://example.com |
${request.model} |
Device model from which the ad request is made. Specified by the m request parameter in an ad request to Pulse. |
${request.linearbreaks} |
The linear break's playback positions. A playback position is a point in time on the content timeline. Specified by the bp request parameter in the ad request to Pulse. |
${request.bitrate} |
The requested maximum bit-rate of the ad. Specified by the vbw request parameter in an ad request to Pulse. |
${request.height} |
The requested height of the ad. Specified by the vht request parameter in an ad request to Pulse. |
${request.width} |
The requested width of the ad. Specified by the vwt request parameter in an ad request to Pulse.
|
Campaign macros
Campaign macros carry information about the campaign that the ad is a part of.
Macro | Description |
---|---|
${campaign.id} | Pulse's campaign id (UUID*) for the campaign. |
${campaign.customid} |
Custom campaign id. Custom campaign id is an optional value in Pulse. |
* Universally unique identifier: http://en.wikipedia.org/wiki/Universally_unique_identifier.
Goal macros
Goal macros carry information about the goal that the ad is a part of.
Macro | Description |
---|---|
${goal.id} | Pulse's goal id (UUID*) for the goal. |
${goal.customid} |
Custom goal id. Custom goal id is an optional value in Pulse. |
${goal.name} |
Goal name. Goal name is an optional value in Pulse. |
* Universally unique identifier: http://en.wikipedia.org/wiki/Universally_unique_identifier.
Ad macros
Ad macros carry information about the ad that the end-user sees.
Macro | Desciption |
---|---|
${ad.id} | Pulse's ad id (UUID*) for the ad. |
${ad.customid} |
Custom ad id. Custom ad id is an optional value in Pulse. |
${ad.name} |
Ad name. Ad name is a required value when creating an ad in Pulse. |
${ad.sourceURL} | The precise URL from where the ad was served to the viewer. Use only in tracking links. |
* Universally unique identifier: http://en.wikipedia.org/wiki/Universally_unique_identifier.
Helper macros
Helper macros are convenience macros that try to remove friction in third party integrations.
Macro | Description |
---|---|
${random} | The ${random} macro will resolve into a random string. The ${random} macro is commonly used for cache busting. |
${timestamp} | The ${timestamp} macro will resolve into a timestamp of when the ad request was done. |
Custom macros
Macro | Description |
---|---|
${content.customparameters.ID} |
Important: do not use uppercase characters in the custom
parameter ID.
ID can be any url encoded value. The custom macro is retrieved from the request parameters: cp.ID=VALUE where ID and VALUE could be any url encoded value. |
${blocked.category.customIds} | List of client categories that should not be included in ad responses. |
${break.id} | The unique identifier for the ad break. |
Deprecated Macros
The following macros are still available, but it is not recommended to use them, because they may be unaccessible in the future.
Macro | Description |
---|---|
${request.platform} |
Platform from which the ad request is made. Specified by the pf request parameter in an ad request to Pulse. |
${request.callerversion} |
The version number of the integration from which the ad request is made. Specified by the cv request parameter in an ad request to Pulse. |
${campaign.name} |
Campaign name. Campaign name is a required value when creating a campaign in Pulse. |
${ad.formattype} | Pulse's name for the ad format. |
${ad.banner} | The link to the companion banner's assets. |
${ad.linkurl} | The landing page. |
${clickurl} | Click-through tracking link with redirect to the landing page. |
${mediafile.name} | Pulse asset id (UUID) |
${mediafile.extension} | The asset's container. |
${zone.name} | Companion banner zone name / id. |
${zone.width} | Companion banner zone width. |
${zone.height} | Companion banner zone height. |