Yahoo Dot Tags

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.

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 Yahoo 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 Gemini 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 Yahoo search, native and display campaigns run through Gemini.

For details on accessing your Dot tag code, see Create a Conversion Rule or the BrightRoll DSP help page.

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 done with the help of a tag management platform, such as Ensighten or Google Tag Manager.

The steps for creating Conversion Rules in Gemini and BrightRoll DSP can be found at Create a Conversion Rule or the BrightRoll DSP help page.

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 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=custom cannot be changed. 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”.
  • 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 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 Gemini 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 Gemini 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/spp.pl?a=1000112697409&.yp=403062\"/>",
                                                    "type": "img",
                                                    "protocol": "http"
                                                },
                                                {
                                                    "instrumentationCode": "<img src=\"https://sp.analytics.yahoo.com/spp.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/spp.pl?a=10001969463985&.yp=401283\"/>",
                                                                "type": "img",
                                                                "protocol": "http"
                                                            },
                                                            {
                                                                "instrumentationCode": "<img src=\"https://sp.analytics.yahoo.com/spp.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/spp.pl?a=1000112697409&.yp=403062\"/>",
                                                                "type": "img",
                                                                "protocol": "http"
                                                            },
                                                            {
                                                                "instrumentationCode": "<img src=\"https://sp.analytics.yahoo.com/spp.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"
  }
}