PubSubSubscribeOptions Class - Android

Configuration options for subscribing to a PubSub topic.

Pass these options to subscribe() to limit how much history the subscription replays and how fast live messages reach it. Without options, the whole history is replayed at the server's own pace.

The options do not change how messages are delivered: history arrives in server-paced batches on onOldMessagesReceived() either way, and live batching is a server setting, not a subscribe option.

Pass the options to the constructor. These are the defaults:

PubSubSubscribeOptions(
    oldMessageLimit = null,
    realtimeOverflow = RealtimeOverflow.QUEUE,
    maxQueue = null,
    newMessageLimit = null,
)

Pass only the options you need. The properties are read-only. The constructor does not check the values: an invalid option makes subscribe() throw a VideoSDKException with code 3073 (ERROR_INVALID_PARAMETER).

Properties

oldMessageLimit

• type: Int?

• defaultValue: null

• Limits how many persisted (historical) messages are fetched on subscribe.

• Pass null for all history, 0 for none (real-time only), or N > 0 for the last N messages. A negative value makes subscribe() throw 3073.

---

realtimeOverflow

• type: RealtimeOverflow

• defaultValue: RealtimeOverflow.QUEUE

• Policy for live messages that arrive faster than they can be delivered.

Value	Behaviour
QUEUE	The server keeps recent messages, so a subscriber that briefly falls behind can catch up instead of losing them. How far it may fall behind is set by maxQueue, and anything lost beyond that is reported by onMessageDrop(). A burst above the server's own per-window ceiling is still cut short.
DROP	Shed load — the newest messages of each delivery window survive, the rest are dropped. Don't rely on onMessageDrop() to count these losses. Use it only when stale data is worthless, such as cursor positions or typing indicators.

---

maxQueue

• type: Int?

• defaultValue: null

• How far a subscriber may fall behind under RealtimeOverflow.QUEUE before the server gives up on it. The value counts delivery batches, not messages. Beyond it, the server discards the waiting messages and onMessageDrop() reports them.

• Must be >= 1. Pass null to let the server decide.

• The server clamps this value to its own maximum. The first subscriber to a topic sets it for everyone on that topic.

note

maxQueue is only valid with RealtimeOverflow.QUEUE. Combining it with RealtimeOverflow.DROP, or passing a value below 1, makes subscribe() throw a VideoSDKException with code 3073 (ERROR_INVALID_PARAMETER).

---

newMessageLimit

• type: Int?

• defaultValue: null

• Caps how many new (live) messages this subscriber accepts per server batching window (500 ms).

• Pass null or 0 for unlimited, or N > 0 to cap N messages per window (approximately 2 × N messages/second). A negative value makes subscribe() throw 3073.

• Extra messages in a window are skipped for this subscriber only. onMessageDrop() reports them once delivery continues in the next window, so a capped topic produces drop callbacks by design.

---

Example

val options = PubSubSubscribeOptions(
    oldMessageLimit = 100,
    realtimeOverflow = RealtimeOverflow.QUEUE,
    maxQueue = 70,
)

lifecycleScope.launch {
    try {
        room.pubSub.subscribe("CHAT", pubSubMessageListener, options)
    } catch (e: VideoSDKException) {
        // 3073 for invalid options; see subscribe() for the other codes
        Log.d("VideoSDK", "subscribe failed: ${e.code} ${e.message}")
    }
}