Setting custom attributes

Braze provides methods for assigning attributes to users. You can filter and segment your users according to these attributes on the dashboard.

Before implementation, review examples of the segmentation options afforded by custom events, custom attributes, and purchase events in our Best practices.

To assign attributes to your users, call the braze.getUser() method to get a reference to the current user of your app. After you have a reference to the current user, you can call methods to set predefined or custom attributes.

Assigning predefined user attributes

Braze provides predefined methods for setting the following user attributes within the User class:

• First Name
• Last Name
• Language
• Country
• Date of Birth
• Email
• Gender
• Home City
• Phone Number

Implementation examples

Setting a first name

1
braze.getUser().setFirstName("SomeFirstName");

Setting a gender

1
braze.getUser().setGender(braze.User.Genders.FEMALE);

Setting a date of birth

1
braze.getUser().setDateOfBirth(2000, 12, 25);

Assigning custom user attributes

In addition to our predefined user attribute methods, Braze also provides custom attributes to track data from your applications.

Full method specifications for custom attributes can be found here within the JSDocs.

Custom attribute length

Custom attribute keys and values have a maximum length of 255 characters. Refer to the full technical documentation for details about valid custom attribute values.

Implementation examples

Setting a custom attribute with a string value

1
2
3
4
braze.getUser().setCustomUserAttribute(
  YOUR_ATTRIBUTE_KEY_STRING,
  YOUR_STRING_VALUE
);

Setting a custom attribute with an integer value

1
2
3
4
5
6
7
8
9
10
braze.getUser().setCustomUserAttribute(
  YOUR_ATTRIBUTE_KEY_STRING,
  YOUR_INT_VALUE
);

// Integer attributes may also be incremented using code like the following
braze.getUser().incrementCustomUserAttribute(
  YOUR_ATTRIBUTE_KEY_STRING,
  THE_INTEGER_VALUE_BY_WHICH_YOU_WANT_TO_INCREMENT_THE_ATTRIBUTE
);

Setting a custom attribute with a date value

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
braze.getUser().setCustomUserAttribute(
  YOUR_ATTRIBUTE_KEY_STRING,
  YOUR_DATE_VALUE
);

// This method will assign the current time to a custom attribute at the time the method is called
braze.getUser().setCustomUserAttribute(
  YOUR_ATTRIBUTE_KEY_STRING,
  new Date()
);

// This method will assign the date specified by secondsFromEpoch to a custom attribute
braze.getUser().setCustomUserAttribute(
  YOUR_ATTRIBUTE_KEY_STRING,
  new Date(secondsFromEpoch * 1000)
);

Dates passed to Braze with this method must be JavaScript Date objects.

Setting a custom attribute with an array value

The maximum number of elements in custom attribute arrays defaults to 25. Individual arrays can be increased up to 100 in the Braze dashboard under Data Settings > Custom Attributes. If you want this maximum increased, contact your customer service manager. Arrays exceeding the maximum number of elements will be truncated to contain the maximum number of elements.

1
2
3
4
5
6
7
braze.getUser().setCustomUserAttribute(YOUR_ATTRIBUTE_KEY_STRING, YOUR_ARRAY_OF_STRINGS);

// Adding a new element to a custom attribute with an array value
braze.getUser().addToCustomAttributeArray(YOUR_ATTRIBUTE_KEY_STRING, "new string");

// Removing an element from a custom attribute with an array value
braze.getUser().removeFromCustomAttributeArray(YOUR_ATTRIBUTE_KEY_STRING, "value to be removed");

Unsetting a custom attribute

Custom attributes can be unset by setting their value to null.

1
braze.getUser().setCustomUserAttribute(YOUR_ATTRIBUTE_KEY_STRING, null);

Setting a custom attribute via the REST API

You can also use our REST API to set user attributes. Refer to the users API documentation for details.

Setting up user subscriptions

To set up a subscription for your users (either email or push), call the functions setEmailNotificationSubscriptionType() or setPushNotificationSubscriptionType(), respectively. Both of these functions take the enum type braze.User.NotificationSubscriptionTypes as arguments. This type has three different states:

When a user is registered for push, the browser forces them to choose to allow or block notifications, and if they choose to allow push, they are set OPTED_IN by default.

Visit Managing user subscriptions for more information on implementing subscriptions and explicit opt-ins.

Example code

Unsubscribing a user from email:

1
braze.getUser().setEmailNotificationSubscriptionType(braze.User.NotificationSubscriptionTypes.UNSUBSCRIBED);

Unsubscribing a user from push:

1
braze.getUser().setPushNotificationSubscriptionType(braze.User.NotificationSubscriptionTypes.UNSUBSCRIBED);