Nested Object Support for Custom Event Properties

Nested Object Support allows you to send arrays of data as properties of custom events and purchases. This nested data can be used for templating personalized information in API-triggered messages through the use of Liquid and dot notation.

Limitations

  • Nested data can only be sent with custom events and purchase events. This is not yet supported with user attributes.
  • Array data cannot be used for segmentation or in any other way on the platform outside of Liquid templating and triggering.
  • Datetimes are not supported within the array.
  • Object data types will be ingested as strings.
  • Event property objects that contain array or object values can have an event property payload of up to 50KB.
  • Available on events/purchases sent via API only, the Braze SDKs are not yet supported.

Usage Examples

API Request Body

Shown below is a /users/track example with a “Played Song” custom event. Once a song has been played, to capture the properties of the song, 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
...
properties: {
  ...
  "songs" :[{
    "title" : "Smells Like Teen Spirit",
    "artist" : "Nirvana",
    "album" : {
      "name" : "Nevermind",
      "yearReleased" : "1991"
    }
  }],
  ...
}
...

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
13
14
...
properties:{
  ...
  "r_details" : {
    "name" : "McDonalds",
    "identifier" : "12345678",
    "location" : {
      "city" : "Montclair",
      "state" : "NJ"
    }
  },
  ...
}
...

Liquid Templating

The Liquid templating example below shows how to reference the nested properties saved from the above API request and use them in your API-triggered Liquid messaging. Using Liquid and dot notation, traverse the nested data array to find the specific node you would like to include in your API-triggered messages.

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

{{event_properties.${songs}[0].album.name}} - “Nevermind”
{{event_properties.${songs}[0].title}} - “Smells Like Teen Spirit”

Campaign Triggering

Campaign triggering is supported for object custom event properties only. To use these properties to trigger a campaign, select your custom event, and add a Nested Object Property filter.

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

Triggering Campaign

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

Triggering Campaign

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

Frequently Asked Questions

Does this consume additional data points?

Array properties are treated the same as other event type properties, so there is no change in how we charge data points as a result of adding this capability.

How much data can be sent in the array?

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!