Skip to content

Nested objects in custom events

This article describes how to send nested JSON data as properties of custom events and purchases, and how to use those nested objects in your messaging.

You can use nested objects—objects that are inside of another object—to send nested JSON data as properties of custom events and purchases. This nested data can be used for templating personalized information in messages, for triggering message sends, and for segmentation.

Limitations

  • Nested data is supported for both custom events and purchase events, but not other event types.
  • Event property objects that contain array or object values can have an event property payload of up to 100 KB.
  • Event property schemas cannot be generated for purchase events.
  • Event property schemas are generated through sampling custom events from the last 24 hours.

Minimum SDK versions

The following SDK versions support nested objects:

Step 1: Generate a schema

To access the nested data in your custom event, generate a schema for each event with nested event properties. To generate a schema, follow these steps:

  1. Go to Data Settings > Custom Events.
  2. Select Manage Properties for the events with nested properties.
  3. Select the button to generate the schema. To view the schema, select the plus button.

Step 2: Use the nested object

After generating a schema, you can reference the nested data during segmentation and personalization. Refer to the following sections for usage examples:

API request body

The following is a /users/track example with a “Created Playlist” custom event. After a playlist has been created, to capture the properties of the playlist, we will send an API request that lists “songs” as a property, and an array of the nested properties of the songs.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

...
"properties": {
  "songs": [
    {
      "title": "Smells Like Teen Spirit",
      "artist": "Nirvana",
      "album": {
        "name": "Nevermind",
        "yearReleased": "1991"
      }
    },
    {
      "title": "While My Guitar Gently Weeps",
      "artist": "the Beatles",
      "album": {
        "name": "The Beatles",
        "yearReleased": "1968"
      }
    }
  ]
}
...

The following is a /users/track example with an “Ordered” custom event. After an order has been completed, to capture properties of that order, we will send an API request that lists “r_details” as a property, and the nested properties of that order.

1
2
3
4
5
6
7
8
9
10
11
12

...
"properties": {
  "r_details": {
    "name": "McDonalds",
    "identifier": "12345678",
    "location" : {
      "city": "Montclair",
      "state": "NJ"
    }
  }
}
...

Liquid templating

The following Liquid templating examples show how to reference the nested properties saved from the preceding API request and use them in your Liquid messaging. Using Liquid and dot notation, traverse the nested data to find the specific node you would like to include in your messages.

Templating in Liquid in a message triggered by the “Created Playlist” event:

{{event_properties.${songs}[0].album.name}}: “Nevermind”
{{event_properties.${songs}[1].title}}: “While My Guitar Gently Weeps”

Templating in Liquid in a message triggered by the “Ordered” event:

{{event_properties.${r_details}.location.city}}: “Montclair”

Message triggering

To use these properties to trigger a campaign, select your custom event or purchase, and add a Nested Property filter. Note that message triggering is not yet supported for in-app messages, but nested properties in Liquid personalization in the messages will still display.

Triggering a campaign with nested properties from the “Created Playlist” event:

A user choosing a nested property for property filters on a custom event.

The trigger condition songs[].album.yearReleased “is” “1968” will match an event where any of the songs have an album released in 1968. We use the bracket notation [] for traversing through arrays, and match if any item in the traversed array matches the event property.

Triggering a campaign with nested properties from the “Ordered” event:

A user adding the property filter r_details.name is McDonalds for a custom event.

r_details.name: “Mcdonalds”
r_details.location.city: “Montclair”

Segmentation

To segment users based on nested event properties, you must use Segment Extensions. After you’ve generated a schema, the nested objects explorer will display in the segmentation section.

Segmentation uses the same notation as triggering (see Message triggering).

Personalization

Using the Add Personalization modal, select Advanced Event Properties as the personalization type. This allows the option to add a nested event properties after a schema has been generated.

Frequently asked questions

Does using nested objects consume additional data points?

There is no change in how we charge data points as a result of adding this capability. Segmenting based on nested objects uses Segment Extensions, which does not incur additional data point usage.

How much nested data can be sent?

If one or more of the event’s properties contains nested data, the maximum payload for all combined properties on an event is 100 KB. Any request over that size limit will be rejected.

Github   Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!