Yahoo Native Dot Tags

Dot is Yahoo Native’s universal tracking tag.

You use Dot tags to communicate website and app events when you want to track performance and optimize your Yahoo Native search, native and display campaigns. Dot tags also enable you to leverage retargeting and advanced audience targeting for various Yahoo Native channels.

Using a single pixel, you can manage multiple objectives, like creating new audiences for retargeting and tracking website conversions, mobile app installs and in-app user behavior.

Key benefits

  • Use one Dot tag to record all events for conversion tracking and retargeting. This simplifies instrumentation and maintenance of tags.

  • The Dot tag script loads asynchronously during page load so that it never delays the rest of the content being presented to your users.

  • Your Dot tag is associated with you as an advertiser. The advantage to this is that you can use the same tag to define and track conversions across Yahoo Native’s multiple booking systems for search, native and display campaigns. This flexibility allows you to instrument your site just once and keep defining new conversion and retargeting rules without ever needing to add another Yahoo Native tag to your site.

  • Integration with Bing Ads’ Universal Event Tracking (UET). With one tag, you can use Universal Event Tracking for campaign analytics, enable remarketing and audience-based buying opportunities and better understand your customer activity, like destination URL, visit duration, pages per visit and custom events. You can also view performance of all Bing Ads campaigns in Microsoft’s dashboard with no additional effort.

How it works

Dot provides you with a snippet of JavaScript code that when placed on a website, sends event data to Yahoo Native for use with your advertising campaigns. The event data may be either through standard or custom implementation of Dot tagging.

In the standard Dot implementation, you place the tag in the <head> of every page on your website to transmit standard HTTP header information for each page a user visits, most importantly the URL of the page.

The more advanced option lets you send custom event parameters that transmit more complex event data (e.g., check out with a cart value of $150). You can then use the event data collected through your Dot tag to define specific conversion rules or retargeting segments.

Installing Dot Tags

To access and retrieve your tag, simply visit the Dot section within your Yahoo Native account, or contact your account manager. Regardless of the Yahoo Native advertising application you use to retrieve your tag, your single Dot tag works for all your search, native and display campaigns run through Yahoo Native.

Your Dot tag will look similar to this:

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

Use the entire Dot tag code without modification. As a best practice, it is recommended that you copy and paste it into your whatever page template or content management system you use to tag all your website pages. While you may place the tag anywhere on the webpage, it is recommended to paste it in the <head> section.

If you only wish to send events for certain pages, you’ll need to place the Dot tag only on those pages. This is often accomplished with the help of a tag management platform. Yahoo Native provides support for a number of third-party tag managers. See Third-Party Managers for more information.

Dot tag elements

The table below describes the important, required code elements of the Dot tag. You should not alter or change your Dot tag. Only the dotq parameter of the Dot tag code may be changed, and only if conflicting with other JavaScript used on your site.

Code

Description

pixelId

A key value used to key rules to the transmitted data points. You should not modify the value provided with the tag code.

projectId

Provides additional validation of tag ownership. You should not modify the value provided with the tag code.

https://s.yimg.com/wi/ytc.js

This script, ytc.js, is loaded asynchronously so that the rest of the page rendering is not blocked while fetching the tracking script. The asynchronous loading makes it possible to track all the events that can happen on a page even before the tracking script is fully loaded.

dotq

A global array used for collecting event data. All the events that happen are queued in the global array and are processed by the tag script.

Standard custom event parameters

Dot supports the collection of custom-defined events through the use of a custom event script. This is additional JavaScript code placed on a page that works in combination with the Dot tag on that same page to pass custom-defined values for a set of reserved custom event parameters.

The custom event script supports four custom event parameters that capture and describe a user’s interaction with the website. None of the parameters are mandatory, but at least one of the parameters must be included in the custom event call.

Parameter

Type

Description

ec

Event category

The object you want to track. For example, button.

ea

Event action

The type of interaction the user takes with the category object. For example, click.

el

Event label

Useful to label details about the event. For example, Product demo

ev

Event value

Use it to track a numerical value associated with the goal. For example, a numeral 5.

Capture a custom event on the page

When capturing an event to track, follow the template below:

<script type="application/javascript">
window.dotq = window.dotq || [];
window.dotq.push(
{
  'projectId': '10001234567890',
  'properties': {
    'pixelId': '654321',
    'qstrings': {
      'et': 'custom',
      'ec': 'event category',
      'ea': 'event action',
      'el': 'event label',
      'ev': 'event value',
      'gv': 'conversion value'
    }
} } ); </script>

Note

The et parameter is required to be included and set to the value custom. Note, however, this is only applicable for sending audience data, NOT for conversion tracking. Note also that for the ev value, the enum value has to be passed as a string for the JavaScript value comparison.

