Wyślij swoje pierwsze zdarzenie w czasie rzeczywistym

Realtime dostarcza zdarzenia przez WebSockets. Twój serwer publikuje do kanału, a każdy podłączony klient subskrybujący ten kanał odbiera zdarzenie. Ten przewodnik prowadzi jedną ścieżką: utwórz aplikację, zasubskrybuj klienta i opublikuj z serwera.

Darmowy plan obejmuje 100 równoczesnych połączeń i 200 000 wiadomości dziennie, we wszystkich aplikacjach obszaru roboczego. Płatne plany zaczynają się od 25 $ miesięcznie; zobacz Cennik Realtime.

1. Utwórz aplikację

Aplikacja to izolowane środowisko z własnymi poświadczeniami i kanałami. Region wybierasz podczas tworzenia i nie możesz go później zmienić.

Otwórz Realtime > Apps w panelu.
Wybierz Create app.
Wpisz nazwę w polu Name.
Wybierz Region: United States (us1) lub Europe (eu1).
Wybierz Create app.

Save your app credentials wyświetla następnie trzy wartości, jednorazowo:

App ID to rap_… id identyfikujące aplikację w wywołaniach Bird API.
Key jest publiczny. Klienty łączą się za jego pomocą i można go bezpiecznie umieścić w kodzie klienckim.
Secret jest powiązany z kluczem i służy do uwierzytelniania wywołań po stronie serwera oraz podpisywania autoryzacji kanałów. Traktuj go jak hasło.

Skopiuj wszystkie trzy wartości przed wybraniem I've saved my secret, ponieważ secret nie zostanie ponownie wyświetlony. Następnie utwórz klucz Bird API z uprawnieniem realtime na stronie Developers > API keys i wyeksportuj to, czego wymagają kolejne kroki:

Przykład kodu

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

2. Subskrybuj z poziomu klienta

Wybierz jednego z trzech klientów, po jednym na platformę, wszystkie korzystające z tego samego protokołu: @messagebird/realtime dla przeglądarki, BirdRealtime dla platform Apple i com.messagebird:bird-realtime dla Androida i serwerowej 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")
}

Klient identyfikuje aplikację po kluczu i wybiera edge na podstawie regionu, więc nie musisz konfigurować hosta:

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

Wszystkie trzy klienty otwierają gniazdo podczas tworzenia, więc możesz subskrybować bez osobnego wywołania połączenia. Subskrybowanie przed nawiązaniem połączenia też jest dozwolone: kanały są rejestrowane lokalnie i wysyłane, gdy połączenie zostanie nawiązane, a także po każdym ponownym połączeniu.

orders to kanał publiczny, więc każdy klient z kluczem aplikacji może go subskrybować. Kanały o nazwach private-… lub presence-… wymagają autoryzacji każdej subskrypcji przez Twój serwer. Zobacz Autoryzacja kanałów.

Kanałów nie tworzy się ani nie konfiguruje nigdzie. Kanał istnieje, dopóki co najmniej jedno połączenie go subskrybuje, i znika, gdy ostatnie połączenie się rozłączy.

3. Publikuj z serwera

Publikowanie to wywołanie po stronie serwera. Uwierzytelnia się kluczem Bird API i przesyła klucz oraz sekret aplikacji, aby edge je zaakceptował. Nigdy nie publikuj z klienta, ponieważ wymagałoby to udostępnienia sekretu.

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

Po dostarczeniu zdarzenia przez edge subskrybujący klient wyświetla order changed { id: 42, status: 'shipped' }. Jeśli nic nie dociera, sprawdź, czy klucz klienta i dane uwierzytelniające serwera należą do tej samej aplikacji oraz czy nazwy kanałów dokładnie się zgadzają. Jedno wywołanie publish może wskazać do 100 kanałów. Aby wysłać do 10 różnych zdarzeń w jednym żądaniu, opublikuj paczkę.

Publikowanie kończy się, gdy edge zaakceptuje zdarzenie. Dostarczanie do podłączonych klientów jest asynchroniczne, więc 200 oznacza zaakceptowane, a nie odebrane.

4. Sprawdź w dashboardzie

Realtime > Metrics pokazuje szczytową i średnią liczbę równoczesnych połączeń oraz wiadomości, per aplikacja lub w całym obszarze roboczym. Wykresy raportują dzienne punkty użycia, więc potwierdź zdarzenie w momencie jego nadejścia, korzystając z wyjścia klienta z kroku 3.

Następne kroki

Autoryzacja kanałów obejmuje kanały prywatne i presence oraz sygnaturę zwracaną przez Twój backend.
Publikowanie zdarzenia zawiera pełne żądanie i odpowiedź, w tym stan per kanał w momencie publikacji.
Webhooki i zdarzenia wyjaśnia, jak odbierać zdarzenia realtime.*, takie jak zajęcie kanału lub dołączenie członka, na własnym endpoincie.

Powiązane zasoby

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

RealtimePoznaj możliwości

Build your first integrationPodążaj ścieżką nauki

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy