Skip to content

Braze Learning courseCustom events

Custom events are actions taken by, or updates about, your users. They’re best suited for tracking high-value user interactions within your application. Logging a custom event can trigger any number and type of follow-up campaigns, and enables the listed segmentation filters on the recency and frequency of that event.

Managing custom events

To create and manage custom events in the dashboard, go to Manage Settings > Custom Events. From this page, you can view, manage, or blocklist existing custom events, or create a new one. If you block a custom event, no data will be collected regarding that event, existing data will be unavailable unless reactivated, and blocklisted events will not show up in filters or graphs.

Logging custom events

The following lists the methods across various platforms that are used to log custom events. Within these pages, you will also be able to find documentation on how to add properties and quantities to your custom events.

Expand for documentation by platform

Custom event storage

All data stored on the User Profile, including custom event metadata (first/last occurrence, total count, and X in Y over 30 days), is retained indefinitely as long as each profile is active.

Custom event segmentation filters

The following table shows the filters available for segmenting users by custom events.

Segmentation Options Dropdown Filter Input Options
Check if the custom event has occurred more than X number of times MORE THAN NUMBER
Check if the custom event has occurred less than X number of times LESS THAN NUMBER
Check if the custom event has occurred exactly X number of times EXACTLY NUMBER
Check if the custom event last occurred after X date AFTER TIME
Check if the custom event last occurred before X date BEFORE TIME
Check if the custom event last occurred more than X days ago MORE THAN NUMBER OF DAYS AGO (Positive Number)
Check if the custom event last occurred less than X days ago LESS THAN NUMBER OF DAYS AGO (Positive Number)
Check if the custom event occurred more than X (Max = 50) number of times MORE THAN in the past Y Days (Y = 1,3,7,14,21,30)
Check if the custom event occurred less than X (Max = 50) number of times LESS THAN in the past Y Days (Y = 1,3,7,14,21,30)
Check if the custom event occurred exactly X (Max = 50) number of times EXACTLY in the past Y Days (Y = 1,3,7,14,21,30)

Custom event analytics

Braze notes the number of times these events have occurred as well as the last time they were performed by each user for segmentation. On the Custom Events page in the dashboard, you can view in aggregate how often each custom event occurs, as well as by segment over time for more detailed analysis. This is particularly useful to view how your campaigns have affected custom event activity by looking at the gray lines Braze overlays on the time series to indicate the last time a campaign was sent.

Custom event counts graph on the Custom Events page in the dashboard showing trends for two different custom events

Custom events analytics not showing?

Note that Segments created with custom event data cannot show previous historic data from before they were created.

Custom event properties

With custom event properties, you can set properties on custom events and purchases. These properties can then be used for further qualifying trigger conditions, increasing personalization in messaging, track conversions, and generating more sophisticated analytics through raw data export.

The properties values should be an object where the keys are the property names and the values are the property values. Property names must be non-empty strings less than or equal to 255 characters, with no leading dollar signs ($).

Property values can be any of the following data types:

Data Type Description
Numbers As either integers or floats
Booleans  
Datetimes Formatted as strings in ISO-8601 or yyyy-MM-dd'T'HH:mm:ss:SSSZ format. Not supported within arrays.
Strings 255 characters or fewer.
Arrays Arrays cannot include datetimes.
Objects Objects will be ingested as strings.
Nested objects Objects that are inside of other objects. For more, see the section in this article on Nested objects.

Event property objects that contain array or object values can have an event property payload of up to 50KB.

For example, if an eCommerce application wanted to send a message to a user when they abandon their cart, it could additionally improve its target audience and allow for increased campaign personalization by adding a custom event property of the ‘cart value’ of users’ carts.

Custom event property filters for an abandoned card. Two filters are combined with an AND operator to send this campaign to users who abandoned their card with a cart value between 100 and 200 dollars

Custom event properties can also be used for personalization within the messaging template. Any campaign using Action-Based Delivery with a trigger event can use custom event properties from that event for messaging personalization. If a gaming application wanted to send a message to users who had completed a level, it could further personalize the message with a property for the time it took users to complete that level. In this example, the message is personalized for three different segments using conditional logic. The custom event property called time_spent, can be included in the message by calling {{event_properties.${time_spent}}}.

You can change the data type of your custom event property, but be aware of the impacts of changing data types after data has been collected.

In regards to subscription usage, custom event properties enabled for segmentation with the filters X Custom Event Property in Y Days or X Purchase Property in Y Days are all counted as separate data points in addition to the data point counted by the custom event itself.

Nested objects

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 can only be sent with custom events and purchase events.
  • Sending nested custom attributes (objects as a custom attribute data type) is limited to customers participating in the early access. For more information, refer to Nested custom 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

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

The following 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 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.

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

Use segment extensions to segment users based on nested event properties. Segmentation uses the same notation as triggering (see Message triggering).

Event property segmentation

Event property segmentation allows you to target users based not just on custom events taken but the properties associated with those events. This feature adds additional filtering options when segmenting purchase and custom events.

These segmentation filters include:

  • Has done custom event with property Y with value V X times in the last Y days.
  • Has made any purchases with property Y with value V X times in the last Y days.
  • Adds the ability to segment within 1, 3, 7, 14, 21, and 30 days.

Unlike with segment extensions, segments used are updated in real-time, support an unlimited amount of segments, offer a look back history of at most 30 days, and incur data points. Because of the additional data point charge, you must reach out to your CSM to get event properties turned on for your custom events. Once approved, additional properties can be added in the dashboard under Manage Settings > Custom Events > Mangage Properties and used in the target step of the campaign or Canvas builder.

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.

Custom event property storage

Custom event properties are designed to help you increase targeting precision and make messages feel even more personalized. Custom event properties can be stored within Braze in both the short and long term.

If you would like to segment on the values of event properties, you have two options:

  1. Within 30 days: Braze support personnel can enable event property segmentation based on the frequency and recency of specific event property values within Braze Segments. If you’d like to leverage event properties within Segments, contact your Braze account executive or customer success manager. Note that this option will impact data usage.

  2. Within and Beyond 30 days: To cover both short-term and long-term event property segmentation, you can use Segment Extensions. This feature enables you to segment based on custom events and event properties tracked within the past year. Note that this option will not impact data usage.

Braze’s Success and Support teams can help recommend the best approach depending on your specific needs.

WAS THIS PAGE HELPFUL?
New Stuff!