Setting Custom Attributes

Braze provides methods for assigning attributes to users. You’ll be able to filter and segment your users according to these attributes on the dashboard.

Before implementation, be sure to review examples of the segmentation options afforded by Custom Events vs. Custom Attributes vs Purchase Events in our Best Practices section.

Assigning Standard User Attributes

To assign user attributes, you need to set the appropriate field on the shared ABKUser object. For example, to assign the current user’s first name to be “Jeff,” you would use the following line of code:

1
[Appboy sharedInstance].user.firstName = @"Jeff";
1
Appboy.sharedInstance().user.firstName = "Jeff"

The following attributes should be set on the ABKUser object:

  • firstName
  • lastName
  • email
  • dateOfBirth
  • country
  • language
  • homeCity
  • bio
  • phone
  • userID
  • avatarImageURL
  • twitterAccountIdentifier
  • gender

We strongly recommend collecting email addresses even if you’re not sending emails through Braze. Email makes it easier to search for individual user profiles and troubleshoot issues as they arise.

Assigning Custom User Attributes

Beyond the attributes above, Braze also allows you to define Custom Attributes using a number of different data types: For more information regarding the segmentation options each of these attributes will afford you see our “Best Practices” documentation within this section.

Custom Attribute with a Boolean Value

1
[[Appboy sharedInstance].user setCustomAttributeWithKey:@"your-attribute-string" andBOOLValue:yourBOOLValue];
1
Appboy.sharedInstance().user.setCustomAttributeWithKey("your-attribute-string", andBOOLValue: yourBoolValue)

Custom Attribute with an Integer Value

1
[[Appboy sharedInstance].user setCustomAttributeWithKey:@"your-attribute-string" andIntegerValue:yourIntegerValue];
1
Appboy.sharedInstance().user.setCustomAttributeWithKey("your-attribute-string", andIntegerValue: yourIntegerValue)

Custom Attribute with a Double Value

1
[[Appboy sharedInstance].user setCustomAttributeWithKey:@"your-attribute-string" andDoubleValue:yourDoubleValue];
1
Appboy.sharedInstance().user.setCustomAttributeWithKey("your-attribute-string", andDoubleValue: yourDoubleValue)

Braze treats FLOAT and DOUBLE values exactly the same within our database.

Custom Attribute with a String Value

1
[[Appboy sharedInstance].user setCustomAttributeWithKey:@"your-attribute-string" andStringValue:"Your String"];
1
Appboy.sharedInstance().user.setCustomAttributeWithKey("your-attribute-string", andStringValue: "Your String")

Custom Attribute with a Date Value

1
[[Appboy sharedInstance].user setCustomAttributeWithKey:@"your-attribute-string" andDateValue:yourDateValue];
1
Appboy.sharedInstance().user.setCustomAttributeWithKey("your-attribute-string", andDateValue:yourDateValue)

Dates passed to Braze with this method must either be in the ISO 8601 format, e.g 2013-07-16T19:20:30+01:00 or in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format e.g 2016-12-14T13:32:31.601-0800

Custom Attribute with an Array Value

The maximum number of elements in Custom Attribute Arrays defaults to 25. The maximum for individual arrays can be increased to up to 100 in the Braze Dashboard, under “Manage App Group -> Custom Attributes”. Arrays exceeding the maximum number of elements will be truncated to contain the maximum number of elements. For more information on Custom Attribute Arrays and their behavior, see our Documentation on Arrays.

1
2
3
4
5
6
7
8
// Setting a custom attribute with an array value
[[Appboy sharedInstance].user setCustomAttributeArrayWithKey:@"array_name" array:@[@"value1",  @"value2"]];
// Adding to a custom attribute with an array value
[[Appboy sharedInstance].user addToCustomAttributeArrayWithKey:@"array_name" value:@"value3"];
// Removing a value from an array type custom attribute
[[Appboy sharedInstance].user removeFromCustomAttributeArrayWithKey:@"array_name" value:@"value2"];
// Removing an entire array and key
[[Appboy sharedInstance].user setCustomAttributeArrayWithKey:@"array_name" array:nil];
1
2
3
4
5
6
// Setting a custom attribute with an array value
Appboy.sharedInstance().user.setCustomAttributeArrayWithKey("array_name", array: ["value1",  "value2"])
// Adding to a custom attribute with an array value
Appboy.sharedInstance().user.addToCustomAttributeArrayWithKey("array_name", value: "value3")
// Removing a value from an array type custom attribute
Appboy.sharedInstance().user.removeFromCustomAttributeArrayWithKey("array_name", value: "value2")

Unsetting a Custom Attribute

Custom Attributes can also be unset using the following method:

1
[[Appboy sharedInstance].user unsetCustomAttributeWithKey:@"your-attribute-string"];
1
Appboy.sharedInstance().user.unsetCustomAttributeWithKey("your-attribute-string")

Incrementing/Decrementing Custom Attributes

This code is an example of an incrementing custom attribute. You may increment the value of a custom attribute by any positive or negative integer or long value.

1
[[Appboy sharedInstance].user incrementCustomUserAttribute:@"Attribute Key" by:incrementIntegerValue];
1
Appboy.sharedInstance().user.incrementCustomUserAttribute("Attribute Key", by: incrementIntegerValue)

Setting a Custom Attribute via the REST API

You can also use our REST API to set user attributes. To do so refer to the user API documentation.

Custom Attribute Value Limits

Custom attribute values have a maximum length of 255 characters; longer values will be truncated.

Implementation Example

User Attributes are set within the UserAttributesViewController.m file within the Stopwatch sample application.

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 ABKNotificationSubscriptionType as arguments. This type has three different states:

Subscription Status Definition
ABKOptedin Subscribed, and explicitly opted in
ABKSubscribed Subscribed, but not explicitly opted in
ABKUnsubscribed Unsubscribed and/or explicitly opted out

Users who grant permission for an app to send them push notifications are defaulted to the status of ABKOptedin as iOS requires an explicit opt in.

Users will be set to ABKSubscribed automatically upon receipt of a valid email address, however we suggest that you establish an explicit opt-in process and set this value to OptedIn upon receipt of explicit consent from your user. See Braze Academy for details.

Setting Email Subscriptions

1
[[Appboy sharedInstance].user setEmailNotificationSubscriptionType: ABKNotificationSubscriptionType]
1
Appboy.sharedInstance().user.setEmailNotificationSubscriptionType(ABKNotificationSubscriptionType)

Setting Push Notification Subscriptions

1
[[Appboy sharedInstance].user setPushNotificationSubscriptionType: ABKNotificationSubscriptionType]
1
Appboy.sharedInstance().user.setPushNotificationSubscriptionType(ABKNotificationSubscriptionType)

Users who grant permission for an app to send them push notifications are defaulted to the status of ABKOptedin as iOS requires an explicit optin.

For more information on implementing subscriptions, visit the topic on Braze Academy.

WAS THIS PAGE HELPFUL?