Rulesets

Rulesets

A ruleset describes restrictions required for an action to happen, in the case of an offer, the ruleset is used to describe the offer’s targeting settings Offers and some offer related resources containing rules have a relationship key called ruleset.

The ruleset entity contains the following fields:

Geotargeting Rules

  • countries (find possible values here)
  • regions (find possible values here)
  • cities (find possible values here)
  • dmas (find possible values here)
  • postal_codes
  • mobile_carriers (find possible values here)

Device Characteristics Rules

  • browsers (find possible values here)
  • device_types (find possible values here)
  • brands (find possible values here)
  • os_versions (find possible values here)
  • platforms (find possible values here)

Connection Information Rules

  • ips
  • connection_types (find possible values here)

Matches

Each set of rule have two common fields:

  • targeting_type : include or exclude
  • match_type : exact, minimum, maximum or range depending on the type of rule
    • exact : supported on countries, regions, cities, dmas, postal_codes, mobile_carriers, browsers, device_types, brands, platforms, ips
    • maximum : supported on os_versions
    • minimum : supported on os_versions
    • range : supported on ips

Order of Precedence

Some rules precede others in the Geotargeting set of rules. The order is based on the specificity of the rule.

The specificity goes City > DMA > ZIP / Postal Code > Region > Country and the matching logic is the following:

As soon as we hit an “Include” for a rule more specific than the following then we don’t need to continue as even Excludes further down the chain are not enough to justify exclusion.

For example, including New York (City) and excluding United States (Country) is the same as just including New York (City).

Day Parting

The ruleset entity also contains fields related to Day Parting. Day Parting allows you to configure windows in which an action can happen.

The fields are the following:

  • is_use_day_parting
  • day_parting_apply_to
  • day_parting_timezone_id
  • days_parting

is_use_day_parting is a simple boolean flag enabling the day parting

day_parting_apply_to is an optional field, if is_use_day_parting is on, used to specify whether the day parting applies to the user timezone or a specific timezone. Supported values are user_timezone and selected_timezone

day_parting_timezone_id is an optional field, if day_parting_apply_to is set to specific_timezone, used to specify which timezone the day parting is applied to.

days_parting is an optional array field, if is_use_day_parting is on, used to specify rules. There is one entry per window, and there can be multiple windows per day.

For example, the following days_parting entry allows traffic on Tuesdays between 8 AM and 5PM

{
  "day_of_week": 2,
  "start_hour": 8,
  "start_minute": 0,
  "end_hour": 17,
  "end_minute": 0
}

The Ruleset Object

Rulesets are represented by a single json object. It’s the same format that will be used, whether you’re dealing with offer targeting or with custom payout revenue settings targeting.

Below are some examples :

Empty Ruleset

The simplest of all ruleset if one that allows for all traffic to come through. To create an empty ruleset, simply pass an empty json object :

"ruleset": {

}
Simple Rules

Not all types of rules need to be included. You can, for example, only target one type of rule. The following example is for a ruleset that allows traffic from the United States only.

"ruleset": {
  "countries": [
    {
      "country_id": 227,
      "match_type": "exact",
      "targeting_type": "include"
    }
  ]
}

You could target 2 countries at the same time :

"ruleset": {
  "countries": [
    {
      "country_id": 227,
      "match_type": "exact",
      "targeting_type": "include"
    },
    {
      "country_id": 36,
      "match_type": "exact",
      "targeting_type": "include"
    }
  ]
}

Please note that an include rule for "United States" mixed with an exclude rule for "Canada" is redundant as per the explanation in the section above. include "United States" is enough to exclude all other traffic.

Combining Rules

Rules of different types can be used at the same time. Here’s a more complex ruleset that must match ALL the following :

  • Comes from a device running iOS from version 9.0 to 11.4
  • Comes from New York City
  • Is on a mobile connection (as opposed to Wifi)
  • Is not from a known proxy
"ruleset": {
  "os_versions": [
    {
      "os_version_id": 16,
      "match_type": "minimum",
      "targeting_type": "include",
      "platform_id": 2
    },
    {
      "os_version_id": 33,
      "match_type": "maximum",
      "targeting_type": "include",
      "platform_id": 2
    }
  ],
  "cities": [
    {
      "city_id": 479,
      "match_type": "exact",
      "targeting_type": "include"
    }
  ],
  "connection_types": [
    {
      "match_type": "exact",
      "connection_type_id": 2,
      "targeting_type": "include"
    }
  ],
  "is_block_proxy": true
}
Specific Example : Day Parting

The following ruleset only accepts traffic from Monday to Thursday, 9 AM - 6 PM based on the device user’s timezone :

"ruleset": {
  "is_use_day_parting": true,
  "day_parting_apply_to": "user_timezone",
  "days_parting": [
    {
      "day_of_week": 1,
      "start_hour": 9,
      "end_hour": 18
    },
    {
      "day_of_week": 2,
      "start_hour": 9,
      "end_hour": 18
    },
    {
      "day_of_week": 3,
      "start_hour": 9,
      "end_hour": 18
    },
    {
      "day_of_week": 4,
      "start_hour": 9,
      "end_hour": 18
    }
  ]
}

Only on Saturday from noon until 2 PM UTC (regardless of the device user’s timezone) :

"ruleset": {
  "is_use_day_parting": true,
  "day_parting_apply_to": "selected_timezone",
  "day_parting_timezone_id": 67,
  "days_parting": [
    {
      "day_of_week": 6,
      "start_hour": 12,
      "end_hour": 14
    }
  ]
}
Specific Example : IP Ranges

The following ruleset will exclude all IPs in the [10.11.12.13 to 10.11.12.100] range as well as the 1.2.3.4 address

"ruleset": {
  "ips": [
    {
      "match_type": "range",
      "targeting_type": "exclude",
      "ip_from": "10.11.12.13",
      "ip_to": "10.11.12.100"
    },
    {
      "match_type": "exact",
      "targeting_type": "exclude",
      "ip_from": "1.2.3.4",
      "ip_to": "1.2.3.4"
    }
  ]
}
Specific Example : OS Versions

The following ruleset will allow all traffic from iOS version 12.0 and up

"ruleset": {
  "os_versions": [
    {
      "os_version_id": 34,
      "match_type": "minimum",
      "targeting_type": "include",
      "platform_id": 2
    }
  ]
}

Exclude all traffic Android for versions 7.0 and below

"ruleset": {
  "os_versions": [
    {
      "os_version_id": 7,
      "match_type": "maximum",
      "targeting_type": "exclude",
      "platform_id": 1
    }
  ]
}
Complete Ruleset

Although it’s very unlikely that you would ever want to use a ruleset like this, here is an example of a ruleset that combines every type of rule available :

"ruleset": {
    "platforms": [
        {
            "platform_id": 1,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "device_types": [
        {
            "device_type_id": 3,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "os_versions": [
        {
            "os_version_id": 32,
            "match_type": "minimum",
            "targeting_type": "include",
            "platform_id": 1
        },
        {
            "os_version_id": 45,
            "match_type": "maximum",
            "targeting_type": "include",
            "platform_id": 1
        }
    ],
    "browsers": [
        {
            "browser_id": 2,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "brands": [
        {
            "brand_id": 23,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "postal_codes": [
        {
          "postal_code": "90210",
          "targeting_type": "include",
          "match_type": "exact"
        },
        {
          "postal_code": "90211",
          "targeting_type": "include",
          "match_type": "exact"
        }
    ],
    "languages": [
        {
            "browser_language_id": 10,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "countries": [
        {
            "country_id": 227,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "regions": [
        {
            "region_id": 1140,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "cities": [
        {
            "city_id": 555,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "dmas": [
        {
            "dma_code": 807,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "isps": [
        {
            "isp_id": 3827,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "mobile_carriers": [
        {
            "mobile_carrier_id": 32,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "connection_types": [
        {
            "match_type": "exact",
            "connection_type_id": 2,
            "targeting_type": "include"
        }
    ],
    "ips": [
        {
            "match_type": "range",
            "targeting_type": "exclude",
            "ip_from": "100.100.100.100",
            "ip_to": "100.100.100.255"
        }
    ],
    "is_use_day_parting": true,
    "is_block_proxy": true,
    "day_parting_apply_to": "selected_timezone",
    "day_parting_timezone_id": 90,
    "days_parting": [
        {
            "day_of_week": 1,
            "start_hour": 8,
            "end_hour": 17
        },
        {
            "day_of_week": 2,
            "start_hour": 8,
            "end_hour": 17
        }
    ]
}