Custom attributes

This page covers custom attributes, which are a collection of your users’ unique traits. Custom attributes are best for storing attributes about your users, or information about low-value actions within your application.

When stored in Braze, custom attributes can be used to build out audience segments and personalize messaging using Liquid. Keep in mind that Braze doesn’t store time-series information for custom attributes, so you can’t get any graphs based on them like you can for custom events.

Use cases

Some common custom attribute use cases include:

• Targeting and suppressing audiences by segmenting users based on traits like loyalty tier, subscription status, preferred language, or plan type
• Personalizing messages with Liquid by referencing attributes such as a user’s first name, rewards points, or favorite category
• Tracking lifecycle stages and user states, such as onboarding stage, account status, or trial end date
• Counting low-value actions with numeric attributes, such as incrementing a feature_views_count attribute each time a user views a feature
• Recording when low-value actions last occurred using time attributes, such as last_support_ticket_at or last_password_reset_at
• Storing user interests and history as arrays, such as favorite genres or recently viewed content, for interest-based targeting
• Storing richer profile data as objects or arrays of objects, such as structured preferences or multiple saved addresses
• Triggering action-based messages when an attribute value changes using attribute triggers, such as sending a tier-up notification when a user’s rewards_tier changes

Managing custom attributes

To create and manage custom attributes in the dashboard, go to Data Settings > Custom Attributes.

The Last updated column lists the last time the custom attribute was edited, such as when it was last set to blocklist or active.

From this page, you can view, manage, create, or blocklist existing custom attributes. Select the menu next to a custom attribute for the following actions:

Blocklisting

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

When you block a custom attribute:

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

Additionally, if a blocked custom attribute 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.

For more details on blocklisting and deleting custom data, see Blocklist custom data.

Marking as personally identifiable information (PII)

Administrators can also create custom attributes and mark them as PII from this page. These attributes are only visible to admins and dashboard users with the “View Custom Attributes Marked as PII” permission.

Adding descriptions

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

Adding tags

You can add tags to a custom attribute 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 attributes.

Removing custom attributes

There are two ways you can remove custom attributes from user profiles:

• Select the custom attribute name to be removed in a User Update step.
• Set the null value in your API request to the /users/track endpoint.

Exporting data

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

Viewing usage reports

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

You can view up to 100 usage reports at a time by selecting the checkboxes next to the respective custom attributes and then selecting View usage report.

Values tab

When viewing a usage report, select the Values tab to view the top values of the selected custom attributes based on a sample of approximately 250,000 users. Note that because the results are sampled from a subset of users, the sample won’t include all existing values. This means the Values tab shouldn’t be used for troubleshooting or for use cases that require incorporating data from all users.

Setting custom attributes

The following lists methods across various platforms that are used to set custom attributes.

Expand for documentation by platform

• Android and FireOS
• iOS
• Web
• React Native
• Unity
• .NET MAUI (formerly Xamarin)
• Roku

Custom attribute storage

All data stored on the User Profile, including custom attribute data, is retained indefinitely as long as each profile is active.

For a full reference of all data types you can store as custom attributes—including booleans, numbers, strings, arrays, time, objects, and arrays of objects—see Custom attribute data types.