Example using a custom event script

The following example shows how you might use the custom event script to capture the event of a user adding a $249 electronics item to a shopping cart:

<script type="application/javascript">
window.dotq = window.dotq || [];
window.dotq.push(
{
  'projectId': '10001234567890',
  'properties': {
    'pixelId': '654321',
    'qstrings': {
      'et': 'custom',
      'ec': 'shopping',
      'ea': 'add to cart',
      'el': 'add to cart',
      'ev': 'electronics',
      'gv': '249.00'
    }
} } ); </script>

Note the following:

  • The et parameter is required to be included and set to the value custom. Note, however, this is only applicable for sending audience data, NOT for conversion tracking.

  • The values of projectID and pixelID must match those of the same parameters of the Dot tag included on the page.

To capture custom events on a user-initiated action:

A common use for the custom event script is to capture an event from an action a user takes after the page loads, like when submitting a form or starting a video.

Using the template above, you can capture events specific to an element of a webpage by including the push call inline.

<button onclick=" window.dotq = window.dotq || []; window.dotq.push( { 'projectId': '10001234567890', 'properties': {  'pixelId': '654321', 'qstrings': { 'et': 'custom', 'ec': 'event category', 'ea': 'event action', 'el': 'event label', 'ev': 'event value', 'gv': 'conversion value' } } } ); ">Submit</button>

Capture dynamic event values

When you use a script to dynamically assign values to events, an additional conversion value parameter – gv – is used. In Yahoo Native advertising applications you may choose to assign a constant conversion value to any conversion rule defined.

Alternatively, you can dynamically assign a conversion value to each standard and custom event collected through your Dot tag by populating the ‘gv’ parameter with JavaScript. This conversion value is a numeric monetary value that represents the revenue associated with the event, and is used to calculate the “revenue” of conversions in reports.

Parameter

Type

Description

gv

Conversion value

Used to pass a dynamic conversion value on a standard or custom event. This represents the goal’s revenue shown in reports.

Assign a conversion value to a standard event

In the example snippets below, the function Revenue is used to show possible business logic. The following are just examples. The actual logic and code for calculating a conversion value would be customized by the advertiser/developer.

<script> function Revenue (totalrev, revshare) {return totalrev * revshare;} // Function for computing the conversion value </script>
<script> window.dotq = window.dotq || [];window.dotq.push({ 'gv': Revenue(20, .5); }); // Compute and pass the conversion value  </script>

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 need to create a separate account per website. You also need to insert an additional parameter in the custom event field.

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',
        'advertiser_id': 'insert the Native & Search account id here',
'ea': 'insert the standard value',  //this represents the user interaction with your product
      'product_id': 'product_id value',
    }
} } ); </script>

Assigning a conversion value to a custom event

You can also dynamically assign a conversion value to a custom event in a similar fashion. This code snippet assigns the value of gv using the variable value.

<script> function Revenue(totalrev, revshare) {return totalrev * revshare;} var amount = Revenue(20, .5); // Compute the conversion value  </script>
<script> window.dotq = window.dotq || []; // Pass the computed goal value window.dotq.push({ 'ec':'Event category', 'ea':'Event action', 'el':'Event label', 'ev':'Event value', 'gv': amount }); </script>

Managing Dot Tags

To create audiences from your website, as well as to track conversions, you will need to place Dot on the pages of your website. You can get a Dot tag using either the Native & Search UI or the tag service. As a best practice, it is recommended that you place the tag on every page on your site.

Tags include the fields shown in the table below.

Fields

The tag object contains the following fields:

Name

Description

Type

Add

Update

id

The unique identifier of the tag.

long

N/A

Required

advertiserId

The id of the advertiser that owns the tag.

long

Required

N/A

codes

The tag code.

string

Read-Only

Read-Only

customEventScript

Instrumentation code for passing custom events. Details are available in Installing Dot Tags.

string

Read-Only

Read-Only

eventCnt24h

Events count for the past 24 hours.

long

N/A

Read-Only

eventCnt30d

Events count for the past 30 days. If there is data for less than 30 days, then a forecast will be provided.

long

N/A

Read-Only

name

The tag name.

string

Required

Optional

uuCnt24h

Unique users count for the past 24 hours.

long

N/A

Read-Only

uuCnt30d

Unique users count for the past 30 days. If there is data for less than 30 days, then a forecast will be provided.

long

N/A

Read-Only

defaultPixel

If this is set to true, it becomes your default account pixel. The default pixel will then be associated with any new campaign. However, you can optionally specify different rules you have created for this pixel for each campaign.

boolean

Optional

Optional

Important

