Registration Updates Via Contact Key, Attributes, and Tags
Upon initial configuration of the SDK (after app installation and first launch), a MobilePush registration will be sent immediately to Marketing Cloud. Subsequent registration changes will be sent as described below.
The SDK will send changes to the Marketing Cloud servers within one minute of the first change to any Marketing Cloud MobilePush device or contact registration record and no more frequently than once per minute after as required. This can be data set by your application like Contact Key, Tags or Attributes or it could be system related and set by the SDK like Time Zone, Locale or Application Version, etc.
If the registration update fails the SDK will retry using a backoff algorithm with increasing retry intervals to a maximum delay of 1 day at which point the SDK will retry daily until it is successful.
It will take up to 15 minutes for the registration data to be propagated throughout the Marketing Cloud servers and services once the REST call is successfully completed by the SDK.
NOTE: The SDK is considered the source of truth with regards to the contact’s device registration. Data is replicated 1-way from the SDK to the Marketing Cloud servers.
NOTE: Only modify the contact record while your UI is in the foreground - not the background. This will optimize API calls to the Marketing Cloud servers. For instance, setting an Attribute like “LastAppUsed” to a date-timestamp upon successful SDK initialization will result in an updated registration record every time the SDK is initialized. If your app is backgrounded the SDK may initialize to show a notification or pre-cache messages. This will result in unnecessary communication with the Marketing Cloud servers.
Delay Registration Until Contact Key is Set
You can configure the SDK in a mode that delays registration until a contact key is set by the application. Use this configuration mode only in implementations where the device running your app is tied to a specific contact key in Marketing Cloud and not to a generic device contact.
For more information about configuring the SDK, review Configure the SDK.
To enable delay registration, use the
sfmc_setDelayRegistrationUntilContactKeyIsSet (< v8.0.0) or
setDelayRegistrationUntilContactKeyIsSet method in your configuration builder.
Or, in Objective-C, use the builder with
Listen To Registration Events
Register a callback that will be notified when Registration related events happen. You can also unregister a callback once the callback has been triggered.
The following represents a non-exhaustive list of keys available within the dictionary:
- push_Enabled - Flag indicating whether push notification features are enabled
- quietPushEnabled - Flag indicating whether or not quiet push is enabled
- location_Enabled - Flag indicating if location features are enabled
- proximity_Enabled - Flag indicating proximity features are enabled
- attributes - An array of key/value pairs representing attributes for a contact
- tags - Array of tags set by the SDK
- subscriberKey - Contact key
- device_Token - Device token provided by APNS
- deviceID - Device ID
- timeZone - Offset in seconds relative to UTC time,
- dST - Flag indicating whether or not daylight savings is in effect
- locale - locale,
- language - locale code
- platform - Platform the application is running on
- platform_Version - Version of the platform the application is running on
- app_Version - Application version
- sdk_Version - Version of MobilePush SDK
- hwid - Hardware
- etAppId - MarketingCloud Application ID
- registrationId - Registration ID
"quietPushEnabled" : false,
"location_Enabled" : true,
"registrationId" : "1eb8c21d-ca72-41ac-930d-cec9a311d699",
"timeZone" : "-14400",
"locale" : "en_US",
"etAppId" : " 995k5k1j-162l-4n5m-j4lo-jl5mmnk14n47",
"attributes" : [
"key" : "CODE",
"value" : "FREE99"
"proximity_Enabled" : true,
"subscriberKey" : "email@example.com",
"platform" : "iOS",
"sdk_Version" : "8.0.8",
"language" : "en_US",
"app_Version" : "32.1.4",
"deviceID" : "1EB8C21D-CA72-41AC-930D-CEC9A311D699",
"tags" : [
"hwid" : "iPhone13",
"push_Enabled" : true,
"device_Token" : "t22wrs6vr221rr29r671412s5vwuruwwsu8s48rs274t7tr3s771w7t9v32vus41",
"dST" : true,
"platform_Version" : "15.6"
Contact key is the unique identifier used to aggregate a contact’s devices within Marketing Cloud. Set the contact key to a specific value provided by your customer or to another unique identifier for the contact, such as mobile number, email address, customer number, or another value.
Contact Key can’t be null and can’t be an empty string. Leading or trailing whitespace is removed. After you set the contact key for a contact, you can change it, but you can’t clear it. Don’t set the contact key to a generic, non-unique value.
If your app doesn’t set the contact key using
sfmc_setContactKey:, Marketing Cloud uses the registration sent with a contact record that matches the system token included in the registration payload. If Marketing Cloud doesn’t find a match, it sets a new contact key and doesn’t send the value back to the SDK.
You can use attributes to segment your audience and personalize your messages. Before you can use attributes, create them in your MobilePush account. Attributes may only be set or cleared by the SDK. See the Reserved Words section for a list of attribute keys that can’t be modified by the SDK or your application.
The attribute key can’t be one of the reserved words; it can’t be null or an empty string; and whitespace is trimmed.
The attribute value can’t be null, and whitespace is trimmed.
For additional convenience methods to manage attributes, see MarketingCloudSDK+Base.h.
You can use tags to segment your audience. Tags are commonly used to allow customers to express their interests. For example, a news app offers predefined article categories, such as sports, headlines, and entertainment. App users select the categories, or tags, that they want to receive notifications for.
Dynamically add and remove tags via the SDK. You don’t have to create tags in Marketing Cloud.
Tags can’t be null or an empty string, and whitespace is trimmed.
For additional convenience methods to manage Tags, see MarketingCloudSDK+Base.h.
The SDK ignores calls to modify values associated with the following attribute keys because these attributes are reserved for internal use.
What is an orphaned contact?
An orphaned contact is a contact that is no longer targetable by the marketer due to the contact becoming disassociated with any known devices in the Marketing Cloud.
Common causes of orphaned contacts
- Initializing the SDK without setting the
truein an app that will eventually associate the device users with a known identifier.
- The first launch of the app the SDK will send a registration to the Marketing Cloud. This will be done before it would be possible for the customer to set a contact key.
- Upon receiving a registration payload without a contact key, the Marketing Cloud will generate one for the device. (eg. abc123)
- At a point in the future (let’s say once the user logs into their account in the application) the app sets the known contact key in the registration.
- The device will now send a new registration payload to the Marketing Cloud, a new contact will be created and the device will become associated with the new contact.
- The application allows for multiple users, for example, a banking app, where each user can log into the application and are targeted as individual users.
- User A logs into their account in the banking app and the application sets the contact key in the registration to firstname.lastname@example.org.
- The Marketing Cloud creates a contact for User A in the contact record for the customer’s MC App.
- At a point in the future User B logs into their account on the same device and the application sets the contact key in the registration to email@example.com.
- The Marketing Cloud creates a contact for User B in the contact record and associates the device with that contact. The contact for User A no longer has an association with a targettable device and is now considered “orphaned.”
Avoiding orphaned contacts
Depending on the design/usage of an application, orphaned contacts may not be entirely avoidable. However, the likelihood of an orphaned contact being created can be reduced by using the
sfmc_setDelayRegistrationUntilContactKeyIsSet configuration flag when initializing the SDK.
The default value for
false, but if a developer sets the flag to
true the SDK will not send a registration request to the Marketing Cloud until a contact key has been set by the application. For new installs of the application, this will prevent an unknown contact from being created in the Marketing Cloud.
How is billing affected by orphaned contacts?
Each Contact with a unique ContactKey/SubscriberKey is counted as a Distinct Contact for billing purposes.