Set Contact Attributes and Tags

Attributes are key-value pairs that you can use to segment your audience and personalize your messages. Examples of attributes include first name, last name, loyalty level, channel preference, signup date, birthday, ZIP code, or a unique identifier.

Tags are categories that let your audience express their interests or preferences and what they want to receive notifications about. For example, a news app can offer article categories, or tags, for users to follow, such as sports, headlines, and entertainment. App users select the tags they’re interested in.

When deciding on your segmentation and personalization strategy, it's important to understand the roles of tags and attributes in Marketing Cloud Engagement.


Use tags as a complement to attributes. Tags are a device-specific way to collect small amounts of information to use for segmentation. Unlike attributes, you don’t have to define tags in Engagement before the SDK submits values for them. Tags are registered to the MobilePush Tags table in Contact Builder.


Attributes are the common standard for segmentation and personalization across all Engagement channel types. Attributes are more descriptive than tags and are the primary way to segment demographic data. You can change and update attributes.

Before the SDK can submit values for attributes, you must first define MobilePush attributes in the MobilePush Demographics table in Contact Builder. It’s critical that the SDK submits attributes with the exact same name as defined on the server. If there’s a mismatch, then Engagement can reject the entire registration.

If you want your app to use custom attributes, create and define them in Engagement. The MobilePush Demographics table is tied to your organization’s Engagement data model. Before making any changes, consult with your marketing team.

  1. In Engagement, navigate to Audience Builder > Contact Builder.
  2. In Data Designer, select the MobilePush Data attribute group.
  3. Review the MobilePush Demographics table for available attributes.
  4. Select an attribute to review its schema or data type.
  5. Create and define a new custom attribute by clicking the button at the bottom of the MobilePush Demographics table.

Create an Attribute that represents ContactKey. Due to data model constraints, MobilePush doesn’t natively allow customers to query the tables for the actual ContactKey. As a solution-workaround, it’s best to create an Attribute that represents the ContactKey and have the SDK set a value for it. You can then query, join, or segment against it. For guidance on setting attributes, see Set or Clear Attributes.

Only the SDK can set or clear attribute key-value pairs; you can’t set or clear them in Engagement. The attribute key can’t be one of the reserved words, and it can’t be null or an empty string. The attribute value can’t be null. Whitespace is trimmed from both the key and the value.

To set an attribute key-value pair, follow the example code provided in the following sections.

  • To use a date format, you must format the attribute key-value pair using ISO 8601. Examples of valid date formats are: 2024-05-07T13:28:31Z or 2024-05-07T13:28:31+00:00.
  • If you set an attribute, such as DateSignedUp, to a datetime stamp after successful SDK initialization, the registration record gets updated every time the SDK initializes.
  • Never set an attribute with a constantly changing datetime stamp. For example, never set an attribute that tracks LastUserInteraction. Doing so adds a tremendous amount of pressure on the Engagement servers.

If you want your app to use tags, add or remove them via the SDK. Tags can’t be null or an empty string. Whitespace is trimmed.

Attempts to set or clear attributes with any of the following reserved words are ignored.