Appendix D - Pulse Macros

What Are Pulse Macros?

Pulse macros are placeholders and used to add information to third party tags and external tracking links in the Pulse UI. Pulse macros are resolved into values when the third party tags and external tracking links 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?

The Pulse macros can be used for:

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

Important: When you suspect that some macros may resolve to values which will contain characters that need to be encoded to make the URL valid, then it is recommended to use the URL encoding functionality for every macro you insert in links.
URL encoding, also known as percentage encoding, is used to encode the values of a URL's request parameters. The following characters are unreserved, and are never encoded:
  • Letters: A through Z, and a through z
  • Numbers: 0 through 9
  • Other characters: - (hyphen) _ (underscore) . (dot) ~ (tilda)
The encoding functions are:
  • 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.
${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.

Note: Although the ${random} macro is most commonly used for cache busting, we recommend to use the ${timestamp} macro instead in case you need it for cache busting in external tracking links. This is recommended because the ${random} macro may return negative numbers at times, which may result in rejecting the tracking request by the third party.
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.
Parent topic: Ooyala Pulse User Guide

Was this article helpful?

Rate this article:
AAA