Kotlin SDK

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

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

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

इंस्टॉल करें

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

Android पर अपने मैनिफ़ेस्ट में इंटरनेट अनुमति जोड़ें। लाइब्रेरी अब यह अनुमति अपनी ओर से नहीं जोड़ती:

<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। ऐप कुंजी सार्वजनिक है और क्लाइंट कोड में शामिल रहती है: यह ऐप की पहचान करती है, किसी चीज़ को अधिकृत नहीं करती।

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

disconnect() के बाद क्लाइंट दोबारा इस्तेमाल किया जा सकता है, इसलिए यह जानबूझकर वह वर्कर थ्रेड बनाए रखता है जिस तक क्लाइंट अपनी स्थिति सीमित रखता है। जब आपको किसी क्लाइंट की हमेशा के लिए ज़रूरत न रहे, तो उसे 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- प्रीफ़िक्स नहीं है, वह सार्वजनिक है: ऐप कुंजी वाला कोई भी क्लाइंट उसे सब्सक्राइब कर सकता है, इसलिए मानकर चलें कि आपका ऐप खोल सकने वाला कोई भी व्यक्ति उसकी सामग्री पढ़ सकता है।

प्राइवेट और प्रेज़ेंस चैनल

प्राइवेट और प्रेज़ेंस चैनलों को आपका बैकएंड अधिकृत करता है, जिसके पास ऐप सीक्रेट होता है। क्लाइंट को अपने एंडपॉइंट की ओर पॉइंट करें: यह {"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 से देखें। आपके ऑथराइज़र के भीतर होने वाली विफलता चैनल पर 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() को एक बार कॉल करें। पहचान कनेक्शन पर बनी रहती है, इसलिए रीकनेक्ट के बाद क्लाइंट अपने-आप फिर से साइन इन करता है। अपने-आप होने वाले विफल साइन-इन के पास कोई सक्रिय कॉल नहीं होती जिससे त्रुटि थ्रो की जा सके, इसलिए वह onSigninError पर दिखता है। इससे विफल हो रहा सदस्य एंडपॉइंट चैनल सब्सक्रिप्शन को प्रभावित नहीं करता।

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

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

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

हर नॉन-लूपबैक होस्ट के लिए ट्रांसपोर्ट TLS होता है। allowInsecure केवल localhost, 127.0.0.1 और [::1] के लिए ws:// की अनुमति देता है, ताकि किसी डेवलपमेंट टारगेट से कॉपी किया गया कॉन्फ़िगरेशन प्रोडक्शन ट्रैफ़िक को चुपचाप कम सुरक्षित न कर सके।

क्लाइंट इवेंट

ऐप की क्लाइंट-इवेंट सेटिंग चालू होने पर, किसी प्राइवेट या प्रेज़ेंस चैनल को सब्सक्राइब किया हुआ क्लाइंट सीधे अपने साथी क्लाइंट्स को इवेंट प्रकाशित कर सकता है:

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

क्लाइंट इवेंट देखें।

सोर्स

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