To clarify the meaning of defaultPixel and its usage: if you have one default pixel set for your account (which can be a child reseller account), each newly created campaign will by default use that pixel. You can then create any number of conversion rules tied to that default pixel. However, these conversion rules are not by default linked to any campaigns – each conversion rule has to be assigned to a specific campaign. No custom conversion rules are automatically set to campaigns, only the conversion rule that matches all events from the default pixel.

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/rest/tag/

Read tag data

The following parameters are supported when making GET calls to retrieve tag data:

Name

Description

Type

advertiserId

The id of the parent advertiser. Use this parameter to get a filtered list of tags that belong to a certain advertiserId.

long

mr

The maximum number of rows to retrieve. Value should not be greater than 500.

int

si

The start index or the first element to retrieve.

int

details

Use this parameter to request tag details that include user counts and the tag code.

boolean

Method: To retrieve data for a specific tag, make a GET call with the the ID parameter:

    http://api.gemini.yahoo.com/v3/rest/tag/401283

The response will be the tag associated with the id:

    {
        "errors": null,
        "timestamp": "2015-07-02 3:06:40",
        "response": {
            "id": 401283,
            "status": "ACTIVE",
            "advertiserId": 11610,
            "defaultPixel": true,
            "name": "remarketing tag"
        }
    }

Method: To retrieve the code and additional info for this tag, make a GET call with the the ID parameter and use the details parameter:

    https://api.gemini.yahoo.com/v3/rest/tag/403062?details=true

The response will be the tag associated with the id:

    {
        "errors": null,
            "timestamp": "2015-08-07 4:58:29",
            "response": {
                "status": "ACTIVE",
                "id": 403062,
                "defaultPixel": false,
                "advertiserId": 11610,
                "name": "remarketing dot tag",
            "codes": [
                {
                     "instrumentationCode": "<script type=\"application/javascript\">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({'projectId':'1000112697409','properties':{'pixelId':'403062'}});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\",\"http://d.yimg.com/wi/ytc.js\",\"dotq\");</script>",
                                                    "type": "js",
                                                    "protocol": "http"
                                                },
                                                {
                                                    "instrumentationCode": "<script type=\"application/javascript\">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({'projectId':'1000112697409','properties':{'pixelId':'403062'}});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>",
                                                    "type": "js",
                                                    "protocol": "https"
                                                },
                                                {
                                                    "instrumentationCode": "<img src=\"http://sp.analytics.yahoo.com/ssp.pl?a=1000112697409&.yp=403062\"/>",
                                                    "type": "img",
                                                    "protocol": "http"
                                                },
                                                {
                                                    "instrumentationCode": "<img src=\"https://sp.analytics.yahoo.com/ssp.pl?a=1000112697409&.yp=403062\"/>",
                                                    "type": "img",
                                                    "protocol": "https"
                                                }
                                            ],
                                            "customEventScript": "<script type=\"application/javascript\">\nwindow.dotq = window.dotq || [];\nwindow.dotq.push(\n{\n'projectId': '1000112697409',\n'properties': {\n'pixelId': '403062',\n'qstrings': {\n'et': 'custom',\n'ec': 'event category',\n'ea': 'event action',\n'el': 'event label',\n'ev': 'event value',\n'gv': 'conversion value'\n}\n} } ); </script>",
                                            "uuCnt30d": 0,
                                            "uuCnt24h": 0,
                                            "eventCnt30d": 0,
                                            "eventCnt24h": 0
                                        }
                                    }

Example: GET call for a filtered list of tags including details:

    https://api.gemini.yahoo.com/v3/rest/tag?advertiserId=11610&details=true

