MarketingCloudSDK iOS (v8.1.3) : Device and Contact Registration

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.

Configure

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 sfmc_setDelayRegistrationUntilContactKeyIsSet:@(YES).

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.

Registration Object

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

Example

{
  "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" : "contactkey@example.com",
  "platform" : "iOS",
  "sdk_Version" : "8.0.8",
  "language" : "en_US",
  "app_Version" : "32.1.4",
  "deviceID" : "1EB8C21D-CA72-41AC-930D-CEC9A311D699",
  "tags" : [
    "ALL",
    "DEBUG",
    "DISCOUNT",
    "IOS"
  ],
  "hwid" : "iPhone13",
  "push_Enabled" : true,
  "device_Token" : "t22wrs6vr221rr29r671412s5vwuruwwsu8s48rs274t7tr3s771w7t9v32vus41",
  "dST" : true,
  "platform_Version" : "15.6"
}

Contact Key

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.

Attributes

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.

Reserved Words

The SDK ignores calls to modify values associated with the following attribute keys because these attributes are reserved for internal use.

Orphaned Contacts

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 sfmc_setDelayRegistrationUntilContactKeyIsSet flag to true in an app that will eventually associate the device users with a known identifier.
1. 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.
2. Upon receiving a registration payload without a contact key, the Marketing Cloud will generate one for the device. (eg. abc123)
3. 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.
4. 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.
1. User A logs into their account in the banking app and the application sets the contact key in the registration to user.a@example.com.
2. The Marketing Cloud creates a contact for User A in the contact record for the customer’s MC App.
3. 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 user.b@example.com.
4. 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 sfmc_setDelayRegistrationUntilContactKeyIsSet is 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.