Universal Pixel Endpoint
This documentation contains detailed technical information. Please share it with the developer or technical resources you are working with to deploy universal pixels.
The universal pixel endpoint is a URL used to send events to Subset for a universal pixel.
The URL is: https://pixel.sitescout.com/up/[Universal Pixel ID].
For example it will look something similar to: https://pixel.sitescout.com/up/1234.
Universal Pixel ID and URL
The Universal Pixel ID is the number listed within the Tag Code.
All deployment options for the universal pixel cause a GET request to this URL. Key-value pairs are included on the query string to send data to Subset. For most circumstances, you should use the script tag option to deploy a universal pixel. This allows the script to populate certain parameters like the URL by default.
However, in some instances, you might want to interact with the universal pixel endpoint more directly.
For example, you may want to send events from a mobile app environment or send postback conversions. You can make requests to the universal pixel endpoint client-side or server-to-server. Since cookies can't be accessed if fired server-to-server, this would typically be used for mobile app events (with advertising ID explicitly passed) or postback conversions.
The universal pixel endpoint is designed to receive a stream of events in real-time. If you'd like to upload batches of pre-existing mobile audience data, you can do so directly within Subset.
This also applies for when you deploy a universal pixel as an image tag, as the IMG tag simply loads the universal pixel endpoint URL.
Supported Query String Parameters
You send data to Subset by putting key-value pairs in the query string in the form of "key=value", separated by ampersands (&). The order of the key-value pairs does not matter.
Certain keys are reserved—they have a special meaning to Subset and are used to collect certain data points. Include the reserved keys to pass the specific data point to Subset.
You can include any additional key-value pairs you want, using any arbitrary name for the key and any arbitrary values, as long as the key names do not conflict with the reserved keys. These key-value pairs can then be used in Universal Pixel Rules to conditionally add the user to an audience, count a conversion, and so on based on the data sent.
Please ensure that you URL-encode keys and values so they can be safely carried on the query string.
The following are the reserved keys currently supported. All of these parameters are optional; however, depending on the circumstance, some are functionally necessary.
All keys beginning with "cntr_" are reserved by Subset for future use, even if not listed below. If you wish to send arbitrary data for universal pixel rules, use any key name that does not begin with "cntr_" or otherwise conflict with the reserved key names listed below.
Reserved Keys
| Key | Description |
|---|---|
| cntr_url |
The URL of the page. Set this to ensure that URL-based rules function correctly. |
| cntr_revenue | Customer revenue associated with the event. Use this to pass an amount for the DSP to track for conversion revenue reporting purposes. |
| cntr_transactionId | An order ID or other unique alphanumeric identifier intended to be made available in conversions detail reporting. While typically a transaction ID, it can be anything you want to see in that report. For example, you might pass a SKU instead. |
| cntr_ifa |
Advertising ID (sometimes called "device ID") of the user. When supplied, this is used instead of attempting to use the Subset cookie ID (for example, for conversion attribution and audience building). Advertising IDs are used instead of cookies in app environments on mobile and CTV devices. You can pass iOS IDFAs, Google Advertising IDs, or CTV advertising IDs here. Be sure to pass the IFA in the expected case and form as generated by the operating system. That is uppercase for IDFAs, and lowercase for Google Advertising IDs, in the 8-4-4-4-12 format. Subset internally operates on SHA1-hashed values, so the case and formatting of the IFA as passed is relevant to ensuring that it matches bid requests correctly. |
| cntr_postbackAuctionId |
The auction ID to use for postback conversion attribution. When you send this, instead of attempting to perform attribution based on the cookie ID or passed advertising ID, the conversion is attributed to the click or impression represented by that auction ID. This is used to delegate conversion attribution to a third party. For example, this might be a mobile measurement partner (MMP) like Kochava or Appsflyer, used to enable app install attribution. It's also used for Footfall attribution and other cases where it isn't possible (or applicable) to track a conversion by placing a pixel on a page. Include only one of cntr_ifa or cntr_postbackAuctionId as they are mutually contradictory. |
| cntr_eventTimestamp |
The time of the conversion formatted as a UNIX timestamp (for example, 1564943537) in seconds or milliseconds (auto-detected), UTC. The timestamp must be no more than 3 days prior to today, and a timestamp greater than 3 days ago defaults to "now". Omission also means "now". This is used to convey the timestamp at which the conversion should be recorded if the conversions can't be sent in real time, and is supported for both conventional and postback scenarios. For example, if there is a multi-hour processsing delay before a postback is sent to Subset, you can set this to the actual time of conversion to ensure that it is reported at the correct time. cntr_postbackTimestamp is also supported as a synonym. |
| r |
If set, the value tells the URL to redirect to after the pixel fires. Used only if calling the universal pixel is part of a series of redirects. This is uncommon, and would typically only apply to client-side deployment. |
| gdpr | Consistent with the IAB Europe Transparency & Consent Framework, pass "1" as value to indicate that GDPR is applicable. Regardless, Subset will consider GDPR applicable if the request IP address resolves to a geolocation in EU. |
| gdpr_consent | Consistent with the IAB Europe Transparency & Consent Framework, pass a base64-encoded consent string. This is used to determine whether sufficient consent for Subset exists to process the event in accordance with EU regulations. |
Examples
Mobile App
Let's say you want to send events from a mobile app to Subset for audience building or attribution. You can make requests to the universal pixel endpoint like this, including the user's mobile advertising ID in the cntr_ifa parameter:
https://pixel.sitescout.com/up/1234?cntr_ifa=d5434a7b-c558-4dac-9d72-8a37e6a5ac2e
However, what if there are multiple types of events? Suppose that this is a ride-sharing app, and you are tracking events for when the user first launches the app, when they search for a ride, and when they book a ride. Without additional parameters, it isn't possible to tell these events apart. So, you would include a parameter like this:
https://pixel.sitescout.com/up/1234?cntr_ifa=d5434a7b-c558-4dac-9d72-8a37e6a5ac2e&event=first_run
https://pixel.sitescout.com/up/1234?cntr_ifa=d5434a7b-c558-4dac-9d72-8a37e6a5ac2e&event=search_ride
https://pixel.sitescout.com/up/1234?cntr_ifa=d5434a7b-c558-4dac-9d72-8a37e6a5ac2e&event=book_ride
Then, using Universal Pixel Rules, specify how the events are treated based on this custom key-value pair. The key and values can be anything you want that is meaningful to you.
Postback
Let's say you need to send conversions to Subset as postbacks. To send the postback to Subset, call the universal pixel endpoint as illustrated.
In this case, let's assume a scenario with delayed processing, so we include the cntr_eventTimestamp parameter to indicate when the conversion occurred:
https://pixel.sitescout.com/up/1234?cntr_postbackAuctionId=12345678abcd&cntr_eventTimestamp=1713983563 (Wednesday, April 24, 2024 6:32:43 PM UTC as UNIX timestamp in seconds)
Similar to the prior examples, you can still include other key-value pairs:
https://pixel.sitescout.com/up/1234?cntr_postbackAuctionId=12345678abcd&cntr_eventTimestamp=1713983563&product=tshirt&colour=red
Client-Side Image Pixel
Let's say you are deploying universal pixel using a client-side pixel, or similar means, such as deploying the URL through a tag manager. While you should use the script tag option whenever possible for ease of use, client preferences might require you to use this method instead. In that case, you'd need to arrange key-value pairs to substitute for the various reserved keys that would have been populated in the script under normal circumstances.
For example, assume that:
You want to be able to make URL-based rules.
You are dealing with EU users and thus need to pass consent information.
You want to pass revenue and a transaction ID.
The URL for this might look as follows, assuming the page being visited is https://www.example.com/products?productId=27, the transaction ID is "3922019" and the revenue amount is "39.99":
https://pixel.sitescout.com/up/1234?cntr_transactionId=3922019&cntr_revenue=39.99&cntr_url=https%3A%2F%2Fwww.example.com%2Fproducts%3FproductId%3D27&gdpr=1&gdpr_consent=CP9nTYKP9nTYKNTAAAENCZCMAP_AAH_AAAwII7Nd_X__bX9n-_7_6ft0eY1f9_r37uQzDhfNs-8F3L_W_LwX32E7NF36tq4KmR4ku1bBIQNtHMnUDUmxaolVrzHsak2cpyNKJ_JkknsZe2dYGF9Pn9lD-YKZ7_5_9_f52T_9_9_-39z3_9f___dv_-__-vjf_599n_v9fV_78_Kf9______-____________8Edmu_r__tr-z_f9_9P26PMav-_1793IZhwvm2feC7l_rfl4L77Cdmi79W1cFTI8SXatgkIG2jmTqBqTYtUSq15j2NSbOU5GlE_kyST2MvbOsDC-nz-yh_MFM9_8_-_v87J_-_-__b-57_-v___u3__f__Xxv_8--z_3-vq_9-flP-_______f___________-AA.II7Nd_X__bX9n-_7_6ft0eY1f9_r37uQzDhfNs-8F3L_W_LwX32E7NF36tq4KmR4ku1bBIQNtHMnUDUmxaolVrzHsak2cpyNKJ_JkknsZe2dYGF9Pn9lD-YKZ7_5_9_f52T_9_9_-39z3_9f___dv_-__-vjf_599n_v9fV_78_Kf9______-____________8A
Or, if deployed as an <IMG> tag:
<img src="https://pixel.sitescout.com/up/1234?cntr_transactionId=3922019&cntr_revenue=39.99&cntr_url=https%3A%2F%2Fwww.example.com%2Fproducts%3FproductId%3D27&gdpr=1&gdpr_consent=CP9nTYKP9nTYKNTAAAENCZCMAP_AAH_AAAwII7Nd_X__bX9n-_7_6ft0eY1f9_r37uQzDhfNs-8F3L_W_LwX32E7NF36tq4KmR4ku1bBIQNtHMnUDUmxaolVrzHsak2cpyNKJ_JkknsZe2dYGF9Pn9lD-YKZ7_5_9_f52T_9_9_-39z3_9f___dv_-__-vjf_599n_v9fV_78_Kf9______-____________8Edmu_r__tr-z_f9_9P26PMav-_1793IZhwvm2feC7l_rfl4L77Cdmi79W1cFTI8SXatgkIG2jmTqBqTYtUSq15j2NSbOU5GlE_kyST2MvbOsDC-nz-yh_MFM9_8_-_v87J_-_-__b-57_-v___u3__f__Xxv_8--z_3-vq_9-flP-_______f___________-AA.II7Nd_X__bX9n-_7_6ft0eY1f9_r37uQzDhfNs-8F3L_W_LwX32E7NF36tq4KmR4ku1bBIQNtHMnUDUmxaolVrzHsak2cpyNKJ_JkknsZe2dYGF9Pn9lD-YKZ7_5_9_f52T_9_9_-39z3_9f___dv_-__-vjf_599n_v9fV_78_Kf9______-____________8A" width="1" height="1" style="position: absolute; left: -150px;" />
It is especially important to ensure that values for cntr_url are correctly URL-encoded as they are likely to contain characters like an ampersand that would conflict with parsing the query string correctly.