The response will be the relevant tags:

    {
        "errors": null,
        "timestamp": "2015-08-07 5:03:49",
        "response": [
            {
               "defaultPixel": true,
                       "status": "ACTIVE",
                       "id": 401283,
                       "advertiserId": 11610,
                       "name": "remarketing tag",
               "codes": [
                    {
                        "instrumentationCode": "<script type=\"application/javascript\">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({'projectId':'10001969463985','properties':{'pixelId':'401283'}});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\",\"http://d.yimg.com/wi/ytc.js\",\"dotq\");</script>",
                                                                "type": "js",
                                                                "protocol": "http"
                                                            },
                                                            {
                                                                "instrumentationCode": "<script type=\"application/javascript\">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({'projectId':'10001969463985','properties':{'pixelId':'401283'}});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>",
                                                                "type": "js",
                                                                "protocol": "https"
                                                            },
                                                            {
                                                                "instrumentationCode": "<img src=\"http://sp.analytics.yahoo.com/ssp.pl?a=10001969463985&.yp=401283\"/>",
                                                                "type": "img",
                                                                "protocol": "http"
                                                            },
                                                            {
                                                                "instrumentationCode": "<img src=\"https://sp.analytics.yahoo.com/ssp.pl?a=10001969463985&.yp=401283\"/>",
                                                                "type": "img",
                                                                "protocol": "https"
                                                            }
                                                        ],
                                                        "customEventScript": "<script type=\"application/javascript\">\nwindow.dotq = window.dotq || [];\nwindow.dotq.push(\n{\n'projectId': '10001969463985',\n'properties': {\n'pixelId': '401283',\n'qstrings': {\n'et': 'custom',\n'ec': 'event category',\n'ea': 'event action',\n'el': 'event label',\n'ev': 'event value',\n'gv': 'conversion value'\n}\n} } ); </script>",
                                                        "uuCnt30d": 0,
                                                        "uuCnt24h": 0,
                                                        "eventCnt30d": 0,
                                                        "eventCnt24h": 0
                                                    },
                                                    {
                                                        "defaultPixel": false,
                                                        "status": "ACTIVE",
                                                        "id": 403062,
                                                        "advertiserId": 11610,
                                                        "name": "remarketing dot tag",
                                                        "codes": [
                                                            {
                                                                "instrumentationCode": "<script type=\"application/javascript\">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({'projectId':'1000112697409','properties':{'pixelId':'403062'}});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\",\"http://d.yimg.com/wi/ytc.js\",\"dotq\");</script>",
                                                                "type": "js",
                                                                "protocol": "http"
                                                            },
                                                            {
                                                                "instrumentationCode": "<script type=\"application/javascript\">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({'projectId':'1000112697409','properties':{'pixelId':'403062'}});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>",
                                                                "type": "js",
                                                                "protocol": "https"
                                                            },
                                                            {
                                                                "instrumentationCode": "<img src=\"http://sp.analytics.yahoo.com/ssp.pl?a=1000112697409&.yp=403062\"/>",
                                                                "type": "img",
                                                                "protocol": "http"
                                                            },
                                                            {
                                                                "instrumentationCode": "<img src=\"https://sp.analytics.yahoo.com/ssp.pl?a=1000112697409&.yp=403062\"/>",
                                                                "type": "img",
                                                                "protocol": "https"
                                                            }
                                                        ],
                                                        "customEventScript": "<script type=\"application/javascript\">\nwindow.dotq = window.dotq || [];\nwindow.dotq.push(\n{\n'projectId': '1000112697409',\n'properties': {\n'pixelId': '403062',\n'qstrings': {\n'et': 'custom',\n'ec': 'event category',\n'ea': 'event action',\n'el': 'event label',\n'ev': 'event value',\n'gv': 'conversion value'\n}\n} } ); </script>",
                                                        "uuCnt30d": 0,
                                                        "uuCnt24h": 0,
                                                        "eventCnt30d": 0,
                                                        "eventCnt24h": 0
                                                    }
                                                ]
                                            }

Create a tag

Method: To create a new tag, make a POST call to the tag endpoint with the required fields.

POST https://api.gemini.yahoo.com/v3/rest/tag

Data passed
{
  "advertiserId": 11610,
  "name": "remarketing dot tag"
}



Example response
{
  "errors": null,
  "timestamp": "2015-07-23 0:31:36",
  "response": {
      "id": 403062,
      "status": "ACTIVE",
      "defaultPixel": false,
      "advertiserId": 11610,
      "name": "remarketing dot tag"
  }
}

Update an existing tag

Method: To update one or more existing tags, make a PUT call with one or more tag objects. Specify the fields to update; note that id is the only required parameter. The result will be the list of updated objects. Partial update is supported; fields that are either not passed or passed as null will be ignored for the update.

PUT https://api.gemini.yahoo.com/v3/rest/tag

Data passed
{
  "id": 401283,
      "name": "updated tag name"
}

Example response
{
  "errors": null,
  "timestamp": "2015-07-02 3:01:44",
  "response": {
      "status": "ACTIVE",
      "id": 401283,
      "advertiserId": 11610,
      "defaultPixel": false,
      "name": "updated tag name"
  }
}

Install Chrome Extension to Validate Dot Tags

Native Ad Platform now provides you with a Chrome extension that you can use to inspect, validate and troubleshoot Dot tags that you’ve instrumented on your website.

To install the Chrome extension, follow these steps:

  1. Click Yahoo Native Dot Helper. This takes you to the Developer Tools section of the Chrome Web Store.

dot helper chrome main
  1. Click the ADD TO CHROME button in the upper right corner to install the extension and add it to your Chrome browser.

add to chrome

Once you’ve installed Dot tags as part of your Dot 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, as shown below:

dot help main

The required parameters for DPA are:

  • Pixel ID

  • Project ID

  • Event action (ea): acceptable values are ViewProduct, AddToCart and Purchase.

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

dot helper error

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.