Custom Events

Custom events allow emitting and receiving data of any shape in a secure, end-to-end encrypted way.

Custom events allow you to send information to specific groups of users. The data will not be stored anywhere. For an event to reach the recipient, the recipient must be subscribed to the channel on which you are emitting the event at that moment.

Working with Custom Events

Key Considerations

Please note the following:

• Events will only trigger for active connections.
• Events are not captured unless explicitly listened for.
• A single instance of the eventQueue is shared across all connections.

Accessing Custom Event API

To access Custom Event methods, get the field eventApi from active connection. Connection should be initialized with Modules.CUSTOM_EVENT passed to PrivmxEndpoint().

val eventApi = endpointSession.eventApi

Emitting and Handling Custom Events

Below you can find a simple code example showing how to emit an event with a custom payload and how to handle it when it arrives to the recipients.

Emitting Custom Event

val contextId = "CONTEXT_ID"
val channelName = "CHANNEL_NAME"

val users: List<UserWithPubKey> = listOf(
    UserWithPubKey(user1Id, user1PublicKey),
    UserWithPubKey(user2Id, user2PublicKey)
)
val eventData = "Custom Event Data"

endpointSession.eventApi.emitEvent(
    contextId,
    users,
    channelName,
    eventData.encodeToByteArray()
)

Handling Custom Event

val callbacksId = "CALLBACKS_ID"
val contextId = "CONTEXT_ID"
val channelName = "CHANNEL_NAME"

endpointSession.registerCallback(
    callbacksId,
    EventType.ContextCustomEvent(contextId, channelName)
) { customEventData ->
    // Some actions when custom event is received
}