How To Utilize Dot Tag & Conversion Rules¶
This document provides you with a step-by-step guide on how to effectively utilize dot tag and conversion rules, based on your particular needs and setup, i.e., whether your advertiser account contains either a single website or multiple websites.
The API workflow described in this document involves, essentially, no more than five basic steps to set up your Dot tag pixels and Conversion Rules.
Important
With the exception of assigning a pixel to a campaign, the Yahoo Native API provides you with all of the functionality available in the Yahoo Native UI. For purposes of this document, the ability to assign a pixel to a campaign is redundant when you set conversion rules to a specific campaign.
Prerequisites¶
Before you begin creating Dot Tags, you may wish to read the documentation devoted to the topic: Dot Tag Instrumentation.
Dot tags enable you to communicate website and app events when you want to track performance and optimize your Yahoo search, native and display campaigns. You can also leverage retargeting and advanced audience targeting for various Yahoo channels.
Before beginning, you may also wish to read the documentation devoted to Conversion Rules.
Conversion rules, when specified, let you determine which user actions you would like to track, thus enabling you to measure and optimize your campaign performance.
Create a Dot Tag & Conversion Rules For Single Websites¶
If your Advertiser Account contains a single website, follow these steps:
Begin by creating a Dot Tag and making a POST call to this endpoint:
POST https://api.gemini.yahoo.com/v3/rest/tag
For example:
Data passed
{
"advertiserId": 88922,
"name": "default dot tag for 88922",
"defaultPixel": true
}
Note
Ensure that you set the defaultPixel
attribute to true
. If there are no default pixels set on your account, you won’t be able to create a conversion rule.
Get the tag by making a GET call:
GET http://api.gemini.yahoo.com/v3/rest/tag/?id=tagID&details=true
At this point you may want to modify your scripts, as needed, if you wish to send specific information to key off in a conversion rule.
Note that Yahoo Dot supports the collection of custom-defined events through the use of a custom event script. This is simply additional JavaScript code placed on a page that works in combination with the Dot tag.
For more information on working with custom event parameters, refer to the documentation that describes Standard custom event parameters.
Add the pixel with your script to all your webpages, preferably via a tag manager for simplicity.
Create Conversion Rules:
By default, a conversion rule is created to capture all events for each campaign. However, granular rules are usually preferred to capture a specific action.
You can create as many conversion rules as needed.
To accomplish this task in your workflow, make a POST call to the conversionrule
endpoint with the required fields. The response will be the newly created rule, or a list of multiple new rules if an array is passed.
For example:
POST https://api.gemini.yahoo.com/v3/rest/conversionrule
Data passed
{
"advertiserId": 11610,
"name": "new sign up",
"tagId": 401283,
"conversionCategory": "SIGN_UP",
"conversionValue": 15,
"rule": {
"url": {
"i_contains": "signup"
}
}
}
Example response
{
"errors": null,
"timestamp": "2015-07-24 19:33:18",
"response": {
"id": 116964,
"name": "new sign up",
"rule": {
"url": {
"i_contains": "signup"
}
},
"conversionCategory": "SIGN_UP",
"conversionValue": 15,
"advertiserId": 11610,
"status": "ACTIVE",
"tagId": 401283
}
}
For more information, refer to the documentation devoted to Conversion Rules.
Assign conversion rules to your campaigns:
You can accomplish this task by updating the campaign object and setting the conversionRuleIds
attribute array with all applicable rule ids.
If you have a default pixel set on your account, it will automatically be added to new campaigns with a conversion rule that matches all events from the default pixel. You can select a specific pixel and/or conversion rule to associate to a campaign to track only events that match the conversion rule specified by setting the conversionRuleIds
field.
If you wish, depending on the conversion rules you assign, you may change the lookback window at this time by modifying the campaign object attribute conversionRuleConfig
. Note that the default is 30 days, and the range is 1 minute to 30 days.
Important
Every report contains a conversion column. However, if you have multiple rules assigned to a campaign, the conversion column will aggregate those conversions. To view a granular breakdown of conversions by rule ids, use the conversion_rules_stats
cube, described in Conversion Rules Stats. This cube provides a breakdown of stats by conversion rules, conversion categories, and other conversion-related information.
The Reseller/Aggregator Model¶
When creating Dot tags for reseller child accounts, you have these two available options:
Option A: create a single Dot tag. You may choose to make a single Dot tag at the reseller/aggregator shell level. If you do this, follow the steps outlined for Option A for advertiser accounts with multiple websites.
Option B: create multiple Dot tags. If you wish to create multiple Dot Tags, we highly recommend you create the Dot tags at the child account level. If so, follow the steps outlined for advertiser accounts with a single website.