Common Terminology

The SDK, as part of application startup, is waking up and loading its configuration and settings. It must fully initialize in order to function properly. The SDK's initialization can safely be started from the main thread as its underlying implementation does all its own processing on a separate initialization thread.

A REST API call the SDK uses to send critical information to Marketing Cloud Engagement. The registration process facilitates the transfer of devices, contacts, device tokens, attributes, and similar information to Engagement, ultimately determining whether Engagement can send a message to a Contact.

When a user opts into receiving push notifications from an app, their phone's operating system assigns a unique token that allows vendors to send push notifications to that device. By default, our SDK collects this device token and submits it to Engagement as part of registration.

Think of the device token as both an address and an access code. Apple and Google use the device token to route push notifications to the right device and to track its validity, including whether the user is opted in or opted out.

Contact attributes are key-value pairs that you can use to segment your audience and personalize your messages. Contact attributes serve as the common standard for segmentation and personalization across all Engagement channels. MobilePush stores these values on the MobilePush Demographics table within the Contact Builder app. These contact attributes must be defined in Contact Builder before the SDK assigns a value and registers the data with the Engagement server.

Examples of contact attributes include first name, last name, loyalty level, channel preference, signup date, birthday, ZIP code, or a unique identifier.

The SDK stores its own version of the contact model. It’s how customers use the SDK to update attributes on the MobilePush Demographics table within Contact Builder. However, because the SDK sends registrations asynchronously, there’s no sync mechanism between the SDK and the Engagement servers. The SDK is unaware of how the MobilePush Demographics table is configured. As such, the SDK only knows what the app tells it and communicates updates to MobilePush Demographics in a one-way fashion.

With the SDK installed on billions of uncontrollable devices, we try to minimize contact between the SDK and the Engagement servers. As a result, the SDK primarily employs asynchronous, “fire-and-forget” REST API calls for registration and analytics. Here, the SDK only waits to see if the server received the API call and doesn't receive any other information about the validity or processing of the payload.

The asynchronous nature of the SDK can lead to confusion during implementation, primarily around registration. If a customer uses the SDK to register a malformed contact attribute, they can still observe an apparent success from the server. However, this “success” only confirms that the server received the API call, not that it processed it successfully. In this scenario, the server attempts to process the registration and rejects the entire registration due to the malformed attribute. This rejection can result in the loss of critical information such as ContactKey, device token, and other attributes contained in the registration.

Setting the ContactKey via the SDK is entirely optional because an app can lack information about a user's identity. In fact, many MobilePush customers don’t set the ContactKey. In this scenario, the SDK doesn't register a ContactKey. As a result, the Engagement servers assign a random GUID as the ContactKey to associate with the device. Since their identity is unknown, we refer to such contacts as Anonymous Contacts.

When the app later discovers who the user is and decides to set the ContactKey, the SDK registers the ContactKey with Engagement servers accordingly. In such cases, Engagement migrates the device to this new ContactKey. As a result, the original contact (represented by the GUID) loses any association to the device and becomes an orphaned contact (a contact without any DeviceID).