Skip to main content

Using Macros in Your Ad Tags

third-party impression tracking

Overview

Macros let you pass live bidstream details, such as the device, app, page, or creative, into your ad server, tracking, and click URLs. When Jamloop serves your ad, each macro in a URL is replaced with the real value for that impression.

Use macros to:

  • Send impression and device data to your third-party measurement or verification partner.

  • Tag click-through URLs so your analytics can tell which campaign, line item, or creative drove a visit.

  • Add a cache buster so every impression pixel fires as a fresh request.

How macros work

Write each macro in uppercase inside double curly braces, for example {{CACHEBUSTER}}. Put macros only inside URLs: impression trackers, third-party pixels, and click-through URLs.

  1. Add the macro to a URL as a query-string value, for example ?device={{DEVICE_ID}}.

  2. Save the URL on your creative.

  3. At serve time, Jamloop replaces the macro with the value for that impression.

Jamloop URL-encodes most macro values for you, so they're safe to use in a query string. The exception is any macro that also has an encoded version, such as {{URL}} and {{ENCODED_URL}}, or {{CLICK_URL}} and {{CLICK_URL_ESC}}. The plain version is inserted as-is, so use the encoded version inside a query string.

Supported macros

Jamloop supports the following macros, grouped below by the data they carry.

Campaign and creative

Macro

Value

{{CAMPAIGN_KEY}}

Jamloop campaign ID, for example JL12345

{{LINE_ITEM}}

Line item ID

{{TIER_ID}}

Tier ID

{{CREATIVE_ID}}

Creative ID, for example 992379

{{CREATIVE_NAME}}

Creative name, for example ASPCA Puppy

{{HASHED_CREATIVE_ID}}

Hashed creative ID, for example 43d7785daaf6b4fc28a78d7a45504a4c

{{AD_TYPE}}

Ad or creative format

{{LENGTH}}

Video or audio length, in seconds

{{WIDTH}}

Creative width, in pixels, for example 1920

{{HEIGHT}}

Creative height, in pixels, for example 1080

{{CREATIVE_WIDTH}}

Same as {{WIDTH}}, in pixels

{{CREATIVE_HEIGHT}}

Same as {{HEIGHT}}, in pixels

{{PLACEMENT_WIDTH}}

Width of the ad slot requested, in pixels

{{PLACEMENT_HEIGHT}}

Height of the ad slot requested, in pixels

{{ADVERTISER_DOMAIN}}

Advertiser domain

{{ADVERTISER_DOMAIN_ESC}}

Advertiser domain, URL-encoded

{{CLICK_URL}}

Your click-through destination URL

{{CLICK_URL_ESC}}

Your click-through destination URL, URL-encoded

Auction and timing

Macro

Value

{{AUCTION_ID}}

Jamloop auction ID, for example b1b1501f-6bf6-43e6-8199-9b514a765848

{{BID_ID}}

Bid request ID

{{BID_TIMESTAMP}}

Time of the bid response

{{CACHEBUSTER}}

A number that changes on every serve, for example 3708662946268

{{TIMESTAMP}}

Serve time as a Unix timestamp, in seconds, for example 1589919931

{{TIMESTAMP_MS}}

Serve time as a Unix timestamp, in milliseconds, for example 1589919931035

{{UUID}}

Random value in UUID format

Device and user

Macro

Value

{{DEVICE_ID}}

Device ID, for example 437825ef-a4a6-4575-8b70-81630c6d76e5

{{DEVICE_MAKE}}

Device maker, for example Samsung

{{DEVICE_MODEL}}

Device model, for example Galaxy

{{IFA_TYPE}}

Type of device advertising ID, when available

{{DNT}}

Do Not Track flag, when available

{{IP}}

User IP address, for example 52.52.52.52

{{IP_ADDRESS_ESC}}

User IP address, URL-encoded

{{USER_AGENT}}

Browser or device user agent

{{LAT}}

User latitude, for example 33.543682

{{LON}}

User longitude, for example -86.779633

{{ZIP}}

User ZIP or postal code, for example 14526

{{SEGMENTS}}

Audience segment codes

{{US_PRIVACY}}

US Privacy (CCPA) string

App, site, and publisher

Macro

Value

{{APP_BUNDLE}}

App bundle ID, for example com.pic.photoeditor

{{APP_NAME}}

App name, for example photoeditor

{{APP_STORE_URL}}

App store page URL

{{APP_STORE_URL_ESC}}

App store page URL, URL-encoded

{{DOMAIN}}

Site domain, for example weather.com

{{DOMAIN_ESC}}

