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 you determine your segmentation and personalization strategy, it’s important to understand the roles of tags and attributes in Marketing Cloud Engagement. Attributes are the common standard for segmentation and personalization across all channel types. Attributes are more descriptive than tags and are the primary way to segment demographic data. You can change and update attributes. Before you set attributes, first define them in Contact Builder. The SDK rejects registrations that include attributes that aren’t defined in Contact Builder.

Tags are a complement to attributes. Tags are a device-specific way to collect small amounts of information to use for segmentation. Unlike attributes, it isn’t necessary to define tags in Marketing Cloud before the SDK submits values for them. Tags are registered to the MobilePush Tags table in Contact Builder.

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 Contact Builder, select the Data Designer tab.
  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. To add an attribute, click Create Attribute.

As a best practice, 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. 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 a reserved word, empty, or null. The attribute value can’t be null. The SDK trims whitespace from the beginning and end of the key and the value.

Keep these requirements in mind when you set or clear attributes.

  • Specify dates in ISO 8601 format, such as 2024-05-07T13:28:31+00:00.
  • If you set an attribute to a datetime stamp after the SDK successfully initializes, the registration record is updated every time the SDK initializes.
  • Don't create an attribute with a datetime value that constantly changes. For example, never set an attribute that tracks LastUserInteraction. Constantly changing attribute values negatively impacts performance.

This code example shows how to set or clear attributes in the MobilePush SDK for Android.

This code example shows how to set or clear attributes in the MobilePush SDK for Android apps that use SDK version 8.

This code example shows how to set or clear attributes in the MobilePush SDK for iOS that use SDK version 10 and later.

For earlier versions of the SDK, use this code.

If you want your app to use tags, use the SDK to add or remove them. Tags can’t be empty or null. The SDK trims whitespace from the beginning and end of the tag.

This code example shows how to add or remove tags in the MobilePush SDK for Android.

This code example shows how to add or remove tags in the MobilePush SDK for Android apps that use SDK version 8.

This code example shows how to add or remove tags on MobilePush SDK for iOS version 10 and later.

This code example shows how to add or remove tags on earlier versions of the MobilePush SDK for iOS.

Some words are reserved and can’t be used as attribute names. The SDK ignores attempts to set or clear attributes that contain any of these words.

  • addressId
  • alias
  • apId
  • backgroundRefreshEnabled
  • badge
  • channel
  • contactId
  • contactKey
  • createdBy
  • createdDate
  • customObjectKey
  • device
  • deviceId
  • deviceType
  • gcmSenderId
  • hardwareId
  • hwid
  • isHonorDst
  • lastAppOpen
  • lastMessageOpen
  • lastSend
  • locationEnabled
  • messageOpenCount
  • modifiedBy
  • modifiedDate
  • optInDate
  • optInMethodId
  • optInStatusId
  • optOutDate
  • optOutMethodId
  • optOutStatusId
  • platform
  • platformVersion
  • providerToken
  • proximityEnabled
  • pushAddressExtensionId
  • pushApplicationId
  • quietPushEnabled
  • sdkVersion
  • sendCount
  • signedString
  • source
  • sourceObjectId
  • status
  • systemToken
  • timezone
  • utcOffset