Swift SDK

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

इसकी कोई डिपेंडेंसी नहीं है (ट्रांसपोर्ट के लिए URLSessionWebSocketTask, फ़्रेम के लिए JSONSerialization)। यह iOS 15+, macOS 12+, tvOS 15+, watchOS 8+ और Linux पर चलता है।

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

इंस्टॉल करें

Xcode में File > Add Package Dependencies चुनें और रिपॉज़िटरी URL दर्ज करें। Package.swift में:

dependencies: [
    .package(url: "https://github.com/messagebird/bird-sdk-swift.git", from: "0.1.1")
]

फिर प्रोडक्ट को उस टारगेट में जोड़ें जो इसका इस्तेमाल करता है:

.target(
    name: "YourApp",
    dependencies: [.product(name: "BirdRealtime", package: "bird-sdk-swift")]
)

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

import BirdRealtime

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1"
))

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

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

let orders = bird.subscribe("orders")
orders.bind("order-updated") { data in
    print("order changed:", data ?? "")
}

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

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

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

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1",
    authEndpoint: URL(string: "https://your-backend.example.com/bird/auth")!,
    authHeaders: ["authorization": "Bearer <session token>"]
))

guard let room = bird.subscribe("presence-room-42") as? PresenceChannel else { return }
room.bind(BirdProtocol.Event.subscriptionSucceeded) { _ in
    print("me:", room.myId ?? "?", "members:", Array(room.members.keys))
}
room.bind(BirdProtocol.Event.memberAdded) { member in
    print("joined:", member ?? "")
}

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

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

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

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

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1",
    memberAuthEndpoint: URL(string: "https://your-backend.example.com/bird/auth/member")!
))

let me = try await bird.signin()
print("signed in as", me.memberId)

bird.member.bind("order.shipped") { data in
    print("addressed to me:", data ?? "")
}

signin() को एक बार कॉल करें। पहचान कनेक्शन पर बनी रहती है, इसलिए दोबारा कनेक्ट होने के बाद क्लाइंट अपने-आप फिर से साइन इन करता है। अपने-आप होने वाले साइन-इन के विफल होने पर कोई सक्रिय कॉल नहीं होती जिससे त्रुटि थ्रो की जा सके, इसलिए विफलता onSigninError पर दिखती है। इससे विफल हो रहा सदस्य एंडपॉइंट चैनल सब्सक्रिप्शन को प्रभावित नहीं करता।

कनेक्शन का जीवनचक्र

bird.onConnectionStateChange { previous, current in
    print("connection: \(previous) → \(current)")
}
bird.onError { error in
    if error.code == 4009 { print("session ended elsewhere") }
}

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

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

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

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

try room.trigger("client-typing", data: ["on": true])

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

सोर्स

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