Conversion rules

Overview

Conversion rules allow you to tell Gemini which user actions you would like to track. This helps you measure and optimize your performance.

Important

If an advertiser has a default pixel set on the account, then 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.

Fields

Conversion rules have the following fields:

Name Description Type Add Update
id The unique identifier of the conversion rule. long N/A Required
tagId The id of the tag associated with the rule. long Required Read-Only
name The name of the rule. string Required Optional
rule Rules can be applied on either the referrer URL or on specific parameters sent through the tag. See Managing Rules for details. JSON object Required Read-Only
conversionCategory Categories include PURCHASE, SIGN_UP, LEAD, ADD_TO_CART, APP_INSTALL, OTHERS. enum Required Read-Only
conversionValue Use this field to associate a value with a conversion. double Optional Read-Only
cnt24h Unique users count for the past 24 hours. long Read-Only Read-Only
cnt30d Unique users count for the past 30 days. long Read-Only Read-Only
status The status of the rule. Can be ACTIVE or DELETED, and is set to ACTIVE by default. enum Optional Optional

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/rest/conversionrule

Create a new conversion rule

Method: To create a new conversion rule, make a POST call to the conversionrule endpoint with the required fields. Batch create is supported. 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
  }
}

Update conversion rules

Method: Make a PUT call to update one or more existing conversion rules. Only the name field can be updated.

POST https://api.gemini.yahoo.com/v3/rest/conversionrule

Data passed
{
 "id": 116964,
 "name": “updated name”
}

Example response
{
 "errors": null,
 "timestamp": "2015-07-24 19:38:19",
 "response": {
     "id": 116964,
     "name": "updated name",
     "rule": {
         "url": {
             "i_contains": "signup"
         }
     },
     "conversionCategory": "SIGN_UP",
     "conversionValue": 15,
     "advertiserId": 11610,
     "status": "ACTIVE",
     "tagId": 401283
  }
}

Read conversion rule data

Method: To read audience data, you can make a GET call and pass in the following parameters:

Name Description Type
advertiserId The id of the parent advertiser. 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

Example: GET call for a filtered list of conversion rules:

    https://api.gemini.yahoo.com/v3/rest/conversionrule?advertiserId=11610

The response will be the relevant conversion rules:

    {
        "errors": null,
        "timestamp": "2015-07-25 22:58:25",
        "response": [
            {
                "id": 116928,
                "name": "sign up",
                "rule": {
                    "url": {
                        "i_contains": "signup"
                    }
                },
                "conversionCategory": "SIGN_UP",
                "conversionValue": 10,
                "cnt24h": 0,
                "cnt30d": 0,
                "status": "ACTIVE",
                "tagId": 401283
            },
            {
                "id": 116964,
                "name": "checkout",
                "condition": {
                    "rule": {
                        "i_contains": "checkout"
                    }
                },
                "conversionCategory": "CHECKOUT",
                "conversionValue": 20,
                "cnt24h": 0,
                "cnt30d": 0,
                "status": "ACTIVE",
                "tagId": 401283
            }
        ]
    }

Example: GET call for a specific conversion rule:

    https://api.gemini.yahoo.com/v3/rest/conversionrule/116928

The response will be the relevant conversion rule:

    {
        "errors": null,
        "timestamp": "2015-07-25 23:03:08",
        "response": {
            "id": 116928,
            "name": "sign up",
            "rule": {
                "url": {
                    "i_contains": "signup"
                }
            },
            "conversionCategory": "SIGN_UP",
            "conversionValue": 10,
            "cnt24h": 0,
            "cnt30d": 0,
            "status": "ACTIVE",
            "tagId": 401283
        }
    }

Delete a conversion rule

Method: To delete a conversion rule, make a PUT call with the rule object. Batch delete is supported - either a single object or an array can be passed. The following parameters are required:

Name Description
id The ID of the object to delete.
status The status of the object set to be deleted.

Note

In v2, the DELETE operation is supported for both single and multiple ids.

For example:

PUT https://api.gemini.yahoo.com/v3/rest/conversionrule
DELETE https://api.gemini.yahoo.com/v3/rest/conversionrule/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/conversionrule?id=123&id=1234&...

Data passed
{
  "id": 116964,
  "status": “DELETED”
}

Example response
{
  "errors": null,
  "timestamp": "2015-07-21 14:38:19",
  "response": {
      "id": 116964,
      "name": "rule name",
      "rule": {
          "url": {
              "i_contains": "signup"
          }
      },
      "conversionCategory": "SIGN_UP",
      "conversionValue": 15,
      "advertiserId": 11610,
      "status": "DELETED",
      "tagId": 401283
  }
}

Managing Rules

Rules are defined using operators that are applied on data, with and, or or not conditions between them.

Supported operators and data types

The following are the supported operators and data types that can be filtered:

Operators

Operator Description
i_contains Contains substring (case insensitive).
i_not_contains Does not contain substring (case insensitive).
eq Equal to (case sensitive).
neq Not equal to (case sensitive).
lt Less than (for numeric fields only).
lte Less than or equal to (for numeric fields only).
gt Greater than (for numeric fields only).
gte Greater than or equal to (for numeric fields only).
regex_match Matches a regular expression (for example: “example.com.*purchase$”). The full PCRE grammar is supported.

Data types

Data Description
url The full URL of the site visited.
domain The domain of the site visit.
path The path of the site visited (not including the domain).
Any custom data field Any data sent through query parameters of a tag firing, including pre-defined “ec”, “ea”, “el” and “ev” values. Examples: productId, category, price.

Sample rules

Rule: All referrer URLs containing the string “jackets” will be matched.

Example:

  {
  "url": {
    "i_contains": "jackets"
  }
}

Rule: All referrer URLs not containing the string “jackets” will be matched.

Example:

  {
  "url": {
    "i_not_contains": "jackets"
  }
}

Rule: All referrer URLs not containing the string “flowers” and “chocolate” will be matched.

Example:

{
    "not": {
        "and": [
            {
                "url": {
                   "i_contains": "flowers"
                }
            },
            {
                "url": {
                   "i_contains": "chocolate"
                }
            }
        ]
    }
}

Rule: All referrer URLs containing jackets or gloves, and also containing category1 or category2.

Example:

{
    "and": [
        {
            "or": [
                {
                    "url": {
                       "i_contains": "jackets"
                    }
                },
                {
                    "url": {
                       "i_contains": "gloves"
                    }
                }
            ]
        },
        {
            "or": [
                {
                    "url": {
                       "i_contains": "category1"
                    }
                },
                {
                    "url": {
                       "i_contains": "category2"
                    }
                }
            ]
        }
    ]
}

Rule: This custom event rule will match if all of the following custom event field conditions are true: ec = ‘button’, ea = ‘click’, el = ‘Product demo’, and ev is greater than 5.

Example:

“and” :
[
    {
      "ec": {
        "eq": "button"
      }
    },
    {
      "ea": {
        "eq": "click"
      }
    },
    {
      "el": {
        "eq": "Product demo"
      }
    },
    {
      "ev": {
        "gt": "5"
      }
    },
]