Sign inGet started

Kanalen autoriseren

Elke client met de app-key kan zich abonneren op publieke kanalen. Twee kanaalnaam-prefixen vereisen dat je backend het abonnement autoriseert. Je configureert kanalen niet apart.
Een kanaal met de naam private-… vereist dat je backend elk abonnement goedkeurt. Een kanaal met de naam presence-… doet hetzelfde en koppelt bovendien een identiteit aan de abonnee, zodat iedereen op het kanaal kan zien wie er nog meer is. Elke andere naam is publiek.
Alleen je backend beschikt over het app-secret. De client vraagt je server om een specifiek abonnement te ondertekenen, en de Realtime-edge verifieert die handtekening voordat hij het accepteert. Je server beslist of de aanvrager zich mag abonneren zonder het secret bloot te stellen aan de client.

Verwijs de client naar je endpoint

Geef de client een authEndpoint op je eigen backend:
import { BirdRealtime } from "@messagebird/realtime";

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

const room = bird.subscribe("presence-room-1");
De client roept dit endpoint aan voor elk private- of presence-abonnement, inclusief abonnementen die na een herverbinding worden hersteld. Autorisatie geldt voor één verbinding, omdat de handtekening het connection-ID bevat.
De browserclient vereist standaard een same-origin-endpoint. Stel allowCrossOriginAuth: true in om een cross-origin authEndpoint te gebruiken. De browserclient stuurt geconfigureerde authHeaders alleen naar same-origin-endpoints.

Wat je endpoint ontvangt en retourneert

De client POST JSON:
Codevoorbeeld
{ "connection_id": "26896.319537", "channel_name": "presence-room-1" }
Antwoord met de handtekening:
Codevoorbeeld
{ "auth": "your-app-key:8f9a…" }
Retourneer voor een presence-kanaal ook de ledenidentiteit als een JSON string, dezelfde string die je hebt ondertekend:
Codevoorbeeld
{
  "auth": "your-app-key:8f9a…",
  "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Ada\"}}"
}
member_id is de identiteit die andere leden zien en de waarde waarop de disconnect-operatie zich richt. member_info is optionele JSON-data die aan elk kanaallid wordt geleverd. Het heeft een limiet van 1 KB, dus neem alleen kleine, niet-gevoelige profielgegevens op.
Autoriseer de aanvrager in dit endpoint met zijn sessiecookie of bearer-token. Retourneer 403 Forbidden wanneer de aanvrager niet mag toetreden tot het kanaal. Wijs voor presence-kanalen de identiteit toe in hetzelfde antwoord.

De string die je ondertekent

Voeg samen met dubbele punten, pas dan HMAC-SHA256 toe met het app-secret en hex-encodeer het resultaat. Zet er de app-key en een dubbele punt voor.
KanaaltypeTe ondertekenen string
private-…<connection_id>:<channel_name>
private-encrypted-…<connection_id>:<channel_name>
presence-…<connection_id>:<channel_name>:<member_data>
Onderteken voor presence-kanalen exact de member_data-string die je retourneert. Opnieuw serialiseren van hetzelfde object kan de sleutelvolgorde of spatiëring wijzigen en de handtekening ongeldig maken.
Een versleuteld kanaal ondertekent als een privékanaal, en het auth-antwoord retourneert daarnaast de ontsleutelingssleutel van het kanaal als shared_secret. De SDK-helper voegt deze automatisch toe; Versleutelde kanalen beschrijft de afleiding en het kanaalgedrag.
Elke server-SDK biedt een authorizeChannel-helper. Deze ondertekent met de geconfigureerde app-credentials en retourneert de response-body zonder een netwerkverzoek te doen. Voor versleutelde kanalen voegt de helper ook shared_secret toe.
app.post("/bird/auth", async (req, res) => {
  const { connection_id, channel_name } = req.body;

  // Your own authorization decision goes here.
  const user = getUserFromSession(req);
  if (!user || !mayJoin(user, channel_name)) return res.sendStatus(403);

  const memberData = channel_name.startsWith("presence-")
    ? JSON.stringify({ member_id: user.id, member_info: { name: user.name } })
    : undefined;

  res.json(
    await bird.realtime.authorizeChannel({
      connectionId: connection_id,
      channelName: channel_name,
      memberData,
    }),
  );
});
Het ondertekeningscontract is hetzelfde in een taal zonder SDK: pas HMAC-SHA256 toe op de string met het app-secret, hex-encodeer het resultaat en zet er de app-key en een dubbele punt voor.

Leden en verbindingen

Een lid is een identiteit, terwijl een verbinding één open WebSocket is. Als iemand je app in drie tabbladen opent, heeft één lid drie verbindingen. member_added wordt geactiveerd wanneer de eerste verbinding zich abonneert, en member_removed wordt geactiveerd wanneer de laatste vertrekt. Andere verbindingen wijzigen het aantal verbindingen van het kanaal zonder ledengebeurtenissen te produceren.

Veelvoorkomende fouten

Een geweigerd abonnement komt binnen als een clientfout. Controleer deze veelvoorkomende oorzaken:
  • Ongeldige handtekening. De string die je hebt ondertekend komt niet overeen. Bijna altijd een opnieuw geserialiseerde member_data, of een handtekening berekend over de kanaalnaam zonder het private-- of presence--prefix.
  • Ongeldige key. De key in auth hoort bij een andere app, of is ingetrokken. Keys roteren betekent zowel de appKey van de client als het secret waarmee je endpoint ondertekent bijwerken.
  • Ontbrekende ledengegevens. Een presence-abonnement kwam binnen zonder member_data. Presence-kanalen kunnen niet anoniem worden betreden.
  • Een 403 van je eigen endpoint. Je autorisatiebeslissing heeft geweigerd, wat het beoogde resultaat is voor een gebruiker die niet mag toetreden.

Volgende stappen

  • Verstuur je eerste realtime-event is de end-to-end-walkthrough waarop deze gids voortbouwt.
  • Versleutelde kanalen bouwen voort op deze handtekening om goedgekeurde abonnees ook een ontsleutelingssleutel te geven.
  • Presence-kanalen behandelen de ledenlijst, ledengebeurtenissen en het uitlezen van presence vanuit je server.
  • Ledenverbindingen beëindigen is de andere handtekening die je backend berekent, en degene waarmee je de verbindingen van een lid kunt sluiten.
  • Webhooks & events behandelt realtime.*-events, waaronder het toetreden en verlaten van leden, op je eigen endpoint.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Probeer de oefening en ontvang een implementatieoverzicht