Nested object support for custom event properties

Nested Object Support allows you 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 can only be sent with custom events and purchase events. this is not yet supported with user attributes.
  • Event property objects that contain array or object values can have an event property payload of up to 50KB.
  • The following SDK versions support Nested Objects:

Usage examples

API request body

Shown below is a /users/track example with a “Created Playlist” custom event. Once 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"
      }
    }
  ]
}
...

Shown below is a /users/track example with an “Ordered” custom event. Once 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 Liquid templating examples below show how to reference the nested properties saved from the above 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.

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

Triggering Campaign

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:

Triggering Campaign

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

Segmentation

use segment extensions to segment users based on nested event properties. segmentation uses the same notation as triggering (described above).

Frequently asked questions

Does this consume additional data points?

There is no change in how we charge data points as a result of adding this capability.

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 50 KB. Any request over that size limit will be rejected.

WAS THIS PAGE HELPFUL?
New Stuff!