Common Terminology

The MobilePush SDK uses terminology that aligns with industry standards.

Anonymous Contact

Using the SDK to set the contact key is optional because an app can lack information about a user’s identity. Many SDK users don’t set the contact key. In this scenario, the SDK doesn’t register a contact key. As a result, Marketing Cloud assigns a random GUID as the contact key. Contacts with a random contact key are referred to as Anonymous Contacts.

When the app later discovers who the user is and decides to set the contact key, the SDK registers the contact key. In these cases, Marketing Cloud migrates the device to this new contact key. As a result, the original contact (represented by the GUID) loses any association to the device and becomes an orphaned contact.

Asynchronous

With the SDK installed on billions of devices, we try to minimize contact between the SDK and Salesforce servers. As a result, the SDK primarily uses asynchronous, “fire-and-forget” REST API calls for registration and analytics. In these types of requests, 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 around registration. If you use the SDK to register a contact attribute that isn’t formatted correctly, you can still receive a success response from the server. However, this response 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 then rejects it. This rejection can result in the loss of critical information such as contact key, device token, and other attributes contained in the registration.

Contact Attributes

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 channels. Examples of contact attributes include first name, last name, loyalty level, channel preference, signup date, birthday, ZIP code, or a unique identifier.

Marketing Cloud Engagement stores these values on the MobilePush Demographics table within Contact Builder. These contact attributes must be defined in Contact Builder before the SDK assigns a value and registers the data with the Engagement server.

Marketing Cloud Next stores contact attributes on the Individual data model object (DMO).

Device Token

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, the SDK collects this device token and submits it to Marketing Cloud as part of the registration process. The device token is similar to both an address and an access code. Apple and Google use the device token to route push notifications to the correct device and to track its validity, including the recipient’s opt status.

Initialization

The process where the SDK begins to load its settings as the app starts up. To function properly, the SDK must fully initialize. The SDK’s initialization can start from the main thread, because its underlying implementation does its own processing on a separate initialization thread.

Local Contact Model

The SDK stores its own copy of the contact model, which is used to update the attributes in Marketing Cloud. The SDK sends registration requests asynchronously, so there isn’t a synchronization mechanism between the SDK and Marketing Cloud. The SDK is unaware of how the table is configured in Marketing Cloud.

Registration

The process where the SDK issues a REST API call to send critical information to Marketing Cloud Next or Marketing Cloud Engagement. The registration process facilitates the transfer of devices, contacts, device tokens, attributes, and similar information. This information determines whether Marketing Cloud can send a message to a contact.