Swift SDK

BirdRealtime to oficjalny klient Swift dla Bird Realtime: utrzymuje połączenie WebSocket z krawędzią Bird, subskrybuje kanały i dostarcza zdarzenia w momencie ich publikacji. Jest napisany ręcznie, a nie generowany, ponieważ Realtime to warstwa danych WebSocket, a nie powierzchnia REST, i posługuje się tym samym protokołem co klient przeglądarkowy.

Nie ma zależności (URLSessionWebSocketTask do transportu, JSONSerialization do ramek) i działa na iOS 15+, macOS 12+, tvOS 15+, watchOS 8+ oraz Linux.

Ten klient to strona odbierająca. Publikowanie zdarzeń, autoryzacja kanałów i zamykanie połączeń to operacje po stronie serwera w Bird API; zobacz publikowanie zdarzeń.

Instalacja

W Xcode wybierz File > Add Package Dependencies i podaj URL repozytorium. W pliku Package.swift:

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

Następnie dodaj produkt do targetu, który go używa:

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

Tworzenie klienta

import BirdRealtime

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

Wymagany jest tylko appKey oraz region (us1 lub eu1, który rozwiązuje hosta krawędzi) albo jawny wsHost. Klucz aplikacji jest publiczny i trafia do kodu klienta: identyfikuje aplikację, nie autoryzuje niczego. Handlery działają w głównej kolejce, chyba że podasz deliveryQueue.

Subskrypcja kanału

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

Kanał, którego nazwa nie ma prefiksu private- ani presence-, jest publiczny: każdy klient z kluczem aplikacji może go subskrybować, więc traktuj jego zawartość jako czytelną dla każdego, kto może otworzyć Twoją aplikację.

Kanały prywatne i obecności

Kanały prywatne i obecności są autoryzowane przez Twój backend, który przechowuje sekret aplikacji. Skieruj klienta na swój endpoint: wysyła POST z {"connection_id", "channel_name"} i oczekuje w odpowiedzi {"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 ?? "")
}

Przekaż zamiast tego domknięcie authorizer, aby podpisywać przez własny stos sieciowy.

Odrzucenie z serwera (błędna sygnatura, aplikacja przekraczająca limit) dociera na połączenie, a nie na kanał, ponieważ protokół nie przekazuje przypisania do kanału. Obserwuj je za pomocą onError. Błąd wewnątrz Twojego autoryzatora emituje bird:subscription_error na kanale.

Logowanie członka

signin() informuje krawędź, do którego członka należy to połączenie. Ta tożsamość umożliwia API zaadresowanie członka lub zakończenie jego połączeń i spełnia wymagania aplikacji skonfigurowanej tak, aby wymagać autoryzowanych połączeń.

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 ?? "")
}

Wywołaj signin() raz. Tożsamość pozostaje na połączeniu, więc klient loguje się ponownie automatycznie po ponownym połączeniu. Nieudane automatyczne logowanie nie ma aktywnego wywołania, z którego mogłoby rzucić wyjątek, więc pojawia się na onSigninError. Dzięki temu niedziałający endpoint członka nie zakłóca subskrypcji kanałów.

Cykl życia połączenia

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

Ponowne połączenie jest automatyczne, z wykładniczym wycofaniem z pełnym jitterem od 1 s do limitu 30 s. Kody zamknięcia 4000–4099 to odmowy i są terminalne: klient zatrzymuje się i zgłasza kod, ponieważ odmowa to decyzja, a nie przejściowy błąd. Kody 4200–4299 powodują natychmiastowe ponowne połączenie; wszystkie inne stosują wycofanie. Kanały subskrybują się ponownie ze świeżą autoryzacją przy każdym ponownym połączeniu. Zobacz cykl życia połączenia.

Transport to TLS dla każdego hosta innego niż loopback. allowInsecure zezwala na ws:// tylko dla localhost, 127.0.0.1 i [::1], więc konfiguracja skopiowana z targetu deweloperskiego nie może cicho obniżyć bezpieczeństwa ruchu produkcyjnego.

Zdarzenia klienckie

Gdy ustawienie zdarzeń klienckich aplikacji jest włączone, klient subskrybujący kanał prywatny lub obecności może publikować bezpośrednio do swoich peerów:

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

Zobacz zdarzenia klienckie.

Źródło

github.com/messagebird/bird-sdk-swift, licencja MIT. Zgłaszaj problemy w tym repozytorium.