Macros

If you use other platforms for performance tracking or hosting, you may need to include details that won't be known until an impression is delivered. For example, an impression tracking pixel might need to identify the domain name for the impression or the ID of the ad that's being delivered.

Macros are built-in tracking variables in the DSP that insert dynamic data into your click link and ad tags. With macros, you can:

  • Send data from the DSP to your own tracking software.

  • Give each creative in your tactic a unique click link.

  • Send data from the DSP to a third-party ad server. 

When you set up your creatives, insert macros as part of the Destination URL, Impression Tracking URL, or ad tag markup. If using third-party ad tags, see Inserting Macros for Third-Party Ad Tags for more information.

When your tactic is running, the platform generates the appropriate values and inserts them into the URL or ad tag.

Macros

*only populated when GDPR is not applicable (gdprApplicable=0)
Macro Explanation

{advertiserId}

Passes the Basis customer ID # for the impression or click.

{brandId}

Passes the unique ID # of the brand for the impression or click.

{brandName}

Passes the name of the brand, URL encoded.

{adId}

Passes the unique ID # of the creative for the impression or click.

{adLabel}

Passes the name of the creative. Special and unsafe characters will be encoded.

{domain}

Passes the domain name for the impression or click.

{campaignId}

Passes the unique ID # of the tactic for the impression or click.

{campaignName}

Passes the name of the tactic, URL encoded.

{campaignGroupId}

Passes the group ID.

{campaignGroupName}

Passes the name of the group.

{networkId}

Passes the unique ID # of the exchange for the impression or click.

{pageUrl}

Passes the URL of the page for the impression or click when used in an ad tag. When used in a destination click URL or win beacon URL, it passes only the domain name to prevent the chance of generating a URL that is too long and fails to function.

Not supported in VAST events--use {pageUrlEnc} instead.

{pageUrlEnc}

Passes the URL of the page for the impression or click in URL-encoded form. Available only in ad tags and VAST URLs.

If passed to an ad tag in the request URL, that is, <script src="http://ads.springfieldmedia.com/serve/js?adid=1234&page={pageUrlEnc}">, we strongly recommend you use this version of the page URL macro. This prevents the chance of the ad failing to work correctly if the page URL contains special characters.

{carrier}

Passes the carrier of the people that click your ads. (mobile only)

{device}

Passes the device of the people that click your ads. (mobile only)

{appId}

Passes a numeric ID (for Apple) or bundle name (for Google) specific to the mobile app responsible for generating the click (mobile only.)

Example values: “383763″ (Apple) or “com.google.mygoogleapp” (Google)

{inventoryUnitReportingName}

Inserts the app bundle ID if a mobile app generated the click, or the domain name if the click came from web inventory.

{appType}

Passes a string that outputs the origin or type of application responsible for the click. (mobile only)

Example values: “APP_STORE” (Apple) or “PLAY_STORE” (Google)

{ts}

Generates a random timestamp.

{clickMacro}

Inserts the DSP's click-tracking link.

{clickMacroEnc}

Inserts the DSP's click-tracking link in URL-encoded form.

{postbackId}

Use {auctionId} instead. The {auctionId} macro works in all places, including postbacks for view-through conversions.

Passes a unique identifier representing the current impression or click. This is used to attribute conversions when postback (server to server, S2S) conversions are used. Only processed by the click server; can be passed in ad tags or click URL but isn't substituted until routed through clickserv.sitescout.com (on redirect, will be replaced with actual value).

{auctionId}

Passes a unique ID for the auction or impression.

{firstPartyAudienceIds}

 Passes a comma-separated list of first-party audience IDs that were matched for the impression. See the API documentation for details on retrieving the name of a given segment

{audienceIds}

Passes a comma-separated list of third-party audience IDs that were matched for the impression. See the API documentation for details on retrieving the name of a given segment.

{contextualIds}

Passes a comma-separated list of contextual segment IDs that were matched for the impression. See the API documentation for details on retrieving the name of a given segment.

{pagePosition}

Page position of the ad.

Examples: aboveTheFold, belowTheFold, Unknown

{dimensions}

Size of the ad unit as a string.

{creativeType}

The creative type of the ad served, such as:

  • BANNER_IMAGE: DSP-hosted image ad.
  • AD_TAG: Third-party display ad tag.
  • EXPANDABLE: Third-party display ad tag (expandable).
  • AUDIO_VAST: DSP-hosted or third-party VAST audio ad.
  • VIDEO_VAST: DSP-hosted or third-party VAST video.
  • NATIVE: DSP-hosted native ad.
  • HTML5: DSP-hosted HTML5 ad.

{creativeApiFrameworks}

Comma-separated list of the API frameworks--that is, MRAID, VPAID supported--according to the bid request, expressed using the values from the AdCOM 1.0 list API Frameworks.

