Invia il tuo primo evento realtime

Realtime consegna eventi tramite WebSocket. Il tuo server pubblica su un canale e ogni client connesso iscritto a quel canale riceve l'evento. Questa guida segue un percorso: creare un'app, iscrivere un client e pubblicare dal server.

Il piano gratuito copre 100 connessioni simultanee e 200.000 messaggi al giorno, su tutte le app di uno spazio di lavoro. I piani a pagamento partono da 25 $ al mese; vedi Prezzi di Realtime.

1. Creare un'app

Un'app è un ambiente isolato con credenziali e canali propri. Scegli la regione al momento della creazione e non puoi cambiarla in seguito.

Apri Realtime > Apps nella dashboard.
Seleziona Create app.
Inserisci un nome in Name.
Seleziona una Region: United States (us1) o Europe (eu1).
Seleziona Create app.

Save your app credentials mostra quindi tre valori, una sola volta:

App ID è un rap_… id che identifica l'app nelle chiamate Bird API.
Key è pubblica. I client si connettono con essa ed è sicuro includerla nel codice client.
Secret si abbina alla key per autenticare le chiamate lato server e firmare l'autorizzazione del canale. Trattalo come una password.

Copia tutti e tre i valori prima di selezionare I've saved my secret, perché il secret non viene più mostrato. Poi crea una chiave Bird API con lo scope realtime nella pagina Developers > API keys, ed esporta ciò che serve ai passaggi successivi:

Esempio di codice

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

2. Iscriversi da un client

Scegli tra tre client, uno per piattaforma, tutti con lo stesso protocollo: @messagebird/realtime per il browser, BirdRealtime per le piattaforme Apple e com.messagebird:bird-realtime per Android e la JVM lato server.

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

Il client identifica l'app tramite la sua key e sceglie l'edge dalla region, quindi non devi configurare un host:

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

Tutti e tre i client aprono il socket durante la costruzione, quindi puoi iscriverti senza una chiamata di connessione separata. Iscriversi prima che il socket sia attivo va bene: i canali vengono registrati localmente e inviati non appena la connessione è stabilita, e di nuovo dopo ogni riconnessione.

orders è un canale pubblico, quindi qualsiasi client con la key dell'app può iscriversi. I canali denominati private-… o presence-… richiedono che il tuo server autorizzi ogni iscrizione. Vedi Autorizzazione dei canali.

I canali non vengono creati né configurati da nessuna parte. Un canale esiste finché almeno una connessione è iscritta, e scompare quando l'ultima si disconnette.

3. Pubblicare dal server

La pubblicazione è una chiamata lato server. Si autentica con la tua Bird API key e include la key e il secret dell'app affinché l'edge la accetti. Non pubblicare mai da un client, perché significherebbe esporre il secret.

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

Dopo che l'edge consegna l'evento, il client iscritto stampa order changed { id: 42, status: 'shipped' }. Se non arriva nulla, verifica che la key del client e le credenziali del server appartengano alla stessa app e che i nomi dei canali corrispondano esattamente. Una singola pubblicazione può indicare fino a 100 canali. Per inviare fino a 10 eventi diversi in una sola richiesta, pubblica un batch.

La pubblicazione si risolve quando l'edge accetta l'evento. La consegna ai client connessi è asincrona, quindi un 200 significa accettato, non ricevuto.

4. Verificare nella dashboard

Realtime > Metrics mostra il picco e la media delle connessioni simultanee e dei messaggi, per app o sull'intero spazio di lavoro. I grafici riportano punti di utilizzo giornaliero, quindi usa l'output del client dal passaggio 3 per confermare l'evento al suo arrivo.

Passaggi successivi

Autorizzazione dei canali tratta i canali privati e di presenza, e la firma che il tuo backend restituisce.
Pubblicare un evento contiene la richiesta e la risposta complete, incluso lo stato per canale al momento della pubblicazione.
Webhook ed eventi spiega come ricevere eventi realtime.*, ad esempio un canale che diventa occupato o un membro che si unisce, sul tuo endpoint.

Risorse correlate

Continua con la documentazione, le guide e gli esempi per questo argomento.

RealtimeEsplora la funzionalità

Build your first integrationSegui il percorso di apprendimento

Prova l'esercitazione e ottieni un brief di implementazione