Receiving SDK Events

Event Handling

The SDK communicates with your application by emitting events as a result of SDK-related operations. Access these events as follows:

Android

applicationScope.launch {
    EngagementCloud.events.collect { event ->
        when(event){
            is AppEvent -> handleAppEvent(event)
            is BadgeCountEvent -> handleBadgeCountEvent(event)
        }
    }
}

Kotlin Multiplatform

applicationScope.launch {
    EngagementCloud.events.collect { event ->
        when(event){
            is AppEvent -> handleAppEvent(event)
            is BadgeCountEvent -> handleBadgeCountEvent(event)
        }
    }
}

iOS

Access emitted events using the events AsyncStream or by registering a listener for all or specific event types:

 for await event in EngagementCloud.shared.events {
    switch onEnum(of: event) {
        case .appEvent(let appEvent): print("AsyncStream appEvent received: \(appEvent.name) with payload: \(appEvent.payload ?? [:])")
        case .badgeCountEvent(let event): print("AsyncStream badgeCount: \(event.badgeCount)")
    }
}

EngagementCloud.shared.registerEventListener { event in
    switch(event) {
      case let appEvent as AppEvent: handleAppEvent(appEvent)
      case let badgeCountEvent as BadgeCount: handleBadgeCountEvent(badgeCountEvent)
      default: print("unknown event type")
    }
    
    switch onEnum(of: event) {
      case .appEvent(let appEvent): handleAppEvent(appEvent)
      case .badgeCountEvent(let badgeCountEvent): handleBadgeCountEvent(badgeCountEvent)
    }
}

info

The onEnum helper enables exhaustive switching on EngagementCloudEvent without a default case.

Web

You can access the emitted events by registering listeners as follows:

• Continuously collect events:

EngagementCloud.events.on("badge_count", (event) => {
    ...
});

• Handle an event only once:

EngagementCloud.events.once("badge_count", (event) => {
    ...
});

• Remove a registered listener:

EngagementCloud.events.off("badge_count", eventListener);

• Remove all registered listeners:

EngagementCloud.events.removeAllListeners();

Event Types

The events emitted by the SDK conform to the following base structure:

sealed class EngagementCloudEvent {
    abstract val id: String
    internal abstract val type: EventType
}

All events extend EngagementCloudEvent and include a unique identifier (id).

info

On Web, each event includes a type string property for differentiating between event types. The event types follow the lowercase snake_case convention of the event name, for example badge_count for the badge count event and app_event for the app event.

App Events

Android

data class AppEvent(
    val type: String,
    val id: String,
    val name: String,
    val payload: Map<String, Any>?,
    val source: EventSource?
)

• name is the name of the event.
• payload is the additional payload for the event, which can be null.
• source is the origin that triggered the event. EventSource is on of the following:
  • Push: the event was triggered by a push notification interaction.
  • InApp: the event was triggered by an in-app message interaction.
  • InlineInApp: the event was triggered by an inline in-app message interaction.
  • EmbeddedMessagingRichContent: the event was triggered by an embedded messaging rich content interaction.
  • OnEvent: the event was triggered by an on-event action.

Kotlin Multiplatform

data class AppEvent(
    val type: String,
    val id: String,
    val name: String,
    val payload: Map<String, Any>?,
    val source: EventSource?
)

• name is the name of the event.
• payload is the additional payload for the event, which can be null.
• source is the origin that triggered the event. EventSource is on of the following:
  • Push: the event was triggered by a push notification interaction.
  • InApp: the event was triggered by an in-app message interaction.
  • InlineInApp: the event was triggered by an inline in-app message interaction.
  • EmbeddedMessagingRichContent: the event was triggered by an embedded messaging rich content interaction.
  • OnEvent: the event was triggered by an on-event action.

iOS

AppEvent(
  id: String,
  name: String,
  payload: [String : Any]?,
  source: EventSource?
)

• name is the name of the event.
• payload is the additional payload for the event, which can be null.
• source is the origin that triggered the event. EventSource is on of the following:
  • .push: the event was triggered by a push notification interaction.
  • .inApp: the event was triggered by an in-app message interaction.
  • .inlineInApp: the event was triggered by an inline in-app message interaction.
  • .embeddedMessagingRichContent: the event was triggered by an embedded messaging rich content interaction.
  • .onEvent: the event was triggered by an on-event action.

Web

interface AppEvent extends EngagementCloudEvent {
    type: string;
    id: string;
    name: string;
    payload: JSON;
}

• name is the name of the event.
• payload is the additional payload for the event, which can be null.
• source is the origin that triggered the event. EventSource is on of the following:
  • push: the event was triggered by a push notification interaction.
  • in_app: the event was triggered by an in-app message interaction.
  • inline_in_app: the event was triggered by an inline in-app message interaction.
  • embedded_messaging_rich_content: the event was triggered by an embedded messaging rich content interaction.
  • on_event: the event was triggered by an on-event action.

Badge Count Events

Android

data class BadgeCountEvent(
    val id: String,
    val badgeCount: Int,
    val method: String,
)

Kotlin Multiplatform

data class BadgeCountEvent(
    val id: String,
    val badgeCount: Int,
    val method: String,
)

iOS

BadgeCountEvent(
  id: String,
  badgeCount: Int,
  method: String
)

Web

interface BadgeCountEvent extends EngagementCloudEvent {
    type: string;
    id: string;
    badgeCount: number;
    method: string;
}

• badgeCount is the int value of the badge.
• method is the string value the operation with one of the following possible values:
  • Use set to set the current value to the value of the badgeCount
  • Use add to increase the current value by the badgeCount

Memory Considerations

To avoid memory leaks, always unsubscribe or cancel collectors when the component scope ends, for example when the Android ViewModel is cleared.