> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.pixalate.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pixalate.com/_mcp/server. # The Pixalate tag and macros > Reference for Pixalate Analytics tag parameters, macro mapping, supported IAB VAST 4.1 macros, kv24 supply types and passing the Supply Chain Object in kv55. 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](#parameter-reference) below lists what each parameter is for and whether it's required. > **Warning** > > If you don't pass the values marked as required, Pixalate may not be able to detect some types of invalid traffic. ## 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 | Parameter | Key | Dashboard name | What to pass | Required? | | --------------------------- | ------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | Pixalate client ID | `clid` | — | Your Pixalate client identifier | Hardcoded by Pixalate | | Platform ID | | Ad Platform | ID of the platform or ad server the tags are implemented in | Hardcoded by Pixalate | | Creative size | | Ad Unit Size | Width and height of the creative (width x height) | Recommended (web, in-app). Required for viewability measurement. | | User IP | | *API only* | The user's IP address. Include client IPs from `X-Forwarded-For`. | **Required** (web, in-app) | | Auction ID or impression ID | `kv11` | *API only* | A random, unique ID that identifies each impression. At least 16 characters; alphanumeric preferred. | **Required** (web, in-app) | | Placement ID | | Site Placement | ID of the placement (ad slot or tag) on the page. Each placement on a page needs its own ID: a 300x250 above the fold and a 300x250 below the fold on the same page get different IDs. | **Required** (web, in-app) | | Supply type | `kv24` | Supply Type | The type of supply generating the impression. See [Supply types](#supply-types-kv24). Pass it dynamically or hardcode it. | **Required** (web, in-app) | | Device OS | | *API only* | Operating system of the device | Recommended (web, in-app) | | User agent | | *API only* | User agent of the device | Recommended (web, in-app) | | Cachebuster | | — | A unique alphanumeric value that stops the browser reusing a cached copy. You can use the IAB VAST 4.1 `[CACHEBUSTING]` macro where it's supported. | **Required** for the JavaScript tag | | Page URL | | URL | URL of the page the ad loaded on | **Required** for web (desktop and mobile web) | | App ID or bundle ID | `kv18` | App ID | The app's ID in its app store. For direct in-app integrations you can hardcode it. Examples: app ID `1207472156` (iOS and tvOS), bundle ID `com.example.app` (mobile and CTV). | **Required** (in-app) | | Device ID | `kv19` | *API only* | The device's advertising identifier, such as IDFA, Google Advertising ID (AAID), Roku ID (RIDA) or Amazon Fire ID (AFAI) | **Required** (in-app) | ### All integrations **All environments** | Parameter | Key | Dashboard name | What to pass | Required? | | --------------------------- | ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | Pixalate client ID | `clid` | — | Your Pixalate client identifier | Hardcoded by Pixalate | | Platform ID | | Ad Platform | ID of the platform or ad server the tags are implemented in | Hardcoded by Pixalate | | Advertiser ID \* | `avid` | Advertiser | Ad server ID of the top-level advertiser or demand partner | Recommended | | Campaign ID \* | | Campaign | Ad server ID of the campaign (a group of tags) | Recommended | | Creative ID \* | | Creative | Ad server ID of the individual demand-side creative or tag | Recommended | | Publisher ID \* | `publisherId` | Publisher | Ad server ID of the publisher organization that owns a group of websites. This can be the same as the seller ID if you work with the publisher directly. | Recommended | | Site ID \* | | Site | Ad server ID of the website | Recommended | | Line item ID \* | | Line Item | Ad server ID of the line item | Recommended | | Seller ID \* | | Seller | Ad server ID of the organization you buy the inventory through, such as an SSP | Recommended | | Bid price | | Bid Price | The price offered | Recommended | | Clear price | | *API only* | The price the auction cleared at | Recommended | | Creative size | | Ad Unit Size | Width and height of the creative (width x height) | Recommended | | Page URL | | URL | URL of the page the ad loaded on | **Required** for web (desktop and mobile web) | | User ID | | *API only* | An ID for the user, such as a cookie ID. This is different from a device ID. | **Required** | | User IP | | *API only* | The user's IP address. Include client IPs from `X-Forwarded-For`. | **Required** | | Auction ID or impression ID | `kv11` | *API only* | A unique ID for each impression or request. Under IAB OpenRTB 2, the auction ID is a required, globally unique bid request attribute. You can use the IAB VAST 4.1 `[TRANSACTIONID]` macro where it's supported. Minimum 16 characters; alphanumeric recommended. | **Required** | | Placement ID \* | | Site Placement | ID of the placement (ad slot or tag). Each placement on a page needs its own ID. | **Required** | | Custom | `kv5` | *API only* | Reserved for custom values. Data passed in `kv5` can be shown in the Analytics dashboard. | — | | Advertiser domain (adomain) | | *API only* | The domain of the advertiser's landing page | Recommended | | ISP | | *API only* | Name or ID of the internet service provider | Recommended | | Geographic region | | *API only* | Country or region of the user | Recommended | | Supply type | `kv24` | Supply Type | See [Supply types](#supply-types-kv24) | Hardcoded by Pixalate, or passed by your macro | | Device OS | | *API only* | Operating system of the device | Recommended | | User agent | | *API only* | User agent of the device. You can use the IAB VAST 4.1 `[DEVICEUA]` macro where it's supported. | Recommended | | Supply chain object | `kv55` | *API only* | The serialized supply chain object. See [Pass the Supply Chain Object](#pass-the-supply-chain-object-kv55). | Recommended | | Cachebuster | | — | A unique alphanumeric value that stops the browser reusing a cached copy. You can use `[CACHEBUSTING]` where it's supported. | Recommended | | SDK user ID | | — | A unique user ID assigned by the SDK | Recommended | | IDFV | | — | Identifier for Vendor: a unique ID shared by all apps from one developer on a device | Recommended | | Do not track | | — | Whether the user turned on "do not track" on their device: `1` for true, `0` for false | Recommended | \* 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** | Parameter | Key | Dashboard name | What to pass | Required? | | -------------------- | -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | Latitude | | *API only* | The user's latitude, if available | **Required** | | Longitude | | *API only* | The user's longitude, if available | **Required** | | App ID or bundle ID | `kv18`, `kv32` | App ID | The app's ID in its app store. If your platform has a separate macro for the app ID, Pixalate uses `kv32` for the app ID and keeps `kv18` for the bundle ID. Examples: app ID `1207472156` (iOS and tvOS), bundle ID `com.example.app` (mobile and CTV). | **Required** | | Device ID | `kv19` | *API only* | The device's advertising identifier, such as IDFA, AAID, RIDA or AFAI. You can pass it in one macro or several. | **Required** | | MRAID version | | *API only* | Version of the MRAID API used to deliver the ad (mobile only) | Recommended | | Carrier ID | | *API only* | ID of the mobile carrier | Recommended | | App name | | *API only* | The app's name, separate from its app or bundle ID, as listed by the platform or ad server | Recommended | | Device make or model | | *API only* | Manufacturer or model of the device | Recommended | | SSAI integration | | *API only* | Whether the impression came from a server-side ad insertion (SSAI) integration: `0` for no, `1` for yes | Recommended | | App version | | *API only* | Version of the app that fired the impression | Recommended for mobile | **Video environments** | Parameter | Key | Dashboard name | What to pass | Required? | | ----------------- | --- | ----------------- | ------------------------------------------------------ | -------------------------------------- | | Video length | | *API only* | Duration of the video ad | Recommended | | Content ID | | *API only* | ID of the video content | Recommended | | Video play status | | Video Play Status | The player's state, such as auto-play or click-to-play | **Required**, or hardcoded by Pixalate | ## 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. | Demand side | Supply side | | ------------- | ------------ | | Advertiser ID | Seller ID | | Campaign ID | Publisher ID | | Line item ID | Site ID | | Creative ID | Placement ID | 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: | Environment | Display | Video | Native | | ----------- | --------------- | -------------------- | --------------------- | | Desktop | `Desktop` | `Desktop_Video` | `Desktop_Native` | | Mobile web | `Mobile_Web` | `Mobile_Web_Video` | `Mobile_Web_Native` | | Mobile app | `Mobile_InApp` | `Mobile_InApp_Video` | `Mobile_InApp_Native` | | CTV app | — | `CTV_InApp_Video` | — | | Email | `Email_Display` | `Email_Video` | — | ## 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](https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html). | Macro | Type | Example value | | ----------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `[ERRORCODE]` | integer | `12345678` | | `[MEDIAPLAYHEAD]` or `[ADPLAYHEAD]` | timecode | Encoded: `00%3A05%3A21.123` | | `[ASSETURI]` | string | Encoded: `https%3A%2F%2Fmyadserver.com%2Fvideo.mp4` | | `[VASTVERSIONS]` | array of integers | `2,3,5,6,7,8` | | `[IFATYPE]` | string | `rida` | | `[IFA]` | UUID | `123e4567-e89b-12d3-a456-426655440000` | | `[CLIENTUA]` | string | Encoded: `MyPlayer%2F7.1%20MyPlayerVastPlugin%2F1.1.2` | | `[SERVERUA]` | string | Encoded: `AdsBot-Google%20(%2Bhttp%3A%2F%2Fwww.google.com%2Fadsbot.html)` | | `[DEVICEUA]` | string | Encoded: `Mozilla%2F5.0%20(X11%3B%20Linux%20x86_64)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Chrome%2F51.0.2704.103%20Safari%2F537.36` | | `[DEVICEIP]` | string | IPv4: `192.0.2.10`. IPv6, encoded: `2001%3Adb8%3A85a3%3A%3A8a2e%3A370%3A7334` | | `[LATLONG]` | number,number | `51.004703,3.754806` | | `[DOMAIN]` | string | `www.mydomain.com` | | `[PAGEURL]` | string | Encoded: `https%3A%2F%2Fwww.mydomain.com%2Farticle%2Fpage` | | `[PLAYERSIZE]` | integer,integer | `640,360` | | `[REGULATIONS]` | array of strings | `gdpr` | | `[ADTYPE]` | string | `video` | | `[TRANSACTIONID]` | UUID | `123e4567-e89b-12d3-a456-426655440000` | | `[BREAKPOSITION]` | integer | `2` | | `[APPNAME]` | string | `com.example.myapp` | | `[PLACEMENTTYPE]` | integer | `1` | | `[AUTOREFRESH]` | string | Self-reported by publishers to mark activity from page- or site-level auto-refresh | | `[PLAYERSTATE]` | string | `autoplayed,fullscreen` | 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: ```text 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`: ```html ``` 1x1 pixel with `kv55`: ```text 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](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md#supplychain-for-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: ```json "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: ```text 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](/analytics/sco-reports) and [SCO validation and verification](/compliance/sco). ## Related * [Traffic tags in your ad server](/analytics/ad-server-trafficking) * [Choose an integration method](/analytics/integration-methods) * [Video: the 1x1 tag in VAST](/analytics/video-tag)