Universal Pixel Script

To use a universal pixel, you place the universal pixel script on the webpages that you want to track. Anytime a user visits your page, the pixel script sends information to Basis DSP. You control the information that it sends by adding variables (i.e. data objects) with scripts on your page or by modifying the universal pixel script itself. 

You can share the information on this page your web developers as you set up your pages to use universal pixels. 

 

An Overview of the Universal Pixel Script

The universal pixel script:

  • determines the current page URL

  • collects data objects, if present

  • constructs and executes a request to the universal pixel endpoint

  • inserts a hidden IFrame for user matching, unless this has been disabled

The request to the universal pixel endpoint has this form: 

http(s)://pixel-a.basis.net/up/12345?cntr_url=<encoded URL>&key1=value1&key2=value2…

The request may use a different domain name, depending on your DSP setup, but the format of the request will be the same.

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

Mobile Apps: Universal pixels can be used in mobile app environments, including S2S. There is no need to deploy the pixel script (there may not be a webview to deploy it in). The universal pixel endpoint can be called directly from the mobile app, but you must populate the cntr_ifa key with the device's mobile advertising identifier (IFA). 

 

Page URL Detection and Debugging

Under most circumstances, the universal pixel script will automatically detect the page URL correctly. Any of these configurations will 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 friendly IFrame. 

  • The script is deployed inside of a single unfriendly (cross-domain) IFrame.

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.

universal_pixel_URL_chrome.png

The URL can be decoded for easier readability using a tool like the URL Decoder/Encoder.

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 via 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 the universal pixel script code runs. 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>

Reserved Keys

Keys beginning with “cntr_” are reserved for specific purposes by the DSP and are not intended to be used for arbitrary key-value pair targeting. Additionally, the r parameter is optionally used to add a redirect URL. The reserved keys are:

cntr_url The URL of the page. If set, the value is used instead of automatic detection. Only set this key if you wish to override automatic page URL detection.
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 identifier intended to be made available in conversion reporting (such reports are not yet available).
cntr_ifa Mobile advertising ID of the user. When supplied, this is used instead of attempting to use the Centro cookie ID (i.e. for conversion attribution and audience building).
r If set, the value provides 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 not common.) 

Passing Dynamic Conversion Revenue for Universal Pixel

You can pass dynamic conversion revenue for universal pixels through a reserved key in the cntrData data object, called cntr_revenue. For example:

<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 the pixel fires. To make this a dynamic value, you must use a macro. The data object would then look like this:

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

This macro is defined by whoever sets up your site. Example macros could be [CartTotal] or [CartCheckout].

Note: Macros are usually case sensitive. Double check with your site admin before you place the macro.

Using Transaction IDs

A transaction ID is an alphanumeric code, such as an SKU or an order number, that you associate with a pixel for tracking and reporting purposes. The transaction ID is defined in the cntrData data object through a reserved key called cntr_transactionId:

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

 

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. 

universal_pixel_google_tag_manager.png

Using Variables

You can use variables to pass data to the universa pixel. Just follow the instructions above for passing a data object, declaring the variables 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 category and 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 -->

universal_pixel_google_tag_manager_variables.png

 

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 Basis’ 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 -->

 

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. Look for the string “cntrData” (including quotation marks) towards the end of the Universal Pixel script: 

<script type="text/javascript"> (function(window, document, dataKey, upId, pixelserv) { var cntrUrl = "";  try { cntrUrl = top.location.href; } catch(e) { cntrUrl = (window.location !== window.parent.location) ? document.referrer : document.location.href; } var cntrData = window[dataKey] || {}; if (!cntrData.hasOwnProperty("cntr_url")) cntrData["cntr_url"] = cntrUrl; var queryParams = []; for (var param in cntrData) { if (cntrData.hasOwnProperty(param)) { queryParams.push(encodeURIComponent(param) + "=" + encodeURIComponent(cntrData[param])); } } var query = queryParams.join("&"); var protocol = ('https:' === document.location.protocol ? 'https://' : 'http://'); var upUrl = protocol + pixelserv + '/up/' + upId + (query ? "?" + query : ""); new Image().src = upUrl; (function(d) { var syncUrl = protocol + pixelserv + '/dmp/asyncPixelSync'; var iframe = d.createElement('iframe'); (iframe.frameElement || iframe).style.cssText = "width: 0; height: 0; border: 0;"; iframe.src = "javascript:false"; d.body.appendChild(iframe); var doc = iframe.contentWindow.document; doc.open().write('<body onload="window.location.href=\''+syncUrl+'\'">'); doc.close(); })(document); })(window, document, "cntrData", "abcdef123456789", "pixel-a.basis.net")</script>

You can replace cntrData with the variable name that you wish to use. 

Important: Do not change any other mention of “cntrData” (without quotation marks) in the code.  

Was this article helpful?
0 out of 0 found this helpful