How the MobilePush SDK Works

The following sections provide flow charts and high-level explanations of how the SDK interacts with Marketing Cloud Engagement.

1. When a mobile app opens and successfully initializes the SDK, the SDK communicates with the Push Notification Service (PNS) to obtain a device token.

2. The PNS returns a device token to the SDK, but only if the device has opted in to receive push notifications.

3. After receiving the device token, the SDK registers the device with Engagement and submits critical information such as the device token, device ID, push opt-in status, contact key, and any relevant attributes or tags. This registration process occurs asynchronously.

4. Engagement processes the registration to determine whether it can send push notifications to the device. This process includes checking whether the device is opted in our out of receiving push notifications. At this point, if the user is a new contact, Engagement creates a contact record. If the user is an existing contact, Engagement updates the existing contact record with the latest information, such as the user's most recent app open time.

   The registration process can take up to five minutes, after which updated information is visible on the contact's profile in Contact Builder in Marketing Cloud Engagement.

5. After Engagement processes the registration, a marketer sends push notifications using the device token received from the SDK.

6. Device tokens are validated and push notifications are delivered in the following ways:

   a. If the device token is valid, the PNS delivers the message to the device.

   b. If the device token is invalid or if the device is opted out, the PNS notifies Engagement to opt out the contact’s device. The contact also doesn’t receive the push notification. Opt-outs also occur if the device token is malformed or if the auth key is incorrect.

7. After the contact opens and interacts with the push notification, the SDK records the event and sends analytics data to Engagement. The SDK transmits analytics data after the application moves into the background or comes back into the foreground. If a user force-closes the app, the SDK stores the analytics data and sends it to Engagement the next time the user opens the app.

1. The SDK registers the device with Engagement and asynchronously submits critical information such as the device token, device ID, push opt-in status, contact key, and any relevant attributes or tags.

2. Engagement processes the registration to determine whether it can send in-app messages to the device.

   The registration process can take up to five minutes, after which updated information is visible on the contact's profile in Contact Builder.

3. Engagement publishes the rendered in-app message, specifying the message's trigger criteria, and makes the message available for the device to download.

4. Engagement notifies the SDK that a new in-app message is available via a silent push notification. Silent push notifications wake up the SDK without alerting users and are only sent to devices that are opted-in to receive push notifications.

5. On receiving the silent push notification, the SDK downloads the new in-app messages, along with their priority and trigger criteria. Additionally, in-app messages are synced with the device at the start of the next session. This sync ensures that even if the app misses silent push notifications, it can still download available messages when it’s next opened or brought to the foreground. If you edit an in-app message and reactive the journey, the updated version of the in-app message is downloaded, replacing the older one.

6. After the in-app message is downloaded, it's displayed on the device after the specified trigger criteria are met and evaluated by the SDK. After the contact opens and interacts with the message, the SDK records the event and sends analytics to Engagement. The SDK sends analytics data after the application moves into the background or comes back into the foreground. If a user force-closes the app, the SDK stores the analytics data and sends it to Engagement the next time the user opens the app.

7. If you delete the in-app activity or journey after messages are downloaded to a device, messages that are still on the device remain functional. However, any devices that haven’t yet downloaded the message don’t receive it.

1. The SDK registers the device with Engagement and asynchronously submits critical information such as the device token, device ID, push opt-in status, contact key, and any relevant attributes or tags.

2. Engagement processes the registration to determine whether it can send inbox messages to the device.

   The registration process can take up to five minutes, after which updated information is visible on the contact's profile in Contact Builder.

3. Engagement publishes the rendered inbox message and makes the message available for the device to download.

4. Engagement notifies the SDK that a new inbox message is available via a silent push notification. Silent push notifications wake up the SDK without alerting users and are only sent to devices that are opted-in to receive push notifications.

5. On receiving the silent push notification, the SDK downloads all of the available inbox messages. Additionally, the SDK also fetches inbox messages when the app comes to the foreground. This fetch ensures that even if an app can’t receive silent push notifications (assuming it’s not opted-in), the app can still download available inbox messages from Engagement. While you can use SDK convenience methods to refresh the inbox, the refresh is limited to one time every 60 seconds at most.

6. The app displays the inbox messages and view state. The app itself handles inbox data and uses the data to populate its own UI and view state.

7. The app forwards state changes to the SDK, which then submits analytics to Engagement. The app code must notify the SDK of any state changes, such as a read or delete event. The SDK then asynchronously submits analytics after the app goes into the background or comes into the foreground. If a user force-closes the app, the SDK stores the analytics data and sends it to Engagement the next time the user opens the app.