Swift SDK

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

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

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

इंस्टॉल करें

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

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

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

.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, जो edge होस्ट रिज़ॉल्व करता है) या एक explicit wsHost। ऐप key पब्लिक है और क्लाइंट कोड में शिप होती है: यह ऐप की पहचान करती है, किसी चीज़ को authorize नहीं करती। हैंडलर मेन क्यू पर चलते हैं जब तक आप deliveryQueue पास नहीं करते।

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

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

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

Private और presence चैनल

Private और presence चैनलों को आपका बैकेंड authorize करता है, जिसके पास ऐप secret होता है। क्लाइंट को अपने endpoint की ओर पॉइंट करें: यह {"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 से ऑब्ज़र्व करें। आपके authorizer के अंदर कोई विफलता चैनल पर bird:subscription_error एमिट करती है।

किसी मेंबर को साइन इन करें

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

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() एक बार कॉल करें। पहचान कनेक्शन पर बनी रहती है, इसलिए रीकनेक्ट के बाद क्लाइंट अपने आप फिर से साइन इन करता है। किसी स्वचालित साइन-इन की विफलता में throw करने के लिए कोई सक्रिय कॉल नहीं होता, इसलिए यह onSigninError पर दिखाई देती है। इससे किसी विफल मेंबर endpoint से चैनल सब्सक्रिप्शन प्रभावित नहीं होते।

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

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

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

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

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

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

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

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

सोर्स

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