Universal Pixels

Written By

Universal Pixel Script

To use a universal pixel, you place the universal pixel script on webpages that you want to track. Any time a user visits your page, the pixel script sends information to Subset DSP. The page URL is sent automatically, but you can send additional information by adding a data object that contains any key-value pairs that you would like to use in your universal pixel rules.

This documentation contains detailed technical information for developers. Please share it with the developer of the site that you are placing the pixel on.

Overview of the Universal Pixel Script

The universal pixel script snippet looks like this:

<script src="https://cdn01.subset.net/assets/up.js?um=0"></script>
			<script type="text/javascript">
			cntrUpTag.track('cntrData', '1234ab5678c9d');
		</script>

Under most circumstances, you do not need to modify this in any way and can simply include it on a page in the HEAD or BODY section when a tracking event should be sent to Subset servers immediately on page view.

The "um" parameter controls whether user matching is enabled. When it is set to "1", a hidden IFRAME is inserted to perform user matching when the script loads. The “Enable user matching” option in the Get Tags window controls whether the this is set to 1 or 0, but it can also be manually adjusted.

The cntrUpTag.track() function causes the tracking event to be sent to the Subset servers. You can separate this from the loading of the "up.js" library, for example, if you do not wish to immediately cause a tracking event on load, but instead want to populate a data object first or control when the tracking event is dispatched. As long as you include the %lt;SCRIPT%gt;element to load "up.js" before, cntrUpTag.track() may be called at a later time.

The function takes two parameters, which are automatically populated but may be changed if necessary. Using the above as an example:

  • ‘cntrData’: This name of the data object. See Customizing the Data Object Name below.

  • ‘1234ab5678c9d’: The encrypted ID that represents the specific universal pixel in the DSP. Each configured universal pixel has it’s own ID.

When cntrUpTag.track() is called, the script does the following:

  • Determines the current page URL

  • Collects data objects, if present

  • Constructs and executes a request to the universal pixel endpoint

The request to the universal pixel endpoint has this form:

http(s)://pixel.sitescout.net/up/1234ab5678c9d?cntr_url=<encoded URL>&key1=value1&key2=value2…

The request sends the page URL as well as key-value pairs, which you can define and use in your universal pixel rules.

The "up.js" script URL may use a different domain name depending on your DSP setup, but the behaviour will be the same.

 

Page URL Detection and Debugging

Under most circumstances, the universal pixel script will automatically detect the page URL correctly. Any of these configurations correctly detect the page URL:

  • The script is placed directly in the source code of the page.

  • The script is deployed through a tag manager that inserts it directly on to the page.

  • The script is deployed inside a same-origin (friendly) IFRAME.

Page URL detection may not work reliably in cross-origin (unfriendly) IFRAMEs, depending on browser tracking/security policies and site Referrer-Policy header settings. We recommend always deploying a universal pixel by placing the script directly in the source code of the page or using a tag manager that inserts it directly into the page.

Checking the Page URL

You can check whether the page URL has been correctly detected by looking at the call to the universal pixel endpoint. For example, if you look at the Network tab of Chrome developer tools, you see that the cntr_url parameter contains the detected page URL in encoded form.

Overriding the Page URL

If the script is being deployed in a circumstance where the page URL cannot be detected successfully, include a key called cntr_url in the data object with a value consisting of the page URL to override automatic detection. Usually, this would be supplied using a macro from the tag management system or platform that the script is being deployed through.

Passing Data Objects

The universal pixel lets you create rules based on key-value pairs. You supply these key-value pairs by making a data object available to the universal pixel script. The data from the data object is collected and added to the request to the universal pixel endpoint.

The data object is conceptually similar to how a data layer works in Google Tag Manager. In fact, if you are using Google Tag Manager and want to make your entire data layer available to our universal pixel, you can easily do so. A key difference, however, is that instead of an array of objects, we use a single object.

The universal pixel script looks for a data object named “cntrData” on the page that the script is loaded on. This object is expected to consist of a series of key-value pairs. Create the object at any point before calling cntrUpTag.track(). In other words, you can do this:

<script type="text/javascript">
var cntrData = {
                'category':'shoes',
                'gender':'m'
                };
</script>
<!—Universal Pixel Script Code Here -->

but not this:

<!—Universal Pixel Script Code Here -->
<script type="text/javascript">
var cntrData = {
                'category':'shoes',
                'gender':'m'
                };
</script>

Permitted Keys

See the Universal Pixel Endpoint page for details about permitted and reserved keys. The reserved key names are the same regardless of whether you are directly interacting with the Universal Pixel endpoint or creating a JavaScript data object consumed by the universal pixel script. Likewise, you may use any non-reserved keys and values you wish to pass data.

Example

Below is an example of constructing a data object with dynamic conversion revenue, a transaction ID, and the custom field, "productCategory". See the Universal Pixel endpoint page for full details about the keys in the data object.

<script type="text/javascript">
var cntrData = {
                'cntr_revenue':'46.12',
                };
