DPA Pixel Instrumentation¶

This article describes how to install pixel scripts and capture events related to your products.

By definition, a pixel is an organizational structure for a series of rules. One pixel can contain many rules. Once you create pixels, you can add rules to them for tracking conversions and retargeting.

If you have not installed pixels, you’ll need to in order to work successfully with DPA.

For information on how to create pixels with Yahoo DSP, refer to Pixels, which describes how to install and manage pixels.

Important

We request that you use an event script that enables you to track the product that the user has interacted with on your website. To accomplish this, you’ll need to focus on event actions, specifically these string values: ViewProduct, AddToCart, and Purchase to differentiate the conversion funnel. Details are discussed in the sections below.

Using Third-Party Tag Managers¶

If you already have an account with Google Tag Manager and are familiar the Google Tag Manager UI, you may want to take advantage of this tag manager to set up your Yahoo pixels for DPA. The steps to work with the Google Tag Manager are described in the Google Tag Manager Guide for Yahoo DPA pixels.

Similarly, if you already have an account with Signal and are familiar the Signal UI, you may want to take advantage of this tag manager to set up your Yahoo pixels for DPA. The steps are described in the Signal Tag Manager Guide for Yahoo DPA pixels.

Also, if you already have an account with Adobe Dynamic Tag Manager and are familiar the Adobe Tag Manager UI, you may want to take advantage of this tag manager to set up your Yahoo pixels for DPA. The steps are described in the Adobe Tag Manager Guide for Yahoo DPA pixels.

Likewise, if you already have an account with Tealium Tag Manager and are familiar the Tealium Tag Manager UI, you may want to take advantage of this tag manager to set up your Yahoo pixels for DPA. The steps are described in the Tealium Tag Manager Guide for Yahoo DPA pixels.

Capture Events Related to Your Products¶

To track the product that the user has interacted with on your website, you need to use the ea parameter to pass the type of user interaction and the parameter product_id to pass the product id.

Parameter	Type	Description
`ea`	event action	To track the user funnel for product retargeting use case, we accept the following values: ViewProduct AddToCart Purchase If the `ea` parameter is not passed and there is only `product_id`, the event is assumed to be ViewProduct.
`product_id`	product id	Used to pass the product id for the retargeting use case.

Parameter

Type

Description

ea

event action

To track the user funnel for product retargeting use case, we accept the following values:

ViewProduct
AddToCart
Purchase

If the ea parameter is not passed and there is only product_id, the event is assumed to be ViewProduct.

product_id

product id

Used to pass the product id for the retargeting use case.

Use Dot Scripts¶

A pixel script contains 2 parts:

a standard script
a dotq script

You must apply the standard script to all the pages that you would like to track. For the standard part, you can find it on the view tag code page in the Yahoo Native UI. It looks like the following example:

<script type="text/javascript">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({projectId:"XXXX",properties:{pixelId:"YYYY"}});var s=d.createElement(t);s.src=r;s.async=true;s.onload=s.onreadystatechange=function(){var y,rs=this.readyState,c=w[u];if(rs&&rs!="complete"&&rs!="loaded"){return}try{y=YAHOO.ywa.I13N.fireBeacon;w[u]=[];w[u].push=function(p){y([p])};y(c)}catch(e){}};var scr=d.getElementsByTagName(t)[0],par=scr.parentNode;par.insertBefore(s,scr)})(window,document,"script","https://s.yimg.com/wi/ytc.js","dotq"); </script>

In addition to the standard part of the Dot script on the webpage, you’ll also need to add the dotq script to pass the user action and the product id.

Below is an example of the dotq template.

<script type="application/javascript">
    window.dotq = window.dotq || [];
    window.dotq.push(
    {
     'projectId': '10001234567890', -- this value can be found on your Dot page in your account
     'properties': {
       'pixelId': '654321', -- this value can be found on your Dot page in your account
       'qstrings': {
         'et': 'custom',
         'ea': 'insert the standard value',  -- this represents the user interaction with your product
         'product_id': 'product_id value',
       }
    } } ); </script>

For retargeting purposes, use one of the following standard strings to represent the user interaction with the product as the ea value:

ViewProduct
AddToCart
Purchase

Below is an example of a pixel firing result from the advertiser product page:

https://sp.analytics.yahoo.com/spp.pl?a=XXXXXXXX&.yp=YYYYYYYYY&ea=ViewProduct&product_id=BAK1064

The value of XXXXXX and YYYYYYY should match your own Dot on the Dot view page.

Install Chrome Extension to Validate Pixels¶

Yahoo provides you with a Chrome extension that you can use to inspect, validate and troubleshoot pixels that you’ve instrumented on your website.

To install the Chrome extension, follow these steps:

Click Yahoo Ad Platforms Dot Helper.

This takes you to the Developer Tools section of the Chrome Web Store where you can add the extension to your Chrome browser.

Click the ADD TO CHROME button in the upper right corner to install the extension and add it to your Chrome browser.
The Dot Tag Helper has been installed.

How It Works¶

Once you’ve installed Dot tags as part of your pixel instrumentation, this handy tool lets you verify if those tags are sending all the necessary parameters required by Dynamic Product Ads.

The tool performs a simple check on the required parameters for DPA, which are:

Pixel ID (.yp)
Project ID (a)
Event action (ea): Note that the acceptable values are ViewProduct, AddToCart and Purchase.
Product ID (product_id)

If any of the required parameters are missing, the Dot Helper tool will display an error message data unavailable in red text for that parameter.

In addition to the required parameters, the extension also provides you with several other pieces of useful information:

URL: The full script URL, in case you wish to check and verify other parameters.
Load time: The time it takes for the pixel to load. This is valuable for understanding the pixel performance.

Note

Some websites send additional parameters through Dot: for example, gv (for transaction value), et (event type), el (event label), and so on. Since they are optional, the Dot Helper tool only displays these parameters when they exist. No error message is displayed if these parameters are not present.

Some common errors when performing Dot tag instrumentation include:

missing parameter values
incorrect spelling (for example, view_product rather than ViewProduct)
duplicate Dot tags on one page.

Important

If your e-commerce website installs more than 1 pixel for different campaigns, this instrumentation is acceptable. However, if the same pixel ID is fired multiple times on a single page, errors may occur.

For Reseller and Multiple Website Owners¶

If you’re a reseller or advertiser with multiple websites and you want to target users by website, you’ll need to create a separate account with a pixel for each account.

Below is an example of the dotq template.

<script type="application/javascript">
window.dotq = window.dotq || [];
window.dotq.push(
{
  'projectId': '10000', //this value can be found on your Dot page in your account
  'properties': {
    'pixelId': '654321', //this value can be found on your Dot page in your account
    'qstrings': {
      'et': 'custom',
      'ea': 'insert the standard value',  //this represents the user interaction with your product
      'product_id': 'product_id value',
    }
} } ); </script>