MobilePush Events
Event Notification Service (ENS) supports the following event notification types and their corresponding payloads.
| Notification Event Category | Notification Event Type | Description |
|---|---|---|
SendEvents | PushSent | Emitted when a push notification is sent. |
SendEvents | PushNotSent | Emitted when a push notification send fails to fully execute. |
SendEvents | PushBounced | Emitted when a push notification is bounced back by the Push Notification Service (PNS). |
EngagementEvents | PushOpen | Emitted when a user opens a push notification on their mobile device. |
EngagementEvents | InAppDisplay | Emitted when an in-app message is displayed in-session due to a user taking a high-value, tracked action with their mobile app. |
EngagementEvents | InAppDismiss | Emitted when a user dismisses an in-app message. |
EngagementEvents | InAppClick | Emitted when a user interacts with an in-app message using the message's Call-to-Action (CTA) button. |
EngagementEvents | InboxOpen | Emitted when a user opens an inbox message. |
PushSent, PushNotSent, PushBounced, and PushOpen events are inclusive of all send methods, such as Mobile Studio batch, Journey Builder, Transactional API, and REST API-triggered sends. To filter events by a particular send type, set up a subscription filter.
All or some of these attributes are shared for all event data payloads.
| Attribute | Type | Description |
|---|---|---|
eventCategoryType | String | The taxonomy of the event. |
compositeId | String | Event ID. |
timestampUTC | Number | UTC Epoch time. |
definitionKey | String | Name of the send definition. |
definitionId | String | A unique message ID. Only present if the send method used is Transactional API. |
composite | Object | Object containing composite identifiers related to the event. |
composite.jobId | String | Marketing Cloud Engagement Job ID (nullable for EngagementEvents.PushOpen events). |
composite.subscriberId | String | Internal ID of the user the message was sent to. |
composite.deviceId | String | Instance of the app installation on the user's device. |
mid | Number | Member identifier of the Engagement business unit that produced the event. |
eid | Number | Enterprise identifier of the Engagement parent business unit that produced the event. |
info | Object | Object containing detailed information about the event. |
ENS triggers the SendEvents.PushSent event when a push notification is successfully sent to a user's device using the Engagement platform.
This event applies to all send methods, such as Mobile Studio batch, Journey Builder, Transactional API, and REST API-triggered sends.
| Attribute | Type | Description |
|---|---|---|
to | String | The unique address the message was sent to. In this case, the end user's device ID. |
contactKey | String | A unique ID for the contact. |
requestId | String | A unique ID for the request. Used to track message status. |
sendMethod | String | The method used to send the push notification. Potential values include MobileStudio, JourneyBuilder, TriggeredSend, and LLTS (Transactional API). |
messageKey | String | A unique ID for the message. Only available if sendMethod is LLTS. |
appId | String | The MobilePush app ID. |
device | Object | An object containing device information. |
device.platform | String | The platform of the receiver's device. For example, iOS. |
The following event notification payload is an example of what your callback receives for a SendEvents.PushSent event.
ENS triggers the SendEvents.PushNotSent event when a push notification send fails. Send failures can occur due to various reasons, including network or service errors, Object Message Mapping (OMM) errors, or AMPscript errors.
This event applies to all send methods, such as Mobile Studio batch, Journey Builder, Transactional API, and REST API-triggered sends.
| Attribute | Type | Description |
|---|---|---|
to | String | The unique address the message was sent to. In this case, the end user's device ID. |
contactKey | String | A unique ID for the contact. |
requestId | String | A unique ID for the request. Used to track message status. |
sendMethod | String | The method used to send the push notification. Potential values include MobileStudio, JourneyBuilder, TriggeredSend, and LLTS (Transactional API).. |
messageKey | String | A unique ID for the message. Only available if sendMethod is LLTS. |
appId | String | The MobilePush app ID. |
statusCode | String | The message send status code or enum. |
statusMessage | String | Brief error message. |
device | Object | An object containing device information. |
device.platform | String | The platform of the receiver's device. For example, iOS. |
The following event notification payload is an example of what your callback receives for a SendEvents.PushNotSent event.
ENS triggers the SendEvents.PushBounced event when a push notification is sent by the Engagement servers but is bounced back by the PNS, such as Apple Push Notification Service (APNS) or Firebase Cloud Messaging (FCM). Push notifications can bounce due to various reasons, such as the recipient uninstalling the app from their device or a mismatch between the ServerKey and SenderID.
This event applies to all send methods, such as Mobile Studio batch, Journey Builder, Transactional API, and REST API-triggered sends.
| Attribute | Type | Description |
|---|---|---|
to | String | The unique address the message was sent to. In this case, the end user's device ID. |
contactKey | String | A unique ID for the contact. |
requestId | String | A unique ID for the request. Used to track message status. |
sendMethod | String | The method used to send the push notification. Potential values include MobileStudio, JourneyBuilder, TriggeredSend, and LLTS (Transactional API).. |
messageKey | String | A unique ID for the message. Only available if sendMethod is LLTS. |
appId | String | The MobilePush app ID. |
bounceCode | String | One word feedback from APNS or FCM. |
bounceMessage | String | Bounce reason. |
device | Object | An object containing device information. |
device.platform | String | The platform of the receiver's device. For example, iOS. |
The following event notification payload is an example of what your callback receives for a SendEvents.PushBounced event.
ENS triggers the EngagementEvents.PushOpen event when a user opens a push notification on their mobile device.
This event must originate from the MobilePush SDK.
| Attribute | Type | Description |
|---|---|---|
to | String | The unique address the message was sent to. In this case, the end user's device ID. |
contactKey | String | A unique ID for the contact. |
requestId | String | A unique ID for the request. Used to track message status. |
sendMethod | String | The method used to send the push notification. Potential values include MobileStudio, JourneyBuilder, TriggeredSend, and LLTS (Transactional API).. |
messageKey | String | A unique ID for the message. Only available if sendMethod is LLTS. |
appId | String | The MobilePush app ID. |
device | Object | An object containing device information. |
device.platform | String | The platform of the receiver's device. For example, iOS. |
The following event notification payload is an example of what your callback receives for a EngagementEvents.PushOpen event.
ENS triggers the EngagementEvents.InAppDisplay event when an in-app message is displayed in-session due to the user peforming a high-value, tracked action within their mobile app.
This event must originate from the MobilePush SDK.
| Attribute | Type | Description |
|---|---|---|
to | String | The unique address the message was sent to. In this case, the end user's device ID. |
contactKey | String | A unique ID for the contact. |
appId | String | The MobilePush app ID. |
messageTrigger | String | The event that triggered the in-app message display. |
device | Object | An object containing device information. |
device.platform | String | The platform of the receiver's device. Potential values include iOS and Android. |
The following event notification payload is an example of what your callback receives for a EngagementEvents.InAppDisplay event.
ENS triggers the EngagementEvents.InAppDismiss event when an in-app message is dismissed in-session, either by the user hitting the X button or by timing out.
This event must originate from the MobilePush SDK.
| Attribute | Type | Description |
|---|---|---|
to | String | The unique address the message was sent to. In this case, the end user's device ID. |
contactKey | String | A unique ID for the contact. |
appId | String | The MobilePush app ID. |
displayDuration | Integer | In-app message display duration. |
messageTrigger | String | The event that triggered the in-app message display. |
dismissType | Integer | Denotes whether the in-app message was user-dismissed or time-dismissed. |
device | Object | An object containing device information. |
device.platform | String | The platform of the receiver's device. Potential values include iOS and Android. |
The following event notification payload is an example of what your callback receives for a EngagementEvents.InAppDismiss event.
ENS triggers the EngagementEvents.InAppClick event when a user interacts with an in-app message using the message's CTA button during an app session.
This event must originate from the MobilePush SDK.
| Attribute | Type | Description |
|---|---|---|
to | String | The unique address the message was sent to. In this case, the end user's device ID. |
contactKey | String | A unique ID for the contact. |
appId | String | The MobilePush app ID. |
buttonClicked | String | The name, CTA, or title of the button the user clicked. |
displayDuration | Integer | In-app message display duration. |
messageTrigger | String | The event that triggered the in-app message display. |
dismissType | Integer | Denotes whether the in-app message was user-dismissed or time-dismissed. |
device | Object | An object containing device information. |
device.platform | String | The platform of the receiver's device. Potential values include iOS and Android. |
The following event notification payload is an example of what your callback receives for a EngagementEvents.InAppClick event.
ENS triggers the EngagementEvents.InboxOpen event when a user opens an inbox message that's been downloaded to the mobile app's inbox.
This event must originate from the MobilePush SDK.
| Attribute | Type | Description |
|---|---|---|
to | String | The unique address the message was sent to. In this case, the end user's device ID. |
contactKey | String | A unique ID for the contact. |
appId | String | The MobilePush app ID. |
requestId | String | A unique ID used to track message status. |
device | Object | An object containing device information. |
device.platform | String | The platform of the receiver's device. Potential values include iOS and Android. |
The following event notification payload is an example of what your callback receives for a EngagementEvents.InboxOpen event.