Kotlin SDK

com.messagebird:bird-realtime Bird Realtime का आधिकारिक Kotlin क्लाइंट है: यह Bird एज से एक WebSocket कनेक्शन बनाए रखता है, चैनल सब्सक्राइब करता है, और इवेंट पब्लिश होते ही उन्हें डिलीवर करता है। यह जेनरेट किए गए कोड की बजाय हाथ से लिखा गया है, क्योंकि Realtime एक WebSocket डेटा प्लेन है न कि REST सरफ़ेस, और यह ब्राउज़र और Swift क्लाइंट के समान वायर डायलेक्ट बोलता है।

यह एक सामान्य JVM लाइब्रेरी है, इसलिए एक ही आर्टिफ़ैक्ट Android ऐप और सर्वर दोनों के लिए काम करता है। जब Android main looper मौजूद होता है तो कॉलबैक उस पर आते हैं, अन्यथा इनलाइन चलते हैं, इसलिए आपको हर एक के लिए अलग बिल्ड की ज़रूरत नहीं है।

यह क्लाइंट प्राप्त करने वाला पक्ष है। इवेंट पब्लिश करना, चैनल अधिकृत करना, और कनेक्शन समाप्त करना सर्वर-साइड ऑपरेशन हैं जो Bird API पर होते हैं; देखें इवेंट पब्लिश करना।

इंस्टॉल करें

dependencies {
    implementation("com.messagebird:bird-realtime:0.1.0")
}

Android पर, अपने manifest में इंटरनेट परमिशन जोड़ें। अब कोई लाइब्रेरी इसे स्वयं नहीं जोड़ती:

<uses-permission android:name="android.permission.INTERNET" />

क्लाइंट बनाएँ

import com.messagebird.realtime.BirdRealtime
import com.messagebird.realtime.BirdRealtimeOptions

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
    )
)

केवल appKey आवश्यक है, साथ ही region (us1 या eu1, जो एज होस्ट रिज़ॉल्व करता है) या एक स्पष्ट wsHost। ऐप key सार्वजनिक है और क्लाइंट कोड में शिप होती है: यह ऐप की पहचान करती है, कुछ भी अधिकृत नहीं करती।

क्लाइंट बनते ही सॉकेट खुल जाता है, इसलिए आपको पहले connect() कॉल करने की ज़रूरत नहीं है। connect() और disconnect() ऐप लाइफ़साइकल के लिए हैं: जब आपकी activity हट जाए तो सॉकेट बंद करें और वापस आने पर फिर खोलें, और आपके सब्सक्राइब किए गए चैनल स्वचालित रूप से फिर से सब्सक्राइब हो जाते हैं।

disconnect() क्लाइंट को पुन: उपयोग योग्य छोड़ता है, इसलिए यह जानबूझकर उस वर्कर थ्रेड को बनाए रखता है जिस पर क्लाइंट अपनी state सीमित करता है। जब आपका क्लाइंट से काम पूरी तरह हो जाए, तो इसे close() करें, वरना वह थ्रेड और सॉकेट प्रोसेस जीवित रहने तक बने रहते हैं। यह क्लास AutoCloseable है, इसलिए एक use { } ब्लॉक यह आपके लिए कर देता है। Swift क्लाइंट को इसके समकक्ष की ज़रूरत नहीं: जब अंतिम रेफ़रेंस हटता है तो यह दोनों को रिलीज़ कर देता है।

किसी चैनल को सब्सक्राइब करें

val orders = bird.subscribe("orders")
orders.bind("order-updated") { data ->
    println("order changed: $data")
}

पेलोड kotlinx.serialization.json.JsonElement के रूप में आते हैं, इसलिए उन्हें कास्ट करने की बजाय सीरियलाइज़ेशन API से पढ़ें।

जिस चैनल के नाम में कोई private- या presence- प्रीफ़िक्स नहीं है वह public है: ऐप key वाला कोई भी क्लाइंट सब्सक्राइब कर सकता है, इसलिए इसकी सामग्री को ऐसा मानें जो आपका ऐप खोलने वाला कोई भी व्यक्ति पढ़ सकता है।

Private और presence चैनल

