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.

How Dot Tags Work

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 instrumentation, 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, which is discussed in this document, lets you send custom event parameters that transmit more complex event data. You can then use the event data collected through your Dot tag to define specific conversion rules or retargeting segments.

Create a Dot Tag & Conversion Rules For Single Websites

If your Advertiser Account contains a single website, follow these steps:

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

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

  1. Add the pixel with your script to all your webpages, preferably via a tag manager for simplicity.

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

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

Create Dot Tags & Conversion Rules For Accounts With Multiple Websites

If you wish to create Dot Tags and Conversion Rules for multiple websites, follow the steps outlined in this section. Note that these steps are incompatible with Dynamic Product Ads because Dynamic Product Ads require one website per account.

For advertiser accounts with multiple websites, you have essentially two options.

  1. Option A, where you use custom event attributes in your Dot tag

  2. Option B, where you use multiple Dot tags

The Option A strategy is to create a single Dot tag, and then add it to the various websites within your account.

Follow these steps:

  1. To make this work, set a custom event within the Dot tag to relay an identifier of the website from which the pixel is being fired. For example, set ev = 12345 in the dotq array.

<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': '12345',
      '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.

Alternatively, you may omit adding a site id to the tag, and instead, add a domain qualification to the conversion rule; however, based on your setup, this may or may not be programmatically feasible.

  1. Create a conversion rule for each website. Make sure you have the site identifying check in place.

{
"advertiserId": 88922,
"name": "add to cart",
"tagId": 10030500,
"conversionCategory": "ADD_TO_CART",
"conversionValue": 15
"rule": {
        "and": [{
                        "url": {
                                "i_contains": "shoppingcart"
                        }
                },
                {
                        "ev": {
                                "eq": "12345"
                        }
                }]
        }
}

  1. Assign the conversion rule(s) to the correct campaign by updating the campaign object. To update the campaign object, you make a PUT call to the campaign endpoint with one or more campaign objects:

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

Set the conversionRuleIds attribute array with all applicable rule ids.

For Option B, you use multiple Dot tags, as described in this section.

Follow these steps:

  1. Create a Dot tag for each campaign and website you wish to track. A recommended best practice is to put the website and/or campaign id into the name section for easy reference.

  2. Place Dot tags on corresponding websites.

  3. When creating conversion rules, make sure to set the Tag ID to the correct Dot tag Id for that campaign.

  4. Assign rules to the appropriate campaigns by updating the campaign object. Set the conversionRuleIds attribute array with all applicable rule ids.

The Reseller/Aggregator Model

When creating Dot tags for reseller child accounts, you have these two available options:

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

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