Macros

When you're using 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, built-in tracking variables within the DSP, insert dynamic data into your URLs and ad tags. With macros, you can:

  • Send data from the DSP to your own tracking software.
  • Send data from the DSP to a third-party ad server.
  • Insert a click-tracking URL so that the DSP can track clicks in third-party ad tags.

How It Works

When you set up your ads, insert macros as part of the Destination URL, Impression Tracking URL, or ad tag markup.

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

Macro Explanation
{advertiserId} Passes the Basis customer ID # for the impression/click.
{brandId} Passes the unique ID # of the brand for the impression/click.
{brandName} Passes the name of the brand, URL encoded.
{adId} Passes the unique ID # of the ad for the impression/click.
{adLabel} Passes the name of the ad. Special/unsafe characters will be encoded.
{domain} Passes the domain name for the impression/click.
{campaignId} Passes the unique ID # of the campaign for the impression/click.
{campaignName} Passes the name of the campaign, URL encoded.
{campaignGroupId} Passes the campaign group ID.
{campaignGroupName} Passes the name of the campaign group.
{networkId} Passes the unique ID # of the exchange for the impression/click.
{pageUrl} Passes the URL of the page for the impression/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 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/click in URL-encoded form. Available only in ad tags and VAST URLs.

If passed to an ad tag in the request URL (i.e. <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 number/timestamp.
{clickMacro} Inserts the DSP's click tracking link.
{clickMacroEnc} Inserts the DSP's click tracking link in URL encoded form.
{postbackId} Note: Use auctionId instead. The auctionId macro works in all places, including postbacks for view-through conversions.  Passes a unique identifier representing the current click/impression. 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 auction/impression.
{audienceIds} Passes a comma-separated list of data segment 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 (i.e. "aboveTheFold", "belowTheFold", "Unknown").
{dimensions} Size of the ad unit as a string.
{creativeType}

The type of creative. Valid values: 

  • BANNER_IMAGE
  • BANNER_FLASH
  • AD_TAG
  • EXPANDABLE
  • VIDEO_VAST
  • HTML5    
{trafficType} Traffic type (i.e. "MOBILE_WEB", "WEB", "MOBILE_APP", etc.).
{dealId} Returns the deal ID, if any, used for winning an impression.
{paymentIdChain} Returns the Payment ID Chain, if available, as per TAG guidelines.

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 offers 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 including 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, the demographic composition of a campaign.

Was this article helpful?
0 out of 0 found this helpful