Swift SDK

BirdRealtime es el cliente Swift oficial de Bird Realtime: mantiene un WebSocket hacia el edge de Bird, se suscribe a canales y entrega eventos a medida que se publican. Está escrito a mano en lugar de generado, porque Realtime es un plano de datos WebSocket en vez de una superficie REST, y habla el mismo dialecto de protocolo que el cliente de navegador.

No tiene dependencias (URLSessionWebSocketTask para transporte, JSONSerialization para frames) y funciona en iOS 15+, macOS 12+, tvOS 15+, watchOS 8+ y Linux.

Este cliente es el lado de recepción. Publicar eventos, autorizar canales y terminar conexiones son operaciones del lado del servidor en la Bird API; consulta publicar eventos.

Instalación

En Xcode, selecciona File > Add Package Dependencies e introduce la URL del repositorio. En un Package.swift:

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

Luego añade el producto al target que lo usa:

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

Construir un cliente

import BirdRealtime

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

Solo appKey es obligatorio, más region (us1 o eu1, que resuelve el host del edge) o un wsHost explícito. La app key es pública y se incluye en el código del cliente: identifica la app, no autoriza nada. Los handlers se ejecutan en la cola principal a menos que pases un deliveryQueue.

Suscribirse a un canal

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

Un canal cuyo nombre no tiene el prefijo private- ni presence- es público: cualquier cliente con la app key puede suscribirse, así que considera su contenido legible por cualquiera que pueda abrir tu app.

Canales privados y de presencia

Los canales privados y de presencia los autoriza tu backend, que guarda el secreto de la app. Apunta el cliente a tu endpoint: envía un POST con {"connection_id", "channel_name"} y espera {"auth", "member_data"?} de vuelta.

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

Pasa un closure authorizer en su lugar para firmar a través de tu propio stack de red.

Un rechazo del servidor (una firma inválida, una app que excede su capacidad) llega a la conexión en vez del canal, porque el protocolo no incluye atribución de canal. Obsérvalos con onError. Un fallo dentro de tu autorizador sí emite bird:subscription_error en el canal.

Identificar a un miembro

signin() indica al edge a qué miembro pertenece esta conexión. Esa identidad es lo que permite al API dirigirse a un miembro o terminar sus conexiones, y es lo que satisface una app configurada para requerir conexiones autorizadas.

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

Llama a signin() una sola vez. La identidad permanece en la conexión, así que el cliente inicia sesión de nuevo automáticamente tras una reconexión. Un inicio de sesión automático fallido no tiene una llamada activa desde la cual lanzar un error, por lo que aparece en onSigninError. Esto evita que un endpoint de miembro con fallos interfiera con las suscripciones a canales.

Ciclo de vida de la conexión

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

La reconexión es automática, con backoff exponencial de jitter completo desde 1 s hasta un tope de 30 s. Los códigos de cierre en el rango 4000–4099 son rechazos terminales: el cliente se detiene e informa el código, porque un rechazo es una decisión y no un fallo transitorio. Los códigos en 4200–4299 reconectan de inmediato; cualquier otro aplica backoff. Los canales se resuscriben con autorización nueva en cada reconexión. Consulta ciclo de vida de la conexión.

El transporte es TLS para todo host que no sea loopback. allowInsecure permite ws:// solo para localhost, 127.0.0.1 y [::1], de modo que una configuración copiada de un entorno de desarrollo no puede degradar silenciosamente el tráfico de producción.

Eventos de cliente

Con la configuración de eventos de cliente de la app habilitada, un cliente suscrito a un canal privado o de presencia puede publicar directamente a sus pares:

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

Consulta eventos de cliente.

Código fuente

github.com/messagebird/bird-sdk-swift, con licencia MIT. Reporta problemas allí.