Dot Tag Instrumentation

Dot is Yahoo’s universal tracking tag.

You use Dot tags to communicate website and app events when you want to track performance and optimize your Yahoo search, native and display campaigns. Dot tags also enable you to leverage retargeting and advanced audience targeting for various Yahoo 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.

Third-Party Tag Managers

The following third-party tag managers are also available, with guides that describe the steps required to set up and deploy Yahoo Native Dot tags:

Important

BigCommerce, another third-party vendor, now also provides Tag Manager support for Yahoo. The Tag Rocket app officially supports Yahoo on BigCommerce stores when using a product-level feed.

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’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 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 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 account, or contact your account manager. Regardless of the Yahoo advertising application you use to retrieve your tag, your single Dot tag works for all your search, native and display campaigns run through Yahoo.

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>

Important

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 provides support for a number of third-party tag managers.

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>

The Dot script

The Dot script contains 2 parts: a standard script and a dotq script.

You must apply the standard script to all the pages that you’d like to track. For the standard part, you can find it on the view tag code page in 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 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 Dot 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.

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 Yahoo Native 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 Yahoo Native 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"
  }
}