Realtime Events

Realtime events are pushed to the app as they happen, without polling. The service connects automatically when InstaVision.initialize() is called and the user is signed in, and it reconnects on its own when the region changes or the session is refreshed. There is nothing to start or stop yourself.

Pre-requisite: The user has to be signed in to receive realtime events.

Listen for realtime events

To be notified whenever an event arrives, assign a callback to onMessage. The callback is invoked on the main thread, so it is safe to update the UI from it directly.

InstaVision.realtimeEventService.onMessage = { event ->
  // event.name is the event type, for example "lullaby.state.updated"
  // event.extras holds the event payload
  // event.createdAt is the time the event was raised, in epoch milliseconds
}

Assign null to stop receiving events. Only one callback is active at a time, so setting a new one replaces the previous one.

The realtime event

Every event delivered to onMessage or returned by fetchHistory is a RealtimeEvent:

RealtimeEvent(
  name = "lullaby.state.updated", // The event type
  extras = mapOf("device_id" to "deviceId"), // The event payload
  createdAt = 1756636800000, // When the event was raised, in epoch milliseconds
  deliveryType = RealtimeDeliveryType.Persistent // Whether the event is stored or transient
)

To match an event against a known type, use RealtimeEventType:

when (RealtimeEventType.fromValue(event.name)) {
  RealtimeEventType.LullabyStateUpdated -> {
    // The lullaby playback state changed on a device
  }
  null -> {
    // An event type this version of the SDK does not know about
  }
}

RealtimeDeliveryType describes whether an event is kept for later retrieval:

• Persistent: the event is stored and will also be returned by fetchHistory. This is the default.
• Transient: the event is delivered live only and is never returned by fetchHistory.

Observe the connection state

To react to the realtime connection coming up or going down, the following property can be used:

viewModelScope.launch {
  InstaVision.realtimeEventService.connectionState.collectLatest { state ->
    when (state) {
      RealtimeConnectionState.Connected -> {
        // Events are being delivered
      }
      RealtimeConnectionState.Connecting,
      RealtimeConnectionState.Disconnected,
      RealtimeConnectionState.Suspended -> {
        // The connection is being established or has dropped, it recovers on its own
      }
      RealtimeConnectionState.Initialized,
      RealtimeConnectionState.Closing,
      RealtimeConnectionState.Closed,
      RealtimeConnectionState.Failed -> {
        // The connection is not active
      }
    }
  }
}

Fetch the event history

To load the events that arrived while the app was not listening, the following method can be used:

• onSuccess (required): Receives the unread events, oldest first.
• onError (optional): Receives the error if the history could not be fetched.

InstaVision.realtimeEventService.fetchHistory(
  onSuccess = { events ->
    // The list of unread events
  },
  onError = { error ->
    // The error object contains the error code and message
  }
)

Only events that have not been marked as read are returned. Transient events are never part of the history.

Mark an event as read

Events stay unread until you say otherwise, so an event that arrives while the app is backgrounded is still returned by the next fetchHistory call. To mark one as read, the following extension can be used:

event.markAsRead()

Read state is tracked by the SDK against the event’s internal identifier. That identifier is not part of the public RealtimeEvent, so markAsRead() is the only way to advance it.