Salesforce

« Go Back
Information
Macros
Macros
Details

Overview

Equativ’s macros are pieces of code which are replaced by actual values. For instance, the macro [sas_insertionId] is replaced by the actual insertion Id (e. g. 1234567) .

Macros in the UI

Macros can be used:
  • in the script template editor (menu: Administration > Templates library)
  • in the customized script for the creative (more details in Configuring creatives)
  • in the customized script for the insertion (more details in Configuring creatives​)

Templating processor

  • the templating processor uses the DotLiquid templating engine
  • instructions referencing data must use the model prefix {{ model.CamelCaseProperty }}
  • use the {{ model.Doc }} macro to access all available fields
  • when starting to write a JS script template, add /* {{model.Doc}} */ at the top of your template; this allows you to see the documentation when running tests

Macro types

Macros fall into two groups:
  • manage macros - replaced by data originating from Equativ’s UI (“manage”)
  • ad call based macros - replaced by data originating from the ad call (data passed in the ad request URL, json message, header etc.)

Manage macros

  • are replaced by data originating from Equativ’s UI (“manage”)
  • values for these macros are known independently from ad calls (ad delivery)
  • example: the macro [sas_insertionId] will be replaced by the Id of the insertion where the macro is used

Insertion macros

MacroDescription
[sas_advertiserId]Id of the advertiser
[sas_insertionId]Id of the insertion
[sas_campaignId]Id of the campaign
[sas_externalId]external Id of the insertion
[sas_customisedScriptCode]stringified customised script code entered in the insertion
[sas_customisedScriptJSON]version of the script code that can be used in JSON
[sas_formatId]Id of the format
[sas_tagId]represents the DOM tag id where the ad will be rendered;
by default, tagId is specified as: sas_<format id> or sas_<insertion id> if the format Id is zero;
in Equativ’s agency solution, the format id is always zero;
more about tagId in the Tagging guide
[sas_networkId]Id of the network (account at Equativ)
[sas_templateId]Id of the script template
[sas_cpm]CPM of the insertion; specified in the network’s currency or in the overridden currency if a different currency is specified in the ad call


Creative macros

