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.
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 |
---|---|
|
A key value used to key rules to the transmitted data points. You should not modify the value provided with the tag code. |
|
Provides additional validation of tag ownership. You should not modify the value provided with the tag code. |
|
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. |
|
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 |
---|---|---|
|
Event category |
The object you want to track. For example, button. |
|
Event action |
The type of interaction the user takes with the category object. For example, click. |
|
Event label |
Useful to label details about the event. For example, Product demo |
|
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 valuecustom
. Note, however, this is only applicable for sending audience data, NOT for conversion tracking.The values of
projectID
andpixelID
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 |
---|---|---|
|
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>
Fields¶
The tag object contains the following fields:
Name |
Description |
Type |
Add |
Update |
---|---|---|---|---|
|
The unique identifier of the tag. |
long |
N/A |
Required |
|
The id of the advertiser that owns the tag. |
long |
Required |
N/A |
|
The tag code. |
string |
Read-Only |
Read-Only |
|
Instrumentation code for passing custom events. Details are available in Installing Dot Tags. |
string |
Read-Only |
Read-Only |
|
Events count for the past 24 hours. |
long |
N/A |
Read-Only |
|
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 |
|
The tag name. |
string |
Required |
Optional |
|
Unique users count for the past 24 hours. |
long |
N/A |
Read-Only |
|
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 |
|
If this is set to |
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 |
---|---|---|
|
The id of the parent advertiser. Use this parameter to get a filtered list of tags that belong to a certain advertiserId. |
long |
|
The maximum number of rows to retrieve. Value should not be greater than 500. |
int |
|
The start index or the first element to retrieve. |
int |
|
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"
}
}