How the Engagement SDK Works

Learn how the Engagement SDK interacts with your Marketing Cloud environment to deliver push notifications, in-app messages, and inbox messages to your app users.

Push notifications are messages sent from your Marketing Cloud environment to a user’s device, even when the app isn’t actively running. This flow chart shows how the SDK, Push Notification Service, and Marketing Cloud work together to register devices and deliver notifications.

1. When a mobile app opens and successfully initializes the SDK, the SDK communicates with the push notification service to obtain a device token.

   A push notification service is a service such as Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM) that manages push notifications for a device.

2. The push notification service returns a unique 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 your Marketing Cloud environment and submits critical information, such as the device token, device ID, push opt-in status, user identifier (contact key or party identifier), and any relevant attributes or tags. This registration process occurs asynchronously.

4. Your Marketing Cloud environment processes the registration to determine whether it can send push notifications to the device. This process includes checking whether the device is opted in or out of receiving push notifications. At this point, Marketing Cloud creates or updates a record.

   In Marketing Cloud Engagement, 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. This registration process can take up to five minutes.

   In Marketing Cloud Next, if the user is a new contact, Marketing Cloud Next creates an Individual record. If the user is an existing Individual, Marketing Cloud Next updates the existing Individual record with the latest information. This registration process can take up to 15 minutes.

5. After your Marketing Cloud environment processes the registration, a marketer sends push notifications using the device token received from the SDK.

6. The push notification service validates device tokens and delivers push notifications in these ways:

   a. If the device token is valid, the push notification service delivers the message to the device.

   b. If the device token is invalid or if the device is opted out, the push notification service notifies your Marketing Cloud environment to opt out the user’s device. The user 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 user opens and interacts with the push notification, the SDK records the event and sends analytics data to your Marketing Cloud environment. 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 your Marketing Cloud environment the next time the user opens the app.

In-app messages are displayed to users while they use your app. The app downloads these messages to the device and displays them based on trigger criteria that you define. This flow chart shows how the SDK registers the device, downloads in-app messages, and displays them when trigger conditions are met.

1. The SDK registers the device with your Marketing Cloud environment and asynchronously submits critical information, such as the device token, device ID, push opt-in status, user identifier (contact key or party identifier), and any relevant attributes or tags.

2. Your Marketing Cloud environment processes the registration to determine whether it can send in-app messages to the device.

   The registration process can take up to 15 minutes, after which updated information is visible in Contact Builder or your Individual records.

3. Your Marketing Cloud environment publishes the rendered in-app message, specifying the message’s trigger criteria, and makes the message available for the device to download.

4. Your Marketing Cloud environment 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 makes sure 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 reactivate 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 user opens and interacts with the message, the SDK records the event and sends analytics to your Marketing Cloud environment. 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 your Marketing Cloud environment 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.

Inbox messages are persistent messages that are stored in a dedicated inbox within your app. Unlike push notifications or in-app messages, inbox messages remain available for users to view at any time. This flow chart shows how the SDK downloads inbox messages, how your app displays them, and how state changes are tracked.

1. The SDK registers the device with Marketing Cloud 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. Marketing Cloud Engagement processes the registration to determine whether it can send inbox messages to the device.

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

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

4. Marketing Cloud 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 makes sure 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 Marketing Cloud 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 send analytics data to Marketing Cloud Engagement. Make sure that the app code notifies 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 Marketing Cloud Engagement the next time the user opens the app.