Value Extractors

A value extractor is a JSONPath expression that allows you to extract a value from a JSON event.

Syntax

JSONPath expressions act as queries that enable users to extract specific data from JSON structures. User can leverage a custom value extractor with JSONPath to handle complex data retrieval, simplifying the aggregation and analysis of data within event payloads.

Take a simplified example of an orderPlace event:

{
   "userId": {
      "id": "abc879e",
      "idType": "crm"
   },
   "type": "orderPlace",
   "lineItems": [
      {
         "productId": "sweater11",
         "category": "clothes/winter",
         "categoriesList": ["clothes", "winter"],
         "total": 45.0,
         "currency": "EUR",
         "quantity": 1.0
      },
      {
         "productId": "jeans89",
         "category": "clothes/casual",
         "categoriesList": ["clothes", "casual"],
         "total": 58.0,
         "currency": "EUR",
         "quantity": 1.0
      },
      {
         "productId": "smartphone123",
         "category": "tech/mobile",
         "categoriesList": ["tech", "mobile"],
         "total": 680.0,
         "currency": "EUR",
         "quantity": 2.0,
      }
   ],
   "order": {
      "total": 783,
      "currency": "EUR"
   }
}

The most basic usage of JSONPath is accessing a field. For example, you would write $.order.total to retrieve the total money spent on this order.

Most of the times though you'll want to work with multiple elements at once. $.lineItems gets you the list of line items. You can also apply filtering: $.lineItems[?(@.categoriesList[0] == 'clothes')] returns the same list but only with the products that have a descendant list field named categoriesList whose first element has a value equal to clothes.

For value-based segmentation use cases, you'll likely want to work with aggregations on top of filters, which we implement as extensions to the JSONPath standard:

• $.lineItems[?(@.categoriesList[0] == 'clothes')].total returns a list of prices of clothes bought, in this case [45.0, 58.0].
• $..lineItems[?(@.categoriesList[0] == 'clothes')].total.sum() returns the sum of prices of clothes bought, in this case 103.0. Notice the $.. at the start, with the double .., symbolizing aggregation.
• $..lineItems[?(@.categoriesList[0] == 'clothes')].quantity.sum() returns the number of clothes bought in this order.

We support the following functions on lists: sum, min, max, avg, stddev and length.

Usage in User Attribute Creation

Intra-event aggregations with JSONPath can be used in various ways to generate user attributes, enabling new segment opportunities. For example, you can create segments like "customers who spent at least $500 on clothes in the past year" or "customers whose average spend on clothes was at least $50 in the past year" to target in media campaigns.

Customers Who Spent at Least $500 on Clothes, in the past Year

The first step in setting up this segment is to create the required user attribute. Follow the instructions below to determine the total amount each user spent on clothes over the past year.

1. Filter the event. In this case, select all orderPlace events that have at least one item of the clothes category.
2. Define the aggregation between different events. In this case, choose Sum to sum the value of the "clothes" category across different orderPlace events for the same user.
3. Define the event field to extract. Within orderPlace events that contain multiple products of the clothes category, we select the value spent on each different clothes product of the event. Select Custom, and start by writing the path to the relevant field: $.lineItems[?(@.categoriesList[0] == 'clothes')].total.
4. Define the aggregation between different event fields within the same event. For the list of prices to be summed into a value representing the total spent on all clothes products, use the sum function: $..lineItems[?(@.categoriesList[0] == 'clothes')].total.sum().
5. Define the default value for users who don't have any clothes purchases in the relevant period. We recommend using 0 for this kind of aggregation.
6. Choose the period. In this case, the events of the last 365 days.
7. Define a name and an ID of your attribute, and save it.

The final step is to define the segment rules in the (Segments tab)[/segment/segments] using the newly created attribute. We recommend waiting until the historical data processing is complete to gain insights into segments, such as estimated reach, and refine the segment definition accordingly.

Customers Whose Average Spend on Clothes Was at Least $50 in the Last Year

1. Filter the event. Please note that, in this example, the way the business defines average is relevant in the decision of the event filter. Consider a user with 3 orders, 2 of which had "clothes" items ($30 and $60), while the third did not.

• If the target average value is $45 (average clothes spent in orders containing the category), then the event filter (step 1) should specify both the event (orderPlace) and the category.
• If the target average value is $30 (customer's category spend on each purchase, on average), then the event filter should only specify that the event is an orderPlace.

2. Define the aggregation between events. In this case, select Average.
3. Follow the same steps as in the previous example.