Site domain, URL-encoded

{{URL}}

Full page URL, for example http://www.weather.com/weather/radar

{{ENCODED_URL}}

Full page URL, URL-encoded, for example http%3A%2F%2Fwww.weather.com

{{DOUBLE_ENCODED_URL}}

Full page URL, URL-encoded twice

{{PUBLISHER_ID}}

Publisher ID

Additional macros

These macros work only on line items that support them. Jamloop saves them on any line item, but doesn't fill them on line items that don't support them. Ask your account team whether your line item supports them.

Macro

Value

{{ADVERTISER_ID}}, {{ADVERTISER_NAME}}

Advertiser ID and name

{{ANDROID_ID}}, {{IOS_ID}}

Android or iOS device advertising ID

{{BIDREQ}}

Bid request

{{CAMPAIGN_NAME}}

Campaign name

{{CONTEXTUAL}}

Contextual data

{{COUNTRY_CODE}}

Country code

{{DEVICE_TYPE}}

Device type

{{GDPR}}, {{COPPA}}

GDPR and COPPA compliance flags

{{INVENTORY_SOURCE}}

Inventory source

{{IP_ADDRESS_IPV6}}

User IPv6 address

{{LANGUAGE}}

Language

{{METRO_CODE}}, {{CITY_CODE}}, {{REGION}}

Metro, city, and region codes

{{SITE_ID}}, {{SITE_NAME}}

Site ID and name

{{SKAN_*}}

Apple SKAdNetwork macros

{{USER_ID_SHA1}}

SHA-1 hashed user ID

Examples

An impression tracker that reports the campaign, creative, app, and device, with a cache buster:

https://tracker.example.com/imp?cmp={{CAMPAIGN_KEY}}&cr={{CREATIVE_ID}}&app={{APP_BUNDLE}}&did={{DEVICE_ID}}&cb={{CACHEBUSTER}}

At serve time, the same URL fires as:

https://tracker.example.com/imp?cmp=JL12345&cr=992379&app=com.pic.photoeditor&did=437825ef-a4a6-4575-8b70-81630c6d76e5&cb=3708662946268

A click-through URL that tags the visit for your analytics:

https://www.example.com/landing?utm_campaign={{CAMPAIGN_KEY}}&utm_content={{CREATIVE_ID}}&utm_source={{DOMAIN_ESC}}

Troubleshooting

Error when saving a URL

Unsupported macro: try renaming

Jamloop rejects some macro names commonly used on other platforms and asks you to rename them. The table below lists each of these names and the Jamloop name to use instead. Replace the name in your URL, then save again.

Name you entered

Use this Jamloop name

{{REQUEST_ID}}

{{AUCTION_ID}}

{{IP_ADDRESS}}

{{IP}}

{{LONG}}

{{LON}}

{{PAGE}}

{{URL}}

{{USER_ID}}

{{DEVICE_ID}}

{{ZIP_CODE}}

{{ZIP}}

{{US_PRIVACY_STRING}}

{{US_PRIVACY}}

{{SEGMENT}}

{{SEGMENTS}}

{{CREATIVE_TYPE}}

{{AD_TYPE}}

{{CAMPAIGN_ID}}

{{LINE_ITEM}}

To pass the campaign ID, use {{CAMPAIGN_KEY}}.

Unknown or misformated macro

Jamloop rejects a URL with a macro name it doesn't recognize, or a macro written with single braces or square brackets. It also rejects spaces inside the braces: write {{IP}}, not {{ IP }}. Check that the macro name matches one in Supported macros exactly, including capital letters and underscores, for example {{DEVICE_ID}}. Then save again.

Jamloop doesn't support these macros, so a URL that contains any of them can't be saved: {{AUTOPLAY}}, {{DURATION}}, {{LIVERAMP_EIDS}}, {{MUTE}}, {{OPERATING_SYSTEM}}, {{PLACEMENT}}, and {{PRICEPAID}}. Remove them from the URL, then save again.

Macro not replaced

If a URL was saved but a macro still appears as-is when the ad serves, the macro is probably an additional macro that your line item doesn't support. Check with your account team.

Broken link after a macro is replaced

A full URL contains characters like & and /, which break the query string when inserted raw. Use the encoded version: {{ENCODED_URL}} instead of {{URL}}, {{CLICK_URL_ESC}} instead of {{CLICK_URL}}, {{APP_STORE_URL_ESC}} instead of {{APP_STORE_URL}}, and so on for any macro that has an encoded version.

Still stuck? Contact Jamloop support ([email protected]) with the URL you saved and the line item ID.

Did this answer your question?