Envoyer votre premier événement en temps réel

Realtime transmet des événements via WebSockets. Votre serveur publie sur un canal, et chaque client connecté abonné à ce canal reçoit l'événement. Ce guide suit un seul parcours : créer une application, abonner un client et publier depuis votre serveur.

Le plan gratuit couvre 100 connexions simultanées et 200 000 messages par jour, pour l'ensemble des apps d'un espace de travail. Les plans payants commencent à 25 $ par mois ; voir Tarifs Realtime.

1. Créer une application

Une application est un environnement isolé avec ses propres identifiants et canaux. Vous choisissez sa région à la création, et vous ne pouvez plus la modifier ensuite.

Ouvrez Realtime > Apps dans le tableau de bord.
Sélectionnez Create app.
Saisissez un nom dans Name.
Sélectionnez une Region : United States (us1) ou Europe (eu1).
Sélectionnez Create app.

Save your app credentials affiche ensuite trois valeurs, une seule fois :

App ID est un identifiant rap_… qui identifie l'application dans les appels Bird API.
Key est publique. Les clients se connectent avec elle, et elle peut figurer sans risque dans le code client.
Secret s'associe à la clé pour authentifier les appels côté serveur et signer l'autorisation de canal. Traitez-le comme un mot de passe.

Copiez les trois avant de sélectionner I've saved my secret, car le secret ne sera plus affiché. Créez ensuite une clé Bird API avec le scope realtime sur la page Developers > Clés API, et exportez ce dont les étapes suivantes ont besoin :

Exemple de code

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

2. S'abonner depuis un client

Choisissez parmi trois clients, un par plateforme, tous utilisant le même protocole : @messagebird/realtime pour le navigateur, BirdRealtime pour les plateformes Apple, et com.messagebird:bird-realtime pour Android et la JVM serveur.

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

Le client identifie l'app par sa clé et choisit le point d'accès à partir de la région, vous n'avez donc pas besoin de configurer un hôte :

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

Les trois clients ouvrent le socket dès leur construction, vous pouvez donc vous abonner sans appel de connexion séparé. S'abonner avant que le socket soit actif fonctionne aussi : les canaux sont enregistrés localement et envoyés dès que la connexion est établie, et à nouveau après chaque reconnexion.

orders est un canal public, donc tout client disposant de la clé de l'app peut s'y abonner. Les canaux nommés private-… ou presence-… nécessitent que votre serveur autorise chaque abonnement. Voir Autorisation des canaux.

Les canaux ne sont ni créés ni configurés quelque part. Un canal existe tant qu'au moins une connexion y est abonnée, et disparaît quand la dernière se retire.

3. Publier depuis votre serveur

La publication est un appel côté serveur. Elle s'authentifie avec votre clé Bird API et transmet la clé et le secret de l'app pour que le point d'accès l'accepte. Ne publiez jamais depuis un client, car cela impliquerait d'exposer le 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" }
  }'

Une fois que le point d'accès a distribué l'événement, le client abonné affiche order changed { id: 42, status: 'shipped' }. Si rien n'arrive, vérifiez que la clé client et les identifiants serveur appartiennent à la même app et que les noms de canaux correspondent exactement. Une publication peut désigner jusqu'à 100 canaux. Pour envoyer jusqu'à 10 événements différents en une seule requête, publiez un lot.

La publication se résout dès que le point d'accès accepte l'événement. La distribution aux clients connectés est asynchrone, donc un 200 signifie accepté et non reçu.

4. Vérifier dans le tableau de bord

Realtime > Metrics affiche le pic et la moyenne des connexions simultanées et des messages, par app ou pour l'ensemble de l'espace de travail. Les graphiques présentent des points d'utilisation quotidienne ; utilisez donc la sortie du client de l'étape 3 pour confirmer l'événement à son arrivée.

Étapes suivantes

Autorisation des canaux couvre les canaux privés et de présence, ainsi que la signature renvoyée par votre backend.
Publier un événement contient la requête et la réponse complètes, y compris l'état par canal au moment de la publication.
Webhooks & events explique comment recevoir des événements realtime.*, tels qu'un canal devenant occupé ou un membre rejoignant, sur votre propre endpoint.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

RealtimeExplorer la fonctionnalité

Build your first integrationSuivre le parcours d'apprentissage

Essayez la pratique et obtenez un guide d'implémentation