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 50 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. Click the icon to generate the schema. To view the schema, click 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
• Liquid templating
• Message triggering
• Segmentation
• Personalization

API request body

• music example
• restaurant example

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"
      }
    }
  ]
}
...

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.

• music example
• restaurant example

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.

• music example
• restaurant example

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