> ## Documentation Index > Fetch the complete documentation index at: https://docs.insforge.dev/llms.txt > Use this file to discover all available pages before exploring further. # Kotlin 即時 SDK 參考 > 透過 Socket.IO 連線，訂閱頻道，發佈事件，追蹤在線狀態，並使用 InsForge Kotlin 即時用戶端處理重新連線。 ## 安裝 1. Add InsForge dependencies to your project build.gradle.kts: ```kotlin theme={null} repositories { mavenLocal() // For local development mavenCentral() } dependencies { implementation("dev.insforge:insforge-kotlin:0.1.6") } ``` First, create a GitHub Personal Access Token: * Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) * Select permission: `read:packages` Then configure your project using one of the following methods: settings.gradle.kts (or build.gradle.kts): ```kotlin theme={null} repositories { mavenCentral() maven { url = uri("https://maven.pkg.github.com/InsForge/insforge-kotlin") credentials { username = System.getenv("GITHUB_USER") ?: "" password = System.getenv("GITHUB_TOKEN") ?: "" } } } ``` build.gradle.kts: ```kotlin theme={null} dependencies { implementation("dev.insforge:insforge-kotlin:0.1.6") } ``` Set environment variables before building: ```bash theme={null} export GITHUB_USER="your-github-username" export GITHUB_TOKEN="your-personal-access-token" ``` Add credentials to your global Gradle properties file: \~/.gradle/gradle.properties: ```properties theme={null} gpr.user=your-github-username gpr.token=ghp_xxxxxxxxxxxx ``` settings.gradle.kts: ```kotlin theme={null} repositories { mavenCentral() maven { url = uri("https://maven.pkg.github.com/InsForge/insforge-kotlin") credentials { username = providers.gradleProperty("gpr.user").orNull ?: "" password = providers.gradleProperty("gpr.token").orNull ?: "" } } } ``` build.gradle.kts: ```kotlin theme={null} dependencies { implementation("dev.insforge:insforge-kotlin:0.1.6") } ``` The `~/.gradle/gradle.properties` file is stored outside your project, so credentials won't be accidentally committed to version control. 2. Initialize InsForge SDK ```kotlin theme={null} import dev.insforge.createInsforgeClient import dev.insforge.auth.Auth import dev.insforge.database.Database import dev.insforge.storage.Storage import dev.insforge.functions.Functions import dev.insforge.realtime.Realtime import dev.insforge.ai.AI val client = createInsforgeClient( baseUrl = "https://your-app.insforge.app", anonKey = "your-api-key" ) { install(Auth) install(Database) install(Storage) install(Functions) install(Realtime) { autoReconnect = true reconnectDelay = 5000 } install(AI) } ``` 3. Enable Logging (Optional) For debugging, you can configure the SDK log level: ```kotlin theme={null} import dev.insforge.InsforgeLogLevel val client = createInsforgeClient( baseUrl = "https://your-app.insforge.app", anonKey = "your-api-key" ) { // DEBUG: logs request method/URL and response status // VERBOSE: logs full headers and request/response bodies logLevel = InsforgeLogLevel.DEBUG install(Auth) install(Database) // ... other modules } ``` | Log Level | Description | | --------- | ------------------------------------------------- | | `NONE` | No logging (default, recommended for production) | | `ERROR` | Only errors | | `WARN` | Warnings and errors | | `INFO` | Informational messages | | `DEBUG` | Debug info (request method, URL, response status) | | `VERBOSE` | Full details (headers, request/response bodies) | Use `NONE` or `ERROR` in production to avoid exposing sensitive data in logs. ### Android Initialization 1. Add Chrome Custom Tabs dependency to your `build.gradle.kts`: ```kotlin theme={null} dependencies { implementation("androidx.browser:browser:1.9.0") } ``` 2. Initialize InsForge SDK (With Chrome Custom Tabs and Session Storage) ```kotlin theme={null} import android.app.Activity import android.content.Context import android.content.Intent import android.net.Uri import androidx.browser.customtabs.CustomTabsIntent import dev.insforge.createInsforgeClient import dev.insforge.ai.AI import dev.insforge.auth.Auth import dev.insforge.auth.BrowserLauncher import dev.insforge.auth.ClientType import dev.insforge.auth.SessionStorage import dev.insforge.database.Database import dev.insforge.functions.Functions import dev.insforge.realtime.Realtime import dev.insforge.storage.Storage class InsforgeManager(private val context: Context) { val client = createInsforgeClient( baseUrl = "https://your-app.insforge.app", anonKey = "your-anon-key" ) { install(Auth) { // 1. Chrome Custom Tabs - opens in-app, similar to iOS ASWebAuthenticationSession browserLauncher = BrowserLauncher { url -> val customTabsIntent = CustomTabsIntent.Builder() .setShowTitle(true) .build() // Handle non-Activity context safely if (context is Activity) { customTabsIntent.launchUrl(context, Uri.parse(url)) } else { customTabsIntent.intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK) customTabsIntent.launchUrl(context, Uri.parse(url)) } } // 2. enable session persistence persistSession = true // 3. config SessionStorage (use SharedPreferences) sessionStorage = object : SessionStorage { private val prefs = context.getSharedPreferences( "insforge_auth", Context.MODE_PRIVATE ) override suspend fun save(key: String, value: String) { prefs.edit().putString(key, value).apply() } override suspend fun get(key: String): String? { return prefs.getString(key, null) } override suspend fun remove(key: String) { prefs.edit().remove(key).apply() } } // 4. set client type for mobile clientType = ClientType.MOBILE } // Install Database module install(Database) // Install Realtime module for real-time subscriptions install(Realtime) { debug = true } // Install other modules install(Storage) install(Functions) install(AI) } } ``` 3. Use Jetpack DataStore for Session Storage (Optional) ```kotlin theme={null} import androidx.datastore.core.DataStore import androidx.datastore.preferences.core.Preferences import androidx.datastore.preferences.core.edit import androidx.datastore.preferences.core.stringPreferencesKey import androidx.datastore.preferences.preferencesDataStore import kotlinx.coroutines.flow.first import kotlinx.coroutines.flow.map val Context.authDataStore: DataStore by preferencesDataStore(name = "insforge_auth") class DataStoreSessionStorage(private val context: Context) : SessionStorage { override suspend fun save(key: String, value: String) { context.authDataStore.edit { prefs -> prefs[stringPreferencesKey(key)] = value } } override suspend fun get(key: String): String? { return context.authDataStore.data.map { prefs -> prefs[stringPreferencesKey(key)] }.first() } override suspend fun remove(key: String) { context.authDataStore.edit { prefs -> prefs.remove(stringPreferencesKey(key)) } } } // Then use it in your InsForge client install(Auth) { browserLauncher = ... persistSession = true sessionStorage = DataStoreSessionStorage(context) } ``` ## 心智模型 Kotlin SDK 透過 Socket.IO 連線到 InsForge 即時系統。訂閱頻道名稱（如 `order:123` 或 `chat:room-1`），然後監聽發佈到這些頻道的事件名稱。 事件由資料庫觸發程式發佈，這些觸發程式呼叫 `realtime.publish(...)` 或由已加入頻道的用戶端發佈。有關頻道和 RLS 模型，請參閱[即時概述](/core-concepts/realtime/overview)。 ## 快速開始 ```kotlin theme={null} 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("status_changed") { message -> message?.let { println("Status changed: ${it.payload}") } } ``` ## connect() 建立即時連線。 ```kotlin theme={null} client.realtime.connect() println("Connected: ${client.realtime.isConnected}") println("Socket ID: ${client.realtime.socketId}") ``` 監視連線狀態： ```kotlin theme={null} 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() 訂閱頻道並接收目前在線狀態快照。 ```kotlin theme={null} 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() 將事件發佈到頻道。 ```kotlin theme={null} client.realtime.publish( channel = "chat:room-1", event = "new_message", payload = mapOf( "text" to "Hello from Kotlin", "sentAt" to System.currentTimeMillis() ) ) ``` 用戶端必須訂閱頻道才能向該頻道發佈。 如果在 `realtime.messages` 上啟用了 RLS，發佈也會根據 `INSERT` 原則進行檢查。 ## on() 註冊事件接聽程式。 ```kotlin theme={null} client.realtime.on("new_message") { message -> message?.let { println("Message: ${it.payload}") } } ``` 連線和系統事件： | 事件 | 說明 | | ---------------- | ------------- | | `presence:join` | 邏輯成員在頻道中變為在線。 | | `presence:leave` | 邏輯成員不再在頻道中在線。 | | `realtime:error` | 訂閱或發佈失敗。 | ## once() 僅監聽一次事件。 ```kotlin theme={null} client.realtime.once("checkout_completed") { message -> println("Checkout completed: ${message?.payload}") } ``` ## off() 移除事件接聽程式。 ```kotlin theme={null} val callback = Realtime.EventCallback { message -> println("Event received: $message") } client.realtime.on("status_changed", callback) client.realtime.off("status_changed", callback) ``` ## unsubscribe() 離開頻道。 ```kotlin theme={null} client.realtime.unsubscribe("chat:room-1") ``` ## disconnect() 關閉即時連線。 ```kotlin theme={null} client.realtime.disconnect() ``` ## getSubscribedChannels() 傳回本機訂閱的頻道。 ```kotlin theme={null} val channels = client.realtime.getSubscribedChannels() println(channels) ``` ## 在線狀態 成功的訂閱會傳回在線狀態快照。監聽 `presence:join` 和 `presence:leave` 以更新本機在線狀態。 在線狀態是暫時的。它不是一個持久的房間成員身份表。