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 |
---|---|---|---|---|
|
The unique identifier of the conversion rule. |
long |
N/A |
Required |
|
The id of the tag associated with the rule. |
long |
Required |
Read-Only |
|
The name of the rule. |
string |
Required |
Optional |
|
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 |
|
Categories include PURCHASE, SIGN_UP, LEAD, ADD_TO_CART, APP_INSTALL, OTHERS. |
enum |
Required |
Read-Only |
|
Use this field to associate a value with a conversion. |
double |
Optional |
Read-Only |
|
Unique users count for the past 24 hours. |
long |
Read-Only |
Read-Only |
|
Unique users count for the past 30 days. |
long |
Read-Only |
Read-Only |
|
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 |
---|---|---|
|
The id of the parent advertiser. |
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 |
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 |
---|---|
|
The ID of the object to delete. |
|
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 |
---|---|---|---|---|
|
App store ID |
Android: com.yahoo.mobile.client.android.mail iTunes: 577586159 |
string |
Yes |
|
Category of the event type |
One of the following:
|
string |
Yes |
|
Name of specific event |
One of the following:
|
string |
Yes |
|
Additional event label |
[CUSTOM VALUE] |
string |
No |
|
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 |
---|---|
|
Contains substring (case insensitive). |
|
Does not contain substring (case insensitive). |
|
Equal to (case sensitive). |
|
Not equal to (case sensitive). |
|
Less than (for numeric fields only). |
|
Less than or equal to (for numeric fields only). |
|
Greater than (for numeric fields only). |
|
Greater than or equal to (for numeric fields only). |
|
Matches a regular expression (for example: “example.com.*purchase$”). The full PCRE grammar is supported. |
Data types¶
Data |
Description |
---|---|
|
The full URL of the site visited. |
|
The domain of the site visit. |
|
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"
}
}
]
}