Universal Pixel Script

To use a universal pixel, you place the universal pixel script on the web pages that you want to track. Any time a user visits your page, the pixel script sends information to Basis DSP. The page URL is sent automatically, but you can send additional information by adding a separate 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 universal 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 don't need to modify the universal pixel script in any way. For every page that should send a tracking event to Basis servers on page view, simply include the script in the HEAD or BODY section. To include specific details in the tracking event (the equivalent to using macros with other pixel types), use the data object. See Passing Data Objects below.

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 object, 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 "up.js" script URL may use a different domain name, depending on your DSP setup, but the behaviour 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 universal pixel endpoint. 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 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 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 the cntr_url parameter contains the detected page URL, in encoded form.

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, it can be manually overridden by including a key called cntr_url in the data object with a value consisting of the page URL. Usually, this would be supplied via a macro from the tag management system or platform 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 the script is loaded on. This object is expected to consist of a series of key-value pairs. Create the object at any point 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:

Passing Dynamic 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 Basis Technologies 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, such as "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 about 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 Universal Pixel. Simply 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 -->

Reusing the Google Tag Manager Data Layer

If you are using Google Tag Manager and 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 -->

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 universal pixel. Alternatively, if you'd like to deploy one universal pixel across all Floodlight tags for an advertiser and dynamically route the events to Basis 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 Basis Universal Pixel:

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 can be changed. Use the name of your choice isntead of "cntrData" in the Universal Pixel script snippet. For example:

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