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 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
  }
}

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