Verstuur je eerste realtime-event

Realtime levert events via WebSockets. Je server publiceert naar een kanaal en elke verbonden client die op dat kanaal is geabonneerd, ontvangt het event. Deze handleiding volgt één pad: maak een app, abonneer een client en publiceer vanaf je server.

Het gratis abonnement dekt 100 gelijktijdige verbindingen en 200.000 berichten per dag, over alle apps van een werkruimte. Betaalde abonnementen verhogen beide limieten; zie Realtime-prijzen.

1. Maak een app

Een app is een geïsoleerde omgeving met eigen inloggegevens en kanalen. Je kiest de regio bij het aanmaken, en je kunt die regio daarna niet meer wijzigen.

Open Realtime > Apps in het dashboard.
Selecteer Create app.
Voer een naam in bij Name.
Selecteer een Region: United States (us1) of Europe (eu1).
Selecteer Create app.

Save your app credentials toont vervolgens drie waarden, eenmalig:

App ID is een rap_…-id dat de app identificeert in Bird API-aanroepen.
Key is publiek. Clients verbinden ermee, en het is veilig om deze in clientcode mee te leveren.
Secret hoort bij de key om serveraanroepen te authenticeren en kanaalautorisatie te ondertekenen. Behandel het als een wachtwoord.

Kopieer alle drie voordat je op I've saved my secret klikt, want het secret wordt niet opnieuw getoond. Maak daarna een Bird API-key aan met het realtime-bereik op de pagina Developers > API keys, en exporteer wat de volgende stappen nodig hebben:

Codevoorbeeld

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

2. Abonneren vanuit een client

Kies uit drie clients, één per platform, die allemaal hetzelfde protocol spreken: @messagebird/realtime voor de browser, BirdRealtime voor Apple-platforms, en com.messagebird:bird-realtime voor Android en de 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")
}

De client identificeert de app aan de hand van de key en kiest de edge op basis van de regio, zodat je geen host hoeft te configureren:

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 drie de clients openen de socket zodra ze worden aangemaakt, dus je kunt je abonneren zonder een aparte verbindingsaanroep. Abonneren voordat de socket actief is, is ook prima: kanalen worden lokaal geregistreerd en verzonden zodra de verbinding tot stand komt, en opnieuw na elke herverbinding.

orders is een publiek kanaal, dus elke client met de app-key kan zich erop abonneren. Kanalen met de naam private-… of presence-… vereisen dat je server elk abonnement autoriseert. Zie Kanalen autoriseren.

Kanalen worden nergens aangemaakt of geconfigureerd. Een kanaal bestaat zolang ten minste één verbinding erop is geabonneerd, en verdwijnt wanneer de laatste vertrekt.

3. Publiceren vanuit je server

Publiceren is een server-side aanroep. De aanroep authenticeert met je Bird API-key en bevat de key en het secret van de app, zodat de edge het accepteert. Publiceer nooit vanuit een client, want dan zou je het secret meesturen.

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" }
  }'

Nadat de edge het event heeft afgeleverd, print de geabonneerde client order changed { id: 42, status: 'shipped' }. Als er niets binnenkomt, controleer dan of de client-key en de inloggegevens van de server bij dezelfde app horen en of de kanaalnamen exact overeenkomen. Eén publish kan tot 100 kanalen benoemen. Om tot 10 verschillende events in één verzoek te versturen, publiceer je een batch.

Publiceren wordt afgerond zodra de edge het event accepteert. Aflevering aan verbonden clients is asynchroon, dus een 200 betekent geaccepteerd, niet ontvangen.

4. Bekijk het in het dashboard

Realtime > Metrics toont piek- en gemiddelde gelijktijdige verbindingen en berichten, per app of over de hele werkruimte. De grafieken rapporteren dagelijkse gebruikspunten, dus gebruik de clientuitvoer uit stap 3 om het event te bevestigen zodra het binnenkomt.

Vervolgstappen

Kanalen autoriseren behandelt private kanalen en presence-kanalen, en de handtekening die je backend retourneert.
Een event publiceren bevat het volledige verzoek en antwoord, inclusief de status per kanaal op het moment van publiceren.
Webhooks & events legt uit hoe je realtime.*-events op je eigen endpoint ontvangt, zoals een kanaal dat bezet raakt of een lid dat toetreedt.

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Probeer de oefening en ontvang een implementatieoverzicht