JSON Predicates

Array matcher

Determines if an array contains an object that matches another criteria.

Jump to examples ↓

• OBJECT PROPERTIES
  • array_contains object

    The JSON Predicate.

• OBJECT PROPERTIES
  • array_contains object

    The JSON Predicate.

  • index number

    The specified element in the array.

Used in:

• Open an event stream

Examples

{
  "filters": {
    "types": ["PUSH_BODY"],
    "predicates": {
      "key": "categories",
      "scope": ["body", "campaigns"],
      "value": {
        "array_contains": { "value": {"equals": "spring_sale"} }
      }
    }
  }
}  

Equals matcher

Determines if the value matches exactly.

Jump to examples ↓

• equals object
  One of
  • string
  • array<oneOf>

Used in:

• Open an event stream

Examples

{
  "filters": [
    {
      "device_types": ["sms"],
      "types": ["CUSTOM"],
      "predicates": [
        {
          "and": [
            {
              "key": "interaction_type",
              "scope": ["body"],
              "value": {"equals": "delivery_report"}
            },
            {
              "not": {
                "key": "name",
                "scope": ["body"],
                "value": {"equals": "delivered"}
              }
            }
          ]
        }
      ]
    }
  ]
}

JSON Predicate

Standard request filters check specific, predefined fields in your events and remove any events that don’t match the criteria for that field. For example, the device_types filter always checks the device_type sub-field of the device object. In contrast, you can use JSON Predicates to examine any part of an event, providing more flexibility than the standard filters. You can also combine multiple JSON Predicate objects to create complex filtering logic for your event stream.

The simplest JSON Predicate examines a single key and provides a matcher object that can be applied to the value at that key. To filter a stream for only Open events, you could use the standard filter types: filters:{"types": ["OPEN"]}. However, to achieve this with a JSON Predicate, you would use filters:{"predicates":{"key":"type", "value": {"equals": "OPEN"}}}. This checks the value of the top-level key type to see if it’s exactly “OPEN”. It also serves as a foundational step for constructing more intricate filters.

To filter for only Android events, you could use the device_type filter, but a JSON Predicate allows for more complex combinations later. Since the device type key doesn’t appear at the top level of the event, you’ll need to provide a scope, like this filters:{"predicates":{"scope":["device"], "key":"device_type", "value": {"equals": "ANDROID"}}}. This configuration targets the device_type key within the device object, checking if its value is “ANDROID”.

You can combine the two filters to see only Opens from Android devices: filters:{"predicates":{"and":[ {"scope":["device"], "key":"device_type", "value": {"equals": "ANDROID"}}, {"key":"type", "value": {"equals": "OPEN"}} ]}}

We also have matchers other than equals. Numeric at_least and at_most can be combined to create ranges. version_matches uses Ivy syntax  to match version numbers. is_present determines if there’s any value at a given key. array_contains can be combined with another predicate to determine if an array contains an object that matches another criteria.

Jump to examples ↓

• And object
  OBJECT PROPERTIES
  • and array
• Or object
  OBJECT PROPERTIES
  • or array
• Not object
  OBJECT PROPERTIES
  • not object

    The JSON Predicate.

• Value object
  OBJECT PROPERTIES
  • key stringREQUIRED

    The name of the value being matched.

  • scope object

    The path into a JSON object.

    One of
    • string
    • array<string>
  • value objectREQUIRED

    The value you are filtering for in the JSON Predicate.

    One of
    • Array_matcher

      Determines if an array contains an object that matches another criteria.

    • Equals_matcher

      Determines if the value matches exactly.

    • Numeric_matcher

      Determines if a number matches or is within range of the criteria.

    • Presence_matcher

      Determines if there is any value for a given key.

    • Version_matcher

      Determines if version numbers match.

Used in:

• Open an event stream

Examples

{
  "filters": {
    "predicates": {
      "and": [
        {
          "scope": ["device"],
          "key": "device_type",
          "value": {"equals": "ANDROID"}
        },
        { "key": "type", "value": {"equals": "OPEN"} }
      ]
    }
  }
}

Numeric matcher

Determines if a number matches or is within range of the criteria.

Jump to examples ↓

• OBJECT PROPERTIES
  • at_least number
• OBJECT PROPERTIES
  • at_most number
• OBJECT PROPERTIES
  • at_least number
  • at_most number

Used in:

• Open an event stream

Examples

{
  "filters": [
    {
      "types": ["CUSTOM"],
      "predicates": [
        {
          "and": [
            { "key": "value",
              "scope": ["body"],
              "value": {"at_least": 100}
            },
            {
              "key": "name",
              "scope": ["body"],
              "value": {"equals": "purchase"}
            }
          ]
        }
      ]
    }
  ]
}

Presence matcher

Determines if there is any value for a given key.

Jump to examples ↓

• is_present boolean

  If true, the value should be present. If false, the value should not be present.

Used in:

• Open an event stream

Examples

{
  "filters": {
    "types": ["OPEN"],
    "predicates": {
      "key": "triggering_push",
      "scope": ["body"],
      "value": {"is_present": true}
    }
  }
}

Version matcher

Determines if version numbers match.

Jump to examples ↓

• version_matches string

  The version number string to be matched. Format strings using Ivy syntax .

Used in:

• Open an event stream

Examples

{
  "filters": [
    {
      "device_types": ["android"],
      "types": ["CUSTOM"],
      "predicates": [
        {
          "and": [
            {
              "key": "app_version",
              "scope": ["device", "attributes"],
              "value": {"version_matches": "[18.4.1,19.2.3]"}
            },
            {
              "key": "name",
              "scope": ["body"],
              "value": {"equals": "purchase"}
            }
          ]
        }
      ]
    }
  ]
}