{trafficType}

The traffic type.

Examples: MOBILE_WEB, WEB, MOBILE_APP

{dealId}

Returns the deal ID, if any, used for winning an impression.

{paymentIdChain}

Returns the Payment ID Chain, if available, as per TAG guidelines.

{userAgent}

The user agent header as passed by the browser.

{appStoreName}

The name of the app store.

{gdprApplicable}

or

${GDPR}

Binary; Value = 1 if GDPR is applicable, value = 0 if GDPR is not applicable.

{gdprUserConsentString}

or

${GDPR_CONSENT}

or

${GDPR_CONSENT_###}

Passes the GDPR consent string per the IAB Transparency and Consent Framework 2.0 if available.

### is any number of digits; an IAB Global Vendor List ID for the vendor the consent string is being sent to.

{us_privacy}

Passes the privacy string per the IAB CCPA Compliance Framework

{ifa}*

Unhashed mobile advertising identifier (IFA) – specifically, Google Advertising ID or iOS IDFA, when available. Could also contain other advertising identifiers in future such as Windows Advertising ID. (mobile only) The preferred macro for passing device IDs.

{hashedIfa}*

SHA1 hash of above IFA, when available. (mobile only)

{hashedAndroidId}*

SHA1 hashed Android ID, when available. (mobile only, only available on some Android impressions)

{idfa}*

Unhashed Apple IDFA, when available. (mobile only, only impressions from Apple devices)

{hashedIdfa}*

SHA1 hashed Apple IDFA, when available. (mobile only, only impressions from Apple devices)

{googleAdvertisingId}*

Unhashed Google Advertising ID, when available. (mobile only, only impressions from Android devices)

{hashedGoogleAdvertisingId}*

SH1 hashed Google Advertising ID, when available. (mobile only, only impressions from Android devices)

{sourceSiteId}

The site ID from the bid request: an exchange-specific identifier for a seller-defined bucket of inventory which may or may not correspond to an individual site or app.

{sourcePublisherId}

The publisher ID from the bid request: an exchange-specific identifier representing the seller/publisher account on that exchange, corresponding to ads.txt and sellers.json values.*

*Except for Xandr: there, {sourceSellerId} represents this, and is also known inside Xandr as Member ID. {sourcePublisherId} represents buckets of inventory defined by the seller/member, usually representing one or more companies the seller sources supply from.)

{internalUserId}

The Basis cookie ID for the user, if available.

{supplyChain}

SupplyChain string (as described on the IAB's OpenRTB SupplyChain github page) with Basis appended to the chain.

{sourceContentId} The site or app's content ID, sourced from {site,app}.content.id.
{contentLanguage} The site or app's language represented by the two-character ISO 639-1 code, sourced from {site,app}.content.language.
{contentTitle} The site or app's title, sourced from {site,app}.content.title.
{contentSeries} The site or app's series, sourced from {site,app}.content.series.
{contentGenre} The site or app's genre, sourced from {site,app}.content.genre.
{contentLivestream} Whether the site or app includes livestream content, sourced from {site,app}.content.livestream. This is serialized as "true" or "false," or as an empty string if there is no value.

Examples

Here are a few examples of how these macros can be used.

Pass key information to Google Analytics on click.

You may wish to pass certain values to Google Analytics in your click URL, which allows Google Analytics to report by these values. Other analytics software offer similar capabilities. For example:

http://www.example.com/product/6981?utm_source=basis&utm_medium=display&utm_campaign={campaignGroupId}&utm_term={campaignId}&utm_content={adId}

This allows Google Analytics to report on the details of which group, tactic, and ad caused users to visit the site.

Provide parameters to your ad server for detailed reporting analysis.

If your third-party ad server supports receiving custom parameters, you can pass interesting variables that the ad server cannot observe directly and later analyze performance in your ad server using these variables. For example:

<script src="https://ads.example.com/srv/js?crid=58106&lid=38109&avid=9582&c1={trafficType}&c2={networkId}&c3={inventoryUnitReportingName}&r={clickMacroEnc}"></script>

This example presumes that the ad server takes custom variables in the form of c1, c2, c3, etc. Passing this data would enable analysis of campaign performance by traffic type, app/bundle, etc.

Provide parameters to enable a third-party measurement service.

Some third-party measurement services (comScore mobile vCE, for example) operate by the inclusion of an impression tracking pixel with the ad. This pixel receives, as parameters, key information used to achieve measurement such as the mobile advertising ID of the user. This cannot be observed directly and must be gathered from the bid request. For example:

https://measure.example.com/imp?cgid=4912&li=29194&idfa={idfa}&gaid={googleAdvertisingId}

This example passes the user's IDFA or Google Advertising ID, if present, enabling them to report on the campaign based on their IDFA/Google Advertising ID based data--for example, demographic composition of a campaign.