The Pixalate tag and macros

The Pixalate tag (a JavaScript tag or a 1x1 pixel) sends data about each impression to Pixalate as key-value parameters in its URL query string. Each parameter has a placeholder such as [ADVERTISER_ID]. A macro is your ad server’s placeholder for a value type. When you put your ad server’s macro in place of Pixalate’s placeholder, the ad server inserts the real value each time the ad is served.

The tag supports both GET and POST requests.

Video (2 min): map your ad server’s macros and test that they expand.

Map your macros

During onboarding, your Customer Success representative gives you a macro mapping form for each ad platform you’ll use.

1. For each Pixalate parameter in the form, enter the matching macro from your ad server.
2. Submit the form to Pixalate for review.
3. When the macros are final, Pixalate generates your tags with the macros already inserted for each parameter.

The parameter reference below lists what each parameter is for and whether it’s required.

Test your macros

Before you go live, check that your macros expand to real values. These two examples use the advertiser ID and device ID parameters. The same steps work for any parameter.

Advertiser ID

1. In the tag URL (1x1 pixel or JavaScript), find the advertiser ID parameter avid=. It’s followed by the placeholder [ADVERTISER_ID].
2. Replace [ADVERTISER_ID] with your ad server’s advertiser ID macro. For example, if the macro is {advertiserId}, the URL now contains avid={advertiserId}.
3. Traffic the tag in your ad server inside a test campaign or creative.
4. Open a browser, start the browser’s developer tools or a proxy such as Charles Proxy, and load the test page or tag.
5. In the developer tools or proxy, search for Pixalate’s pixel URL. Pixalate gives you this URL during integration.
6. In the URL’s query string, confirm that avid= is followed by a real advertiser ID (such as avid=28374), not the macro.

Device ID

1. In the tag URL, find the device ID parameter kv19=. It’s followed by the placeholder [DEVICE_ID].
2. Replace [DEVICE_ID] with your ad server’s device ID macro. For example, if the macro is {deviceId}, the URL now contains kv19={deviceId}.
3. Traffic the tag in your ad server inside a test campaign or creative.
4. Open the test app, start the webview’s developer tools (Chrome or Safari) or a proxy such as Charles Proxy, and load the test ad.
5. Search for Pixalate’s pixel URL.
6. Confirm that kv19= is followed by a real device ID (such as kv19=00000000-0000-4000-8000-000000000000), not the macro.

Parameter reference

The Dashboard name column shows where a value appears in the Analytics dashboard. Values marked API only aren’t shown as a dashboard dimension. Where the key is listed, it’s the parameter name in the tag. Pixalate sets the other keys in the tags it generates for you.

Publishers without an ad server

All integrations

All environments

* IDs as represented in your ad server. Pass your ad server’s values so you can find and optimize against them in Pixalate’s data as they appear in your ad server.

Mobile and CTV environments

Video environments

How supply and demand IDs relate

Pixalate supports these ad server IDs. Passing them lets you line up Pixalate’s data with the data in your ad server.

Keep the hierarchy in mind when you map them, so the right ID goes in the right parameter:

• Demand side: the advertiser is the top-level account. For example, an advertiser (advertiser ID) runs three brand campaigns (campaign IDs), and each campaign runs three creatives or tags (creative IDs).
• Supply side: the seller is the top-level partner. For example, a seller (seller ID) works with 10 publishers (publisher IDs), each publisher owns 10 websites (site IDs), and every page on those sites has 3 ad slots (placement IDs).

Supply types (kv24)

The supply type tells Pixalate whether the placement is display, video or native, and whether it runs on desktop, mobile web, mobile app or CTV. Pass it in kv24.

Use a macro to fill it when the ad is served. If your platform has no macro for it, duplicate the tag for each supply type with the value hardcoded, and traffic each copy to the matching supply.

Accepted hardcoded values:

Supported IAB VAST 4.1 macros

Pixalate supports these IAB VAST 4.1 standardized macros. Your video player fills them in at runtime. For definitions, see the IAB Tech Lab’s VAST 4.x macro list.

Pixalate also accepts two values that aren’t IAB macros: video play status (whether the video is auto-play or click-to-play) and purchased or acquired traffic (purchased, acquired). Map them like any other parameter.

Measure viewability for non-standard ad sizes

To measure viewability for ad sizes that aren’t IAB standard sizes, such as native ads, pass the ad placement’s div ID in the divid= parameter of the JavaScript tag. A 1x1 pixel can’t measure viewability. You can hardcode the value or pass it with a macro.

• If the tag can’t find the div you pass, it falls back to its usual way of measuring viewability.
• If you hardcode the div ID, make sure each non-standard placement’s tag has that placement’s own ID.
• If every placement uses the same div ID, the tag only looks for that one div, and viewability results can be misleading.

Traffic the tag on a test page first and send it to Pixalate for QA before you push it to production.

Pass the Supply Chain Object (kv55)

You can pass the IAB Supply Chain Object (SCO), serialized, in kv55. If kv55 isn’t already in the tag Pixalate gave you, add it:

kv55=[SupplyChainObject]

These examples use [PIXALATE_TAG_HOST] in place of the host. Use the host in the tag Pixalate gave you.

JavaScript tag with kv55:

<script type="text/javascript" src="https://[PIXALATE_TAG_HOST]/s/[CLIENT_ID]/aa.js?cb=[CACHEBUSTER]#[CLIENT_ID];paid=[PARTNER_ID];avid=[ADVERTISER_ID];publisherId=[PUBLISHER_ID];kv55=[SupplyChainObject];kv24=[SUPPLY_TYPE]"></script>

1x1 pixel with kv55:

https://[PIXALATE_TAG_HOST]/i?clid=[CLIENT_ID]&paid=[PARTNER_ID]&avid=[ADVERTISER_ID]&publisherId=[PUBLISHER_ID]&kv55=[SupplyChainObject]&kv24=[SUPPLY_TYPE]

Serialization format

Replace [SupplyChainObject] with the serialized object, built the way the IAB describes for SupplyChain in non-OpenRTB requests:

1. Start with the object’s two properties, version and complete, separated by a comma: ver,complete.
2. Add each node, in order. Separate the properties from the first node, and each node from the next, with an exclamation mark (!).
3. Within a node, list the properties in this order, separated by commas: asi,sid,hp,rid,name,domain,ext.

The last node should be your own. If it isn’t already in the serialized value, add it before you pass the value in kv55.

Example

This supply chain has two hops:

"schain": {
  "ver": "1.0",
  "complete": 1,
  "nodes": [
    {
      "asi": "exchange1.com",
      "sid": "1234",
      "hp": 1,
      "rid": "bid-request-1",
      "name": "publisher",
      "domain": "publisher.com"
    },
    {
      "asi": "exchange2.com",
      "sid": "abcd",
      "hp": 1,
      "rid": "bid-request-2",
      "name": "intermediary",
      "domain": "intermediary.com"
    }
  ]
}

Serialized:

1.0,1!exchange1.com,1234,1,bid-request-1,publisher,publisher.com!exchange2.com,abcd,1,bid-request-2,intermediary,intermediary.com

The IAB spec also says to URL-encode any value that contains a comma or an exclamation mark, so the separators stay unambiguous.

To check supply chains in your reports, see Supply chain (SCO) reports and SCO validation and verification.

Related

• Traffic tags in your ad server
• Choose an integration method
• Video: the 1x1 tag in VAST