Erstes Realtime-Event senden

Realtime liefert Events über WebSockets. Ihr Server veröffentlicht auf einem Kanal, und jeder verbundene Client, der diesen Kanal abonniert hat, empfängt das Event. Diese Anleitung folgt einem Pfad: App erstellen, Client abonnieren und von Ihrem Server veröffentlichen.

Der kostenlose Plan umfasst 100 gleichzeitige Verbindungen und 200.000 Nachrichten pro Tag, über alle Apps eines Workspace hinweg. Kostenpflichtige Pläne beginnen bei 25 $ pro Monat; siehe Realtime-Preise.

1. App erstellen

Eine App ist eine isolierte Umgebung mit eigenen Zugangsdaten und Kanälen. Sie wählen die Region beim Erstellen, und Sie können diese Region danach nicht mehr ändern.

Öffnen Sie Realtime > Apps im Dashboard.
Wählen Sie Create app.
Geben Sie einen Namen unter Name ein.
Wählen Sie eine Region: United States (us1) oder Europe (eu1).
Wählen Sie Create app.

Save your app credentials zeigt dann einmalig drei Werte:

App ID ist eine rap_…-ID, die die App in Bird-API-Aufrufen identifiziert.
Key ist öffentlich. Clients verbinden sich damit, und er kann bedenkenlos in Client-Code ausgeliefert werden.
Secret bildet zusammen mit dem Key das Authentifizierungspaar für serverseitige Aufrufe und die Signierung der Kanalautorisierung. Behandeln Sie es wie ein Passwort.

Kopieren Sie alle drei Werte, bevor Sie I've saved my secret wählen, denn das Secret wird nicht erneut angezeigt. Erstellen Sie dann einen Bird-API-Key mit dem realtime-Scope auf der Seite Developers > API keys und exportieren Sie, was die nächsten Schritte benötigen:

Codebeispiel

export BIRD_API_KEY="bk_us1_..."
export BIRD_REALTIME_KEY="your-app-key"
export BIRD_REALTIME_SECRET="your-app-secret"

2. Von einem Client abonnieren

Wählen Sie aus drei Clients, einen pro Plattform, alle mit demselben Protokoll: @messagebird/realtime für den Browser, BirdRealtime für Apple-Plattformen und com.messagebird:bird-realtime für Android und die Server-JVM.

npm install @messagebird/realtime

// Package.swift, or Xcode's File › Add Package Dependencies
dependencies: [
    .package(url: "https://github.com/messagebird/bird-sdk-swift.git", from: "0.1.0")
]

// build.gradle.kts
dependencies {
    implementation("com.messagebird:bird-realtime:0.1.3")
}

Der Client identifiziert die App anhand ihres Keys und wählt den Edge aus der Region, sodass Sie keinen Host konfigurieren müssen:

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
});

const orders = bird.subscribe("orders");
orders.bind("order-updated", (data) => {
  console.log("order changed", data);
});

import BirdRealtime

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

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

import com.bird.realtime.BirdRealtime
import com.bird.realtime.BirdRealtimeOptions

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
    )
)

val orders = bird.subscribe("orders")
orders.bind("order-updated") { data ->
    println("order changed: $data")
}

Alle drei Clients öffnen den Socket bei der Konstruktion, sodass Sie ohne einen separaten Verbindungsaufruf abonnieren können. Ein Abonnement vor dem Aufbau des Sockets ist ebenfalls möglich: Channels werden lokal registriert und gesendet, sobald die Verbindung steht, und erneut nach jedem Reconnect.

orders ist ein öffentlicher Channel, sodass jeder Client mit dem App-Key abonnieren kann. Channels mit dem Namen private-… oder presence-… erfordern, dass Ihr Server jedes Abonnement autorisiert. Siehe Channels autorisieren.

Channels werden nirgendwo erstellt oder konfiguriert. Ein Channel existiert, solange mindestens eine Verbindung ihn abonniert hat, und verschwindet, wenn die letzte Verbindung ihn verlässt.

3. Von Ihrem Server publizieren

