Universal Pixel Script

To use a universal pixel, you place the universal pixel script on the webpages that you want to track. Any time a user visits your page, the pixel script sends information to Basis DSP. 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.

An Overview of the Universal Pixel Script

The universal pixel script snippet looks like this:

<script src="https://cdn01.basis.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 Basis servers 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 Basis servers. 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 the 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.com/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 behavior will be the same.

Mobile Apps: Universal pixels can be used in mobile app environments, including S2S. In this environment, you should not attempt to deploy the script. Instead, you should make a request directly to the unversal pixel endpoint. You must populate the cntr_ifa key with the device's mobile advertising identifier (IFA).

Tracking Non-Page View Events

When you use the default snippet, the tracking event occurs as soon as the script loads. Sometimes, you may want to trigger the tracking event only when the user takes an action on the page such as clicking a button.

To achieve this, you may separate the loading of the “up.js” script from the calling of the cntrUpTag.track() function. For example, you can load just the “up.js” script in the HEAD or BODY section of the page and call cntrUpTag.track() later. For example:

<head>
…
<script src="https://cdn01.basis.net/assets/up.js?um=0"></script>
</head>

Then, when the desired action happens, you would call the cntrUpTag.track() function. For example, you may want to fire a tracking event when the user clicks a certain button. One way to achieve this could be as follows:

<button type="button" onclick="cntrUpTag.track('cntrData', '1234ab5678c9d')">Add to cart</button>

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

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. (These reports are available by request. Contact your Customer Success Manager or email dsp.support@basis.net.)
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 an attributed conversion occurs as a result of the pixel firing and a conversion rule executing. If you are using an e-commerce platform, a macro may be available to insert a dynamic value. For example, Shopify's macro for this is {{ total_price | money_without_currency }}.

The data object would then look like this:

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

To determine how to pass revenue in your scenario, 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 Centro cannot advise how to do this for a given website.

Using Transaction IDs

A transaction ID is a code, such as an SKU or an order number, that you associate with a conversion for reporting purposes. It can only consist of numbers and letters (e.g. "ABCD1234"). You define the transaction ID 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 -->

As with revenue, if you are using an e-commerce platform, a macro may be available for this information. Consult the e-commerce platform/software vendor for more information.

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

UP_GTM_variables_2.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. Use the name of your choice instead of 'cntrData' in the Universal Pixel script snippet:

<script src="https://cdn01.basis.net/assets/up.js?um=0"></script>
<script type="text/javascript">
cntrUpTag.track('myData', '1234ab5678c9d');
</script>
Was this article helpful?
0 out of 0 found this helpful