Custom events

This article describes custom events and properties, related segmentation filters, Canvas entry properties, relevant analytics, and more. To learn about Braze events in general, refer to Events.

Custom events are actions taken by, or updates about, your users. When custom events are logged, they can trigger any number and type of follow-up campaigns. You can then use segmentation filters to segment users based on how recently and frequently those custom events occurred. This makes custom events best suited for tracking high-value user interactions within your application.

Use cases

Some common custom event use cases include:

• Triggering a campaign or Canvas based on a custom event using action-based delivery
• Segmenting users by how many times they performed a custom event, when the last time the event occurred, and similar
• Using dashboard custom event analytics to view an aggregate of how often each event occurred
• Finding additional analytics using funnel and retention reports
• Leveraging persistent entry properties to use metadata from your customer event for personalization in your Canvas steps
• Generating more sophisticated analytics with Currents
• Setting up Canvas exception events to define when users shouldn’t advance to the next step of your Canvas

Managing custom events

You can manage, create, or blocklist custom events in the dashboard by going to Data Settings > Custom Events.

Select the menu next to a custom event for the following actions:

Blocklisting

You can blocklist individual custom events through the actions menu, or select and blocklist up to 10 events in bulk.

When you block a custom event:

• Future data won’t be collected for that event.
• Existing data won’t be available unless that event is unblocked.
• That event won’t show up in filters or graphs.

Additionally, if a blocked custom event is currently referenced by filters or triggers in other areas of Braze, a warning modal will appear explaining that all instances of the filters or triggers that reference it will be removed and archived.

Adding descriptions

You can add a description to a custom event after it’s created if you have the Manage Events, Attributes, Purchases user permission. Select Edit description for the custom event and input whatever you like, such as a note for your team.

Adding tags

You can add tags to a custom event after it’s created if you have the “Manage Events, Attributes, Purchases” user permission. The tags can then be used to filter the list of events.

Viewing usage reports

The usage report lists all the Canvases, campaigns, and segments using a specific custom event. The list doesn’t include uses of Liquid.

You can view up to 10 usage reports at a time by selecting the checkboxes for multiple custom events and then selecting View usage report.

Exporting data

To export the list of custom events as a CSV file, select the Export all button at the top of the page. The CSV file will be generated, and a download link will be emailed to you.

Logging custom events

Custom events require additional setup. Refer to the list below for documentation about each platform, where you’ll find information about the methods used to log custom events and how to add properties and quantities to your custom events.

Custom event storage

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

Segmentation filters

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

Analytics

Braze notes the number of times custom events have occurred and the last time they were performed by each user for segmentation. View these analytics by going to Analytics > Custom Events Report.

On the Custom Events Report page in the dashboard, you can view in aggregate how often each custom event occurs. The gray lines overlayed on the time series indicate the last time a campaign was sent, which is useful for viewing how your campaigns affected custom event activity.

You can also use Filters to break down your custom events by hour, monthly average users (MAU), segments, or KPI formulas.

Why custom events analytics aren’t showing

Segments created with custom event data can’t show previous historical data from before they were created.

Custom event properties

Custom event properties are custom event metadata or attributes that describe a specific occurrence of an event. These properties can be used for further qualifying trigger conditions, increasing personalization in messaging, tracking conversions, and generating more sophisticated analytics through raw data export.

Custom event properties aren’t stored on the Braze profile and therefore don’t consume data points (see Data points for exceptions).

Expected format

The property 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:

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

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.

Using custom event properties

Custom event properties can be used to qualify campaign triggers, track conversions, and personalize messaging.

Trigger messages

Use custom event properties to further narrow your audience for a particular campaign or Canvas. For example, if you have an ecommerce application and want to send a message to a user when they abandon their cart, you can add a custom event property of cart value to improve your target audience and allow for increased campaign personalization.

Nested custom event properties are also supported in action-based delivery.

Personalize messages

You can also use custom event properties 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.

For example, if you have a gaming app and want to send a message to users who completed a level, you could further personalize your 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}}}.

1
2
3
4
5
6
7
{% if {{event_properties.${time_spent}}} < 600 %}
Incredible work, hero! Are you ready to test your skills against other powerful heroes? Visit the Arena for real-time battles with top players from around the globe.
{% elsif {{event_properties.${time_spent}}} < 1800 %}
Great job, hero! Don't forget to visit the town store between levels to upgrade your tools.
{% else %}
Well done, hero! Talk to villagers for tips on how to beat levels faster and unlock more rewards.
{% endif %}

For a full list of Liquid tags that will cause in-app messages to deliver as templated in-app messages, refer to Frequently asked questions.

Considerations with filters

• API calls: When making API calls and using the “is blank” filter, a custom event property is considered “blank” if excluded from the call. For example, if you were to include "event_property": "", then your users would be considered “not blank”.
• Integers: When filtering for a number custom event property and the number is very large, don’t use the “exactly” filter. If a number is too large, it may be rounded at a certain length, so your filter won’t work as expected.

Segmentation

Use event property segmentation to target users based on custom events taken and the properties associated with those events. This increases your filtering options when segmenting by purchase and custom events.

Event properties for custom events are updated in real-time for any segment that uses them. You can manage properties by going to Data Settings > Custom Events and selecting Manage Properties for the associated custom event. Custom event properties used in certain segment filters have a maximum look-back history of 30 days.

The event property segmentation filters include:

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

Data is only logged for a given event property after it has been enabled by your customer success manager, and event properties are only available from that date moving forward.

Data points

In regards to subscription usage, custom event properties enabled for segmentation with the following filters are all counted as separate data points in addition to the data point counted by the custom event itself:

• X Custom Event Property in Y Days
• X Purchase Property in Y Days

Canvas entry properties and event properties

You can use canvas_entry_properties and event_properties in your Canvas user journeys. Refer to Canvas entry properties and event properties for more information and examples.

• canvas entry properties
• event properties

1
2
3
4
5
6
{% if  {{canvas_entry_properties.${product_name}}} == "shoes" %}
  Your order is set to ship soon. While you're waiting, why not step up your shoe care routine with a little upgrade? Check out our selection of shoelaces and premium shoe polish.
{% else %}
  Your order will be on its way shortly. If you missed something, you have until the end of the week to add more items to your cart for the same discounts.
{% endif %}

Nested objects

You can use nested objects (objects 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, triggering message sends, and segmenting users.

To learn more, refer to our dedicated page on Nested objects.

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.

You can segment based on the values of event properties in two ways:

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. 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 segments users based on custom events and event properties tracked within the past two years. This option won’t impact data usage.

Contact your Braze customer success manager for recommendations on the best approach depending on your specific needs.