wehub-resource-sync
172 lines
3.9 KiB
Plaintext
172 lines
3.9 KiB
Plaintext
---
|
|
title: Kotlin realtime SDK reference
|
|
description: Connect over Socket.IO, subscribe to channels, publish events, track presence, and handle reconnects with the InsForge Kotlin realtime client.
|
|
---
|
|
|
|
import KotlinSdkInstallation from '/snippets/kotlin-sdk-installation.mdx';
|
|
|
|
## Installation
|
|
|
|
<KotlinSdkInstallation />
|
|
|
|
## Mental model
|
|
|
|
The Kotlin SDK connects to InsForge Realtime over Socket.IO. Subscribe to channel names such as `order:123` or `chat:room-1`, then listen for event names published to those channels.
|
|
|
|
Events are published by database triggers that call `realtime.publish(...)` or by clients that publish to a channel they have already joined. See [Realtime overview](/core-concepts/realtime/overview) for the channel and RLS model.
|
|
|
|
## Quick start
|
|
|
|
```kotlin
|
|
import dev.insforge.realtime.models.SocketMessage
|
|
|
|
client.realtime.connect()
|
|
|
|
val response = client.realtime.subscribe("order:$orderId")
|
|
|
|
if (!response.ok) {
|
|
println("Subscribe failed: ${response.error?.message}")
|
|
return
|
|
}
|
|
|
|
client.realtime.on<SocketMessage>("status_changed") { message ->
|
|
message?.let {
|
|
println("Status changed: ${it.payload}")
|
|
}
|
|
}
|
|
```
|
|
|
|
## connect()
|
|
|
|
Establish a realtime connection.
|
|
|
|
```kotlin
|
|
client.realtime.connect()
|
|
|
|
println("Connected: ${client.realtime.isConnected}")
|
|
println("Socket ID: ${client.realtime.socketId}")
|
|
```
|
|
|
|
Monitor connection state:
|
|
|
|
```kotlin
|
|
client.realtime.connectionState.collect { state ->
|
|
when (state) {
|
|
is Realtime.ConnectionState.Connected -> println("Connected")
|
|
is Realtime.ConnectionState.Connecting -> println("Connecting")
|
|
is Realtime.ConnectionState.Disconnected -> println("Disconnected")
|
|
is Realtime.ConnectionState.Error -> println("Error: ${state.message}")
|
|
}
|
|
}
|
|
```
|
|
|
|
## subscribe()
|
|
|
|
Subscribe to a channel and receive the current presence snapshot.
|
|
|
|
```kotlin
|
|
val response = client.realtime.subscribe("chat:room-1")
|
|
|
|
if (response.ok) {
|
|
println("Subscribed to: ${response.channel}")
|
|
println("Members: ${response.presence?.members}")
|
|
} else {
|
|
println("Error: ${response.error?.message}")
|
|
}
|
|
```
|
|
|
|
## publish()
|
|
|
|
Publish an event to a channel.
|
|
|
|
```kotlin
|
|
client.realtime.publish(
|
|
channel = "chat:room-1",
|
|
event = "new_message",
|
|
payload = mapOf(
|
|
"text" to "Hello from Kotlin",
|
|
"sentAt" to System.currentTimeMillis()
|
|
)
|
|
)
|
|
```
|
|
|
|
<Note>
|
|
The client must subscribe to a channel before publishing to that same channel.
|
|
</Note>
|
|
|
|
If RLS is enabled on `realtime.messages`, publish is also checked against `INSERT` policies.
|
|
|
|
## on()
|
|
|
|
Register an event listener.
|
|
|
|
```kotlin
|
|
client.realtime.on<SocketMessage>("new_message") { message ->
|
|
message?.let {
|
|
println("Message: ${it.payload}")
|
|
}
|
|
}
|
|
```
|
|
|
|
Connection and system events:
|
|
|
|
| Event | Description |
|
|
|-------|-------------|
|
|
| `presence:join` | A logical member became present in the channel. |
|
|
| `presence:leave` | A logical member is no longer present in the channel. |
|
|
| `realtime:error` | Subscribe or publish failed. |
|
|
|
|
## once()
|
|
|
|
Listen for an event once.
|
|
|
|
```kotlin
|
|
client.realtime.once<SocketMessage>("checkout_completed") { message ->
|
|
println("Checkout completed: ${message?.payload}")
|
|
}
|
|
```
|
|
|
|
## off()
|
|
|
|
Remove an event listener.
|
|
|
|
```kotlin
|
|
val callback = Realtime.EventCallback<SocketMessage> { message ->
|
|
println("Event received: $message")
|
|
}
|
|
|
|
client.realtime.on("status_changed", callback)
|
|
client.realtime.off("status_changed", callback)
|
|
```
|
|
|
|
## unsubscribe()
|
|
|
|
Leave a channel.
|
|
|
|
```kotlin
|
|
client.realtime.unsubscribe("chat:room-1")
|
|
```
|
|
|
|
## disconnect()
|
|
|
|
Close the realtime connection.
|
|
|
|
```kotlin
|
|
client.realtime.disconnect()
|
|
```
|
|
|
|
## getSubscribedChannels()
|
|
|
|
Return locally subscribed channels.
|
|
|
|
```kotlin
|
|
val channels = client.realtime.getSubscribedChannels()
|
|
println(channels)
|
|
```
|
|
|
|
## Presence
|
|
|
|
Successful subscriptions return a presence snapshot. Listen for `presence:join` and `presence:leave` to update local online state.
|
|
|
|
Presence is ephemeral. It is not a durable room membership table.
|