Conversion rules¶

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

Important

If you have a default Dot tag (pixel) set on your account, it will automatically be added to new campaigns with a conversion rule that matches all events from the default Dot tag. You can select a specific Dot tag 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
  }
}

Read in-app conversion rule data

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

Key	Description	Example values	Type	Required
`ai`	App store ID	Android: com.yahoo.mobile.client.android.mail iTunes: 577586159	string	Yes
`ec`	Category of the event type	One of the following: Purchase Sign Up Lead Add To Cart View Content Add To Wishlist Initiate Checkout Add Payment Info Others	string	Yes
`ea`	Name of specific event	One of the following: AchievedLevel ActivatedApp AddedPaymentInfo AddedToCart AddedToWishlist CompletedRegistration CompletedTutorial InitiatedCheckout Purchased Rated Searched Lead SignUp SpentCredits UnlockedAchievement ViewedContent [CUSTOM VALUE]	string	Yes
`el`	Additional event label	[CUSTOM VALUE]	string	No
`ev`	Numeric data associated with the event	[CUSTOM VALUE]	Fixed point	Yes

Note

The ea parameter can be any value, but the ec parameter must be from the enumerated list.

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: A 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"
            }
          }
       ]
      }

Rule: A custom event rule for mobile in-app events will match if all of the following custom event field conditions are true: ec = ‘Purchase’, ea = ‘AchievedLevel’, el = ‘customValue’, and ev = ‘customValue’.

Example:

{
      “and” : [
          {
            "ec": {
              "eq": "Purchase"
            }
          },
          {
            "ea": {
              "eq": "AchievedLevel"
            }
          },
          {
            "el": {
              "eq": "customValue"
            }
          },
          {
            "ev": {
              "eq": "customValue"
            }
          },
      {
        "ai": {
          "eq": "305343404"
        }
      }
    ]
       }