Publizieren ist ein serverseitiger Aufruf. Er authentifiziert sich mit Ihrem Bird API Key und überträgt den Key und das Secret der App, damit der Edge ihn akzeptiert. Publizieren Sie niemals von einem Client, da Sie damit das Secret ausliefern würden.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY,
  realtime: {
    key: process.env.BIRD_REALTIME_KEY,
    secret: process.env.BIRD_REALTIME_SECRET,
  },
});

await bird.realtime.publish("rap_01krdgeqcxet5s7t44vh8rt9mg", {
  event: "order-updated",
  channels: ["orders"],
  data: { id: 42, status: "shipped" },
});

import os

from bird import Bird

client = Bird(
    api_key=os.environ["BIRD_API_KEY"],
    realtime_key=os.environ["BIRD_REALTIME_KEY"],
    realtime_secret=os.environ["BIRD_REALTIME_SECRET"],
)

client.realtime.publish(
    "rap_01krdgeqcxet5s7t44vh8rt9mg",
    event="order-updated",
    channels=["orders"],
    data={"id": 42, "status": "shipped"},
)

client, err := bird.NewClient(
	option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
	option.WithRealtimeCredentials(os.Getenv("BIRD_REALTIME_KEY"), os.Getenv("BIRD_REALTIME_SECRET")),
)
if err != nil {
	log.Fatal(err)
}

_, err = client.Realtime.Publish(context.Background(), "rap_01krdgeqcxet5s7t44vh8rt9mg", bird.RealtimePublishParams{
	Event:    "order-updated",
	Channels: []string{"orders"},
	Data:     map[string]any{"id": 42, "status": "shipped"},
})
if err != nil {
	log.Fatal(err)
}

use MessageBird\Bird;
use MessageBird\RealtimeOptions;
use MessageBird\Wire\Model\RealtimePublish;

$bird = new Bird(
    getenv('BIRD_API_KEY') ?: '',
    realtime: new RealtimeOptions(
        key: getenv('BIRD_REALTIME_KEY') ?: '',
        secret: getenv('BIRD_REALTIME_SECRET') ?: '',
    ),
);

$bird->realtime->publish('rap_01krdgeqcxet5s7t44vh8rt9mg', (new RealtimePublish())
    ->setEvent('order-updated')
    ->setChannels(['orders'])
    ->setData(['id' => 42, 'status' => 'shipped']));

curl -X POST https://us1.platform.bird.com/v1/realtime/apps/rap_01krdgeqcxet5s7t44vh8rt9mg/events \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
  -H "X-Realtime-Secret: $BIRD_REALTIME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order-updated",
    "channels": ["orders"],
    "data": { "id": 42, "status": "shipped" }
  }'

Nachdem der Edge das Event zugestellt hat, gibt der abonnierte Client order changed { id: 42, status: 'shipped' } aus. Falls nichts ankommt, prüfen Sie, ob der Client-Key und die Server-Zugangsdaten zur selben App gehören und ob die Channel-Namen exakt übereinstimmen. Ein Publish kann bis zu 100 Channels benennen. Um bis zu 10 verschiedene Events in einer Anfrage zu senden, verwenden Sie Batch publizieren.

Publizieren wird aufgelöst, sobald der Edge das Event akzeptiert. Die Zustellung an verbundene Clients erfolgt asynchron, sodass ein 200 „akzeptiert

4. Im Dashboard prüfen

Realtime > Metrics zeigt Spitzen- und Durchschnittswerte für gleichzeitige Verbindungen und Nachrichten, pro App oder über den gesamten Workspace hinweg. Die Diagramme melden tägliche Nutzungspunkte – verwenden Sie daher die Client-Ausgabe aus Schritt 3, um das Event bei Eintreffen zu bestätigen.

Nächste Schritte

Channels autorisieren behandelt private und Presence-Channels sowie die Signatur, die Ihr Backend zurückgibt.
Event veröffentlichen enthält die vollständige Anfrage und Antwort, einschließlich des kanalspezifischen Status zum Zeitpunkt der Veröffentlichung.
Webhooks & Events erklärt, wie Sie realtime.*-Events empfangen, z. B. wenn ein Channel belegt wird oder ein Mitglied beitritt, auf Ihrem eigenen Endpoint.