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 beginnen bij $ 25 per maand; 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.
Klik op Create app.
Voer een naam in bij Name.
Selecteer een Region: United States (us1) of Europe (eu1).
Klik op 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 kanaalauthorisatie 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: channels worden lokaal geregistreerd en verzonden zodra de verbinding tot stand komt, en opnieuw na elke herverbinding.

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

Channels worden nergens aangemaakt of geconfigureerd. Een channel 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 servercredentials bij dezelfde app horen en of de channelnamen exact overeenkomen. Eén publish kan tot 100 channels benoemen. Om tot 10 verschillende events in één verzoek te versturen, publiceer 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

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

Gerelateerde bronnen

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

RealtimeOntdek de mogelijkheid

Build your first integrationVolg het leerpad

Probeer de oefening en ontvang een implementatieoverzicht