</script>
<!—Universal Pixel Script Code Here -->

This example tracks a revenue of $46.12 every time an attributed conversion occurs as a result of the pixel firing and a conversion rule is executed. The transaction ID of "ABCD1234" will be available in the Conversion Report.

Additionally, the "productCategory" is available to universal pixel rules. For example, you might wish to track conversions separately or create distinct audiences for different product categories.

In practice, these values would not be hardcoded, but rather populated dynamically. If you are using an e-commerce platform, macros may be available to insert a dynamic value.

For example, suppose that your e-commerce platform has macros %%total_order_amount%%, %%order_id%%, and %%product_category%%. You might use them when configuring the universal pixel data object like this:

<script type="text/javascript">
var cntrData = {
                'cntr_revenue':'{{ total_price | money_without_current }}'
                };
</script>
<!—Universal Pixel Script Code Here -->

Alternatively, and especially if not using an e-commerce platform, this might be accomplished by writing some custom code to populate the values. To determine how to proceed or what macros might be used, consult the e-commerce platform / software vendor or site developer. This is specific to the details of the platform/software or custom implementation that you use, and we cannot advise how to do this for a given website.

Deploying Universal Pixel Through Google Tag Manager

Universal pixel can be deployed using any tag manager. Google Tag Manager is specifically documented here as it is most common, but these instructions can be adapted to your tag manager. Consult the documentation for details on your tag manager.

Universal Pixel can be deployed through Google Tag Manager by using the “Custom HTML” tag option.

Using Variables

You can use Google Tag Manager variables to pass data to the universal pixel. Just follow the instructions above for passing a data object, declaring the variables that you need in the cntrData object before the script code.

When you declare the cntrData variables, you can use Google Tag Manager macros to pass values to the cntrData variables. Remember that you refer to a Google Tag Manager macro by its name inside two sets of brackets:

{{Variable Name}}

This example passes the value of the Google Tag Manager variable called Category into the cntrData variable called categoryand the value of the Google Tag Manager variable called Gender into the cntrData variable called gender:

<script type="text/javascript">
var cntrData = {
                'category':'{{Category}}',
                'gender':'{{Gender}}'
                };
</script>
<!—Universal Pixel Script Code Here -->

Reusing the Google Tag Manager Data Layer

If you are using Google Tag Manager, it's easy to make all key-value pairs in the Google Tag Manager data layer available to Subset’s universal pixel. This example assumes all key-value pairs are defined before the Google Tag Manager script loads. These are found in the zeroth element in the dataLayer object array. It is left as an exercise to the reader how to gather additional key-value pairs added at a later point.

In Google Tag Manager, configure a custom HTML tag as follows:

<script type="text/javascript">
var cntrData = dataLayer[0];
</script>
<!—Universal Pixel Script Code Here -->
 

Deploying via Floodlight

If you are deploying the Universal Pixel via a Floodlight container tag, you must select Deploy Via Floodlight before you copy the Universal Pixel code. Additionally, you must use the Floodlight global site tag in order for the page URL to be available to the Universal Pixel.

The Deploy Via Floodlight option includes the code required to automatically collect some variables from Floodlight. This is designed to make implementation more convenient. For example, if you are already passing a revenue amount to your Floodlight tags, it will be automatically passed through to the Subset Universal Pixel. Alternatively, if you'd like to deploy one Subset Universal pixel across all Floodlight tags for an advertiser and dynamically route the events to Subset audiences or conversions based on Floodlight Activity tag string, you can do so.

The following table lists the Floodlight variables collected and the key name they are mapped to for Subset Universal Pixel:

Campaign Manager 360 Variable Name
(String)		 Subset Universal Pixel Key Description
Revenue (cost) cntr_revenue The revenue amount for the transaction, provided that such a value was passed to the Floodlight tag.
Order/Transaction ID (ord) cntr_transactionId A unique transaction or order ID for reporting purposes, provided that such a value was passed to the Floodlight tag.
Advertiser ID (src) src The Campaign Manager 360 Advertiser ID, visible in the Campaign Manager UI.
Activity Tag String (cat) cat The activity string for the Floodlight - an identifier for specific Floodlight activities.
Group Tag String (type) type The group tag string for the Floodlight - an identifier for a group of Floodlight activities.
Custom Variables 1-5 (u1, u2, u3, u4, u5) u1, u2, u3, u4, u5 The first five custom variables, if any were passed to the Floodlight tag. Use for any custom information you want to pass.
 

Customizing the Data Object Name

In extremely unusual cases, the default name for the data object (“cntrData”) may already be in use on a page for some other purpose. In that case, the name may be changed. Use the name of your choice instead of 'cntrData' in the Universal Pixel script snippet:

<script src="https://cdn01.subset.net/assets/up.js?um=0"></script>
			<script type="text/javascript">
			cntrUpTag.track('myData', '1234ab5678c9d');
		</script>
Next

Universal Pixel Endpoint