Envie seu primeiro evento em tempo real

O Realtime entrega eventos via WebSockets. Seu servidor publica em um canal, e cada cliente conectado inscrito nesse canal recebe o evento. Este guia segue um caminho: criar um app, inscrever um cliente e publicar a partir do seu servidor.

O plano gratuito cobre 100 conexões simultâneas e 200.000 mensagens por dia, considerando todos os apps de um espaço de trabalho. Os planos pagos começam em US$ 25 por mês; veja Preços do Realtime.

1. Crie um app

Um app é um ambiente isolado com suas próprias credenciais e canais. Você escolhe a região ao criá-lo e não pode alterá-la depois.

Abra Realtime > Apps no painel.
Selecione Create app.
Insira um nome em Name.
Selecione uma Region: United States (us1) ou Europe (eu1).
Selecione Create app.

Save your app credentials exibe três valores, uma única vez:

App ID é um id rap_… que identifica o app em chamadas Bird API.
Key é pública. Os clientes se conectam com ela, e é seguro incluí-la no código do cliente.
Secret é pareada com a key para autenticar chamadas do lado do servidor e assinar a autorização de canal. Trate-a como uma senha.

Copie os três valores antes de selecionar I've saved my secret, porque o secret não é exibido novamente. Em seguida, crie uma chave Bird API com o escopo realtime na página Developers > API keys e exporte o que as próximas etapas precisam:

Exemplo de código

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

2. Inscrever-se a partir de um cliente

Escolha entre três clientes, um por plataforma, todos usando o mesmo protocolo: @messagebird/realtime para o navegador, BirdRealtime para plataformas Apple e com.messagebird:bird-realtime para Android e a JVM do servidor.

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

O cliente identifica o app pela sua key e escolhe o edge a partir da região, então você não precisa configurar um 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")
}

Os três clientes abrem o socket ao serem construídos, então você pode se inscrever sem uma chamada de conexão separada. Inscrever-se antes de o socket estar ativo também funciona: os canais são registrados localmente e enviados assim que a conexão é estabelecida, e novamente após cada reconexão.

orders é um canal público, então qualquer cliente com a key do app pode se inscrever. Canais nomeados private-… ou presence-… exigem que o seu servidor autorize cada inscrição. Veja Autorizando canais.

Canais não são criados nem configurados em lugar algum. Um canal existe enquanto pelo menos uma conexão estiver inscrita nele e desaparece quando a última sai.

3. Publicar a partir do seu servidor

A publicação é uma chamada do lado do servidor. Ela se autentica com a sua Bird API key e inclui a key e o secret do app para que o edge aceite. Nunca publique a partir de um cliente, porque isso significaria expor o 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" }
  }'

Depois que o edge entrega o evento, o cliente inscrito imprime order changed { id: 42, status: 'shipped' }. Se nada chegar, verifique se a key do cliente e as credenciais do servidor pertencem ao mesmo app e se os nomes dos canais coincidem exatamente. Uma publicação pode indicar até 100 canais. Para enviar até 10 eventos diferentes em uma única solicitação, publique um lote.

A publicação é resolvida assim que o edge aceita o evento. A entrega aos clientes conectados é assíncrona, então um 200 significa aceito, não recebido.

4. Confira no dashboard

Realtime > Metrics mostra conexões simultâneas e mensagens de pico e média, por app ou em todo o espaço de trabalho. Os gráficos reportam pontos de uso diário, então use a saída do cliente do passo 3 para confirmar o evento assim que ele chegar.

Próximos passos

Autorizando canais abrange canais privados e de presença, e a assinatura que o seu backend retorna.
Publicar um evento contém a solicitação e a resposta completas, incluindo o estado por canal no momento da publicação.
Webhooks e eventos explica como receber eventos realtime.*, como um canal se tornando ocupado ou um membro entrando, no seu próprio endpoint.

Continue com a documentação, guias e exemplos sobre este tópico.

Experimente na prática e obtenha um resumo de implementação