Documentação/ Backend as a Service/ Tempo real (Centrifugo)

Tempo real (Centrifugo)

Mensagens WebSocket em tempo real com canais, presença e pub/sub.

Criar um servidor em tempo real

Para criar uma instância em tempo real:

  1. Acesse Servidores em tempo real no painel do sh0.
  2. Clique em Criar servidor em tempo real.
  3. Digite um nome (por exemplo, "my-app-realtime").
  4. Clique em Criar. O sh0 faz o deploy de uma instância do Centrifugo com SSL automático.

Seu servidor em tempo real fica acessível imediatamente em wss://<name>.sh0.app/connection/websocket.

Canais

Os canais são a abstração principal do Centrifugo. Os clientes se inscrevem em canais e recebem as mensagens publicadas neles. Os nomes de canal são strings — você define a convenção de nomenclatura.

Namespaces

Use namespaces de canais para agrupar canais com configuração compartilhada. Por exemplo, os canais chamados chat:room-1 e chat:room-2 pertencem ao namespace chat (usando : como separador).

Configure, no nível do namespace, a retenção de histórico, o rastreamento de presença e as permissões na configuração do Centrifugo.

Presença

Ative a presença em um canal para acompanhar quais usuários estão inscritos no momento. As informações de presença incluem o ID do cliente e o ID do usuário. Útil para:

  • Mostrar quem está online em uma sala de chat.
  • Exibir os colaboradores ativos em um documento.
  • Acompanhar o número de espectadores de uma transmissão ao vivo.

API de publicação

Publique mensagens do seu backend em qualquer canal pela API HTTP:

POST https://<name>.sh0.app/api/publish
Content-Type: application/json
Authorization: apikey <your-api-key>
{
"channel": "chat:room-42",
"data": { "text": "Hello!", "user": "alice" }
}

A chave de API é gerada quando você cria o servidor em tempo real e fica visível no painel.

Tip
A API de publicação é um simples HTTP POST — chame-a de qualquer linguagem de backend. Nenhuma conexão WebSocket é necessária no seu servidor.

Cliente JavaScript

Instale o cliente JavaScript do Centrifugo:

npm install centrifuge

Conecte-se e inscreva-se:

import { Centrifuge } from 'centrifuge';
const client = new Centrifuge(
'wss://my-realtime.sh0.app/connection/websocket'
);
const sub = client.newSubscription('chat:room-42');
sub.on('publication', (ctx) => {
console.log(ctx.data);
});
sub.subscribe();
client.connect();

Autenticação

O Centrifugo oferece suporte a autenticação baseada em JWT. Ao criar a conexão do cliente, passe um token:

const client = new Centrifuge(
'wss://my-realtime.sh0.app/connection/websocket',
{ token: jwtToken }
);

O token deve conter a claim sub (subject) do usuário. Se você usa o serviço de autenticação do sh0 (Logto), o token de acesso funciona diretamente.

Painel de administração

O Centrifugo inclui um painel de administração integrado para monitorar seu servidor em tempo real. Acesse-o pelo domínio do seu servidor em tempo real. O painel mostra:

  • O número de conexões ativas.
  • A taxa de mensagens por segundo.
  • Os canais ativos e seu número de inscritos.
  • As informações dos nós do servidor e seu status de saúde.
Anterior
Autenticação (Logto)
Próximo
Funções (Deno)