About macro indexing
Creative macros can be indexed (e. g. ([sas_creativeId_#1] or {{ model.Creatives.1.Id }}). When indexed, the macros will be replaced when you put the insertion online. Non-indexed creative macros (e. g. [sas_creativeId]) are replaced upon delivery of the insertion.
Equativ provides Creative Rotation modes (for instance, you can assign weights to creatives so that they are delivered based on the assigned weights). Creative rotation modes work with script templates with non-indexed creative macros only. As soon as a script template uses indexed creative macros, the creative rotation mode options disappear.
 
MacroDescription
[sas_creativeType]base of the CreativeFormatImage field
  • 0 - type script
  • 1 - image
  • 2 - mp4
  • 3 - deprecated
  • 4 - HTML5
[sas_creativeId]creative Id
[sas_creativeUrl]URL of the creative (Equativ CDN URL)
[sas_creativeBaseUrl]base domain of the URL of the creative (Equativ CDN)
[sas_creativeName]the creative's name, as specified in the "Name" field of the creative in EMP
[sas_creativeFileName]file name of the creative
[sas_creativeOriginalClickUrl]original click URL (landing page) of the creative (as specified in the Equativ UI); related to [sas_creativeClickUrl], which is replaced by a Equativ URL which redirects to this original click URL
[sas_creativeClickTarget]click target or _blank if empty
[sas_creativeHeight]height of the creative
[sas_creativeWidth]width of the creative
[sas_creativeMimeType]creative MIME-type
[sas_creativeScriptCode]creative’s code or ‘’ if empty
[sas_creativeScriptJSON]creative code escaped for JSON
[sas_creativeHtmlDocument]used to inject DSP markup inside a valid HTML document; ensure that the creative markup is embedded into a valid HTML document with a centered body;
the markup provided by the DSP is rendered verbatim if it ends with the string /html>
[sas_creativeHtmlDocumentJSON]JSON escaped version of [sas_creativeHtmlDocument]
[sas_trackClickUrls]returns an "all-in-one" macro that constructs an array of tracking click URLs (direct campaigns and RTB)


Video macros

MacroDescription
[sas_videoDuration]duration of the video
[sas_videoBitRate]bitrate of the video
[sas_videoplayerheight]value passed in the ad call through the vph parameter (see Video RTB+ parameters)
[sas_videoplayerwidth]value passed in the ad call through the vpw parameter (see Video RTB+ parameters)
[sas_videoIntegrationType]video integration type Ids
1 - Instream Plugins
2 - Instream Embedded Ad Manager
3 - Outstream synchronous formats (obsolete)
4 - Outstream asynchronous formats
5 - Server side ad insertion (SSAI)
[sas_videoClientTechnology]video client technology Id
1 - deprecated
2 - Javascript
3 - iOS App
4 - Android App
5 - tvOS App
6 - AndroidTV App
7 - Amazon Fire TV App
[sas_videoContentPlayer]video player Id
1 - JW Player 5
2 - JW Player 6
3 - JW Player 7
4 - Flowplayer
5 - Ooyala
6 - Kaltura
7 - Brightcove
8 - OSMF
9 - JW Player SDK
10 - Ooyala SDK
11 - Brightcove SDK
12 - AVPlayer
13 - VideoView
14 - ExoPlayer
[sas_videoRevisionNumber]revision number of player or SDK

 

Ad call based macros

MacroDescription
[sas_siteId]Id of the site passed in the ad call
[sas_pageId]Id of the page passed in the ad call or Id of the page found with the page name in the ad call
[sas_pageName]name of the page in the ad call
[timestamp] timestamp of the current ad call
[sas_cookieId]user id from the user’s pid cookie
[countgo]click counting redirect URL of 3rd party creative scripts; counts the click and redirects to the final destination URL; more details in section "Creative scripts" in the Configuring creatives article; to be replaced by [sas_creativeClickUrl] soon
[countgoEncoded]like [countgo] but URL encoded
[sas_uid]unique user Id used for frequency capping and other user related features;
the Id is
  • attached to a mobile ad call (UID, device Id) or
  • any other user Id passed via javascript ad tags using the uid parameter in sas.setup (see “Setting up the ad manager” in the Tagging guide)
[sas_target]user targeting string for the current ad call; URL encoded by default.
[sas_targetraw]Unencoded sas_target
[sas_insertionCountPixelUrl]URL of the counting pixel for selected insertion
[sas_noadImpressionPixelUrl]noad Pixel URL
[sas_creativeCountPixelUrl] URL of the counting pixel for selected creative; empty if prefetch (mobile ad prefetching) is off
[sas_creativeClickCountPixelUrl]URL of the counting pixel for clicks of the selected creative
[sas_pixelDomain]base URL of pixels; the value varies depending on the data center which issued the ad response; used to manually forge event pixels in json custom templates.
[sas_creativeClickUrl] click counting redirect URL of 3rd party creative scripts; counts the click and redirects to the final destination URL; more details in section "Creative scripts" in the Configuring creatives article; will replace  [countgo] soon
[sas_smartBaseUrl]base domain of a Equativ ad call (e. g. www5.smartadserver.com); also works with CNAMES (renders the CNAME domain if it has been registered and is showing up in the Equativ UI
[sas_latitude]latitude when available (SDK ad call only); format is culture invariant ( e. g. 48.856578).
[sas_longitude]longitude when available (SDK call only); format is culture invariant (e. g. 2.351828).
[sas_deviceId]Android Advertising Identifier (Android mobile devices and Android TV) or Apple IDFA (iOS devices and Apple TV)
[sas_bundleid]bundleId of the app
[sas_appname]name of the app
[sas_deviceIdSHA1]SHA1 hash of the unique Id
[sas_deviceIdMD5]MD5 hash of the unique Id
[sas_androidIdSHA1]SHA1 hash of the unique Id; for Android only
[sas_androidIdMD5]MD5 hash of the unique Id; for Android only
[sas_mobileVendor]vendor (manufacturer) of the phone. e.g. Samsung
[sas_mobileModel]model of the phone e.g. Galaxy GT9000
[sas_instanceCount]number of instances per format; either the one set on format level (in the UI) or the value passed in the ad call (ps= parameter); used for VAST calls only
[sas_instanceIndex]current instance index; the number of the tag instance (used when calling multiple instances of a format in a OneCall)
[sas_os]empty, ios or android
[sas_isAsyncCall]boolean indicating if the call is async or not
[sas_referrer]encoded referrer
[sas_referrerraw]unencoded [sas_referrer]
[sas_pageDomain]encoded page domain of the page where the ad tag is integrated; the page domain is extracted from the value of the pgDomain parameter in the ad call
[sas_pageDomainRaw]Unencoded [sas_pageDomain]
[sas_keywordTargeting]keyword targeting criteria
[sas_noCookie]true: user is opted out for web cookie or tracking in apps
false: user is not opted out
[sas_kw|keyword]extracts the value of the specified keyword from the keyword targeting; the keywords available are the ones returned by the [sas_keywordTargeting] macro;

example:
if [sas_keywordTargeting] returns $dt=0t;sex=male;age=40;car=mercedes;
then:
[sas_kw|age] returns 40
[sas_kw|sex] returns male
[sas_kw|$dt] returns 0t
[sas_ip]IP address of the ad call
[sas_isSecureConnection]true if the call is in https
false otherwise
[sas_protocol]https if the call is secure
http otherwise
[sas_userAgent]user-agent provided in the ad call
[sas_userAgent|urlEncoded]user-agent provided in the ad call, URL encoded
[sas_adbreak]ad break provided in the ad call
[sas_platform]Id of the platform provided in the ad call (calculated from user-agent)
1 - Desktop
2 - Smartphone
4 - Tablet
8 - Connected TV
16 - Connected Device
32 - Set Top Box
64 - Game Console
[sas_gdpr_applies]true - if gdpr=1 is passed in the ad call
false - if gdpr=0 is passed in the ad call
unknown - if the gdpr= parameter is missing in the ad call
[sas_gdpr_consent]the value of the gdpr_consent= parameter passed in the ad call
[sas_addtl_consent]the value of the addtl_consent= parameter passed in the ad call (Google Additional Consent string);
Example: 1~1.35.41.101
[sas_sib]returns 1 if the call is a Equativ in-app bidding call, 0 otherwise
[sas_sib_cpm]if the call is a Equativ in-app bidding call, returns the net paid price in network currency (or overridden currency if specified in the ad call);
0 otherwise
[sas_sib_cpm_currency]if the call is a Equativ in-app bidding call, returns the network currency (or overridden currency if specified in the ad call);
empty string otherwise

RTB+ macros

The following macros are replaced upon ad delivery and are available in RTB+ script templates only.
 
MacroDescription
[sas_rtb_advertiserIdName]advertiser Id and name, separated by a comma (",")
[sas_rtb_advertiserId]advertiser Id
[sas_rtb_campaignId]campaign Id (the field cid in the Bid object)
[sas_rtb_creativeId]creative Id (the field crid in the Bid object)
[sas_rtb_dspId]DSP Id 
[sas_rtb_dspIdName]DSP Id and name, separated by a comma (",")
[sas_rtb_buyerId]buyer Id
[sas_rtb_buyerIdName]buyer Id and name, separated by a comma (",")
[sas_rtb_dealId]deal Id
[sas_rtb_dealIdName]deal Id and deal external id separated by a comma (","); known error: instead of external deal id, the macro should be replaced by the deal name (will be fixed soon)
[sas_rtb_dealExternalId]external deal Id
[sas_rtb_clearedPricePublisherCurrency]price paid to the publisher by the DSPs
[sas_rtb_auctionId]auction Id
[sas_rtb_publisherId]publisher Id
[sas_rtb_bidLogTimeTicks]timestamp of the bid request log
[sas_rtb_environmentType]Web (desktop), Mobile Web or App
[sas_rtb_impressionHash]Hash of impression key to verify integrity and source
[sas_publisherCurrencyCode]currency defined in the network (account) at Equativ, following the ISO 4217 standard for currency codes (e. g. EUR, USD etc.)

Specific macros

MacroDescription
[sas_transactionid]used in Click ID based conversion tracking;
is replaced by a unique click ID used to correlate conversions tracked by Equativ with those tracked by third party tracking platforms;
the macro [sas_transactionid] is used as the value of the click Id parameter; the most common click id parameter names are clickid= and cid= but may be different in your specific tracking platform; the resulting key=value pair in the click URL is:  clickid=[sas_transactionid] or cid=[sas_transactionid]
Important note: this macro only works in the click URL field (when editing a creative) - for more details, read chapter "Setup in the Equativ UI" in the Click ID based conversion tracking article
 

Macro filters

Filters allow you to post-process the result of a macro in a particular way (e.g. escaping) depending on the filter applied.
The syntax to apply a filter to a macro is [macroName|filterName], where macroName is the name of the macro, and filterName is the name of the filter to apply.

Example 
!function(w, d) {
var ad = {
  imageUrl: "[sas_creativeUrl|jsonEncoded]",
  altText: "[sas_imageAltText|jsonEncoded]",
  clickUrl: "[sas_creativeClickCountPixelUrl|jsonEncoded]"
}
var tag = d.getElementById("[sas_tagId|jsonEncoded]")
var ce = function (n) { return d.createElement(n) }
var ac = function (p, c) { p.appendChild(c) }
var div = ce("div")
var a = ce("a")
a.href = ad.clickUrl
var img = ce("img")
img.alt = ad.altText
img.src = ad.imageUrl
var p = ce("p")
ac(p, d.createTextNode(ad.altText))
ac(a, img)
ac(a, p)
ac(div, a)
ac(tag, div)
}(window, document)
You can apply more than one filter to the same macro (e.g. [macro|filter1|filter2]). In this case, filters will always be evaluated from left to right.
 
Filter nameTransformation applied
urlEncodedEncodes the result using URL-encoding rules
jsonEncodedEncodes the result using JSON string escaping rules
Stacking too many filters on the same macro may have effects on the performance of template processing when ads are delivered. Ideally, do not stack more than 2 filters for the same macro.

Powered by