Canais privados

Um canal cujo nome começa com private- exige autorização do seu backend além da chave pública do app. Seu backend aprova o chamador para aquele canal e retorna uma assinatura calculada com o segredo do app.

Use canais privados para dados com escopo definido, como atualizações de pedidos de um cliente, o painel de um tenant ou as notificações de uma pessoa.

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
  authEndpoint: "/bird/auth",
});

const orders = bird.subscribe("private-orders-4821");
orders.bind("order-updated", (data) => {
  console.log(data);
});

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1",
    authEndpoint: URL(string: "https://your-backend.example.com/bird/auth")
))

let orders = bird.subscribe("private-orders-4821")
orders.bind("order-updated") { data in
    print(data ?? "")
}

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
        authEndpoint = "https://your-backend.example.com/bird/auth",
    )
)

val orders = bird.subscribe("private-orders-4821")
orders.bind("order-updated") { data ->
    println(data)
}

Swift e Kotlin exigem uma URL de autorização absoluta, enquanto um cliente no navegador pode usar um caminho de mesma origem. Adicione o token de sessão do seu API por meio de authHeaders. O cliente inclui esses cabeçalhos em cada solicitação de autorização, inclusive nas solicitações após uma reconexão.

O cliente envia via POST o ID de conexão e o nome do canal para authEndpoint. A assinatura só é concluída depois que o endpoint aprova o chamador e retorna uma assinatura válida. Autorizando canais define a solicitação, a resposta e a string a ser assinada.

Nomeando canais por usuário ou por tenant

Coloque o escopo do recurso no nome do canal e verifique-o no seu endpoint. Um cliente pode solicitar qualquer nome de canal, então seu backend precisa impedir assinaturas entre clientes diferentes:

if (channel_name !== `private-orders-${user.accountId}`) {
  return res.sendStatus(403);
}

if channel_name != f"private-orders-{user.account_id}":
    return Response(status=403)

if channelName != "private-orders-"+user.AccountID {
	http.Error(w, "forbidden", http.StatusForbidden)
	return
}

if ($channelName !== "private-orders-{$user->accountId}") {
    http_response_code(403);

    return;
}

Essa comparação é a decisão de autorização. Nunca confie em nomes de canal difíceis de adivinhar para controle de acesso.

O que canais privados suportam

Eventos de cliente. Quando o app tem eventos de cliente habilitados, um cliente inscrito pode enviar eventos client- para os outros clientes no canal sem uma ida e volta pelo seu servidor. O edge rejeita esses eventos em canais públicos.
Contagem de conexões. Com as configurações de contagem de conexões e eventos de contagem de conexões do app habilitadas, o cliente recebe bird:connection_count para o canal.
Publicação pelo servidor. A publicação a partir do seu servidor funciona exatamente como em um canal público: nomeie o canal no array channels. Nenhuma autorização se aplica ao seu servidor, que já possui o segredo do app.

Canais privados não possuem identidade de membro nem eventos de membro. Se você precisa saber quem está presente, use um canal de presença.

Quando uma assinatura é recusada

Uma assinatura recusada chega como bird:subscription_error. Causas comuns incluem uma resposta diferente de 2xx do seu endpoint ou uma assinatura que não corresponde à solicitação. Consulte Autorizando canais para solução de problemas.

Próximos passos

Autorizando canais é o contrato que o seu backend implementa.
Canais de presença adicionam identidade de membro sobre a mesma autorização.
Excluindo destinatários de eventos impede que um cliente receba o evento que ele causou.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Explore a funcionalidadeRealtime Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first realtime event

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