Private और presence चैनल आपके बैकएंड द्वारा अधिकृत होते हैं, जिसके पास ऐप secret होता है। क्लाइंट को अपने endpoint पर इंगित करें: यह {"connection_id", "channel_name"} POST करता है और {"auth", "member_data"?} वापस पाने की अपेक्षा करता है।

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
        authEndpoint = "https://your-backend.example.com/bird/auth",
        authHeaders = mapOf("authorization" to "Bearer <session token>"),
    )
)

val room = bird.subscribe("presence-room-42")
if (room is PresenceChannel) {
    room.bind(BirdProtocol.Event.SUBSCRIPTION_SUCCEEDED) {
        println("me: ${room.myId}, members: ${room.members.keys}")
    }
    room.bind(BirdProtocol.Event.MEMBER_ADDED) { member -> println("joined: $member") }
}

अपने स्वयं के नेटवर्किंग स्टैक से साइन करने के लिए इसके बजाय एक authorizer पास करें।

सर्वर से अस्वीकृति (ख़राब सिग्नेचर, क्षमता से अधिक ऐप) कनेक्शन पर आती है, चैनल पर नहीं, क्योंकि वायर में चैनल एट्रिब्यूशन नहीं होता। इन्हें onError से ऑब्ज़र्व करें। आपके authorizer के अंदर की विफलता चैनल पर bird:subscription_error एमिट करती है।

किसी सदस्य को साइन इन करें

signin() एज को बताता है कि यह कनेक्शन किस सदस्य का है। यही पहचान API को किसी सदस्य को संबोधित करने या उनके कनेक्शन समाप्त करने की अनुमति देती है, और यही उस ऐप की शर्त पूरी करती है जो अधिकृत कनेक्शन अनिवार्य करने के लिए कॉन्फ़िगर किया गया है।

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
        memberAuthEndpoint = "https://your-backend.example.com/bird/auth/member",
    )
)

val me = bird.signin() // suspending
println("signed in as ${me.memberId}")

bird.member.bind("order.shipped") { data ->
    println("addressed to me: $data")
}

signin() एक बार कॉल करें। पहचान कनेक्शन पर बनी रहती है, इसलिए रीकनेक्ट के बाद क्लाइंट स्वचालित रूप से फिर से साइन इन करता है। एक असफल स्वचालित साइन-इन के पास throw करने के लिए कोई सक्रिय कॉल नहीं होता, इसलिए यह onSigninError पर दिखाई देता है। इससे एक विफल member endpoint चैनल सब्सक्रिप्शन को बाधित नहीं करता।

कनेक्शन लाइफ़साइकल

bird.onConnectionStateChange { previous, current ->
    println("connection: $previous -> $current")
}
bird.onError { error ->
    if (error.code == 4009) println("session ended elsewhere")
}

रीकनेक्शन स्वचालित है, 1s से 30s की सीमा तक full-jitter exponential backoff के साथ। 4000-4099 में क्लोज़ कोड अस्वीकृतियाँ हैं और टर्मिनल हैं: क्लाइंट रुक जाता है और कोड रिपोर्ट करता है, क्योंकि अस्वीकृति एक निर्णय है न कि क्षणिक विफलता। 4200-4299 में कोड तुरंत रीकनेक्ट करते हैं; बाकी सब बैकऑफ़ करते हैं। हर रीकनेक्ट पर चैनल ताज़ा अधिकरण के साथ फिर से सब्सक्राइब होते हैं। देखें कनेक्शन लाइफ़साइकल।

ट्रांसपोर्ट हर non-loopback होस्ट के लिए TLS है। allowInsecure केवल localhost, 127.0.0.1 और [::1] के लिए ws:// की अनुमति देता है, इसलिए किसी development target से कॉपी किया गया config चुपचाप production ट्रैफ़िक को डाउनग्रेड नहीं कर सकता।

Client events

ऐप की client-events सेटिंग सक्षम होने पर, किसी private या presence चैनल पर सब्सक्राइब्ड क्लाइंट सीधे अपने peers को पब्लिश कर सकता है:

room.trigger("client-typing", buildJsonObject { put("on", true) })

देखें client events।

सोर्स

github.com/messagebird/bird-sdk-kotlin, MIT लाइसेंस प्राप्त। समस्याएँ वहाँ रिपोर्ट करें।