Identifier vos utilisateurs

Seuls les membres lisent et écrivent dans un chat Komozu. Votre serveur garde la main : il crée chaque membre une fois, et Komozu lui donne un jeton pour ce membre. Le chat affiche le nom et l’avatar du membre, lui ouvre les salons Membres et Privé, et vous permet de le bannir. Sans jeton, le chat invite le visiteur à se connecter sur votre site.

Votre serveur ── members.upsert({ id, name, avatarUrl }) ──▶ Komozu ──▶ { member, token }   (une fois, à l'inscription)
Votre serveur ── écrit le jeton conservé dans la page ──▶ le chat                          (à chaque page)

1. Installer le SDK serveur

npm install @komozu/node

import { Komozu } from '@komozu/node';

const komozu = new Komozu({ secretKey: process.env.KOMOZU_SECRET_KEY });

La clé secrète (kz_sec_…) se trouve dans le tableau de bord → Clés API (affichée une seule fois ; renouvelez-la pour en obtenir une nouvelle). Ne la mettez jamais dans un navigateur ni dans une application mobile : l’API refuse tout appel serveur qui porte un en-tête Origin (403 SECRET_KEY_IN_BROWSER).

2. Créer le membre et conserver le jeton

Quand un utilisateur s’inscrit :

const { token } = await komozu.members.upsert({ id: user.id, name: user.name, avatarUrl: user.avatarUrl ?? null });
// Enregistrez-le avec l'utilisateur dans votre base de données, à côté de ses autres champs
await saveUser({ ...user, komozuToken: token });

• id est l’identifiant de l’utilisateur dans votre base de données (1 à 128 caractères).
• Le nom (1 à 64 caractères) et l’avatar affichés dans le chat viennent toujours d’ici, jamais du jeton. L’avatar est l’URL https:// d’une image.
• Le jeton n’expire pas. Conservez-le une fois et réutilisez-le sur chaque page.
• Quand le nom ou l’avatar change, appelez komozu.members.update(user.id, { name, avatarUrl }) : le jeton reste le même.
• Pour les utilisateurs inscrits avant l’ajout de Komozu : lancez upsert une fois pour chacun d’eux (un petit script) et conservez leurs jetons.

3. Écrire le jeton dans la page

Votre serveur écrit le jeton de l’utilisateur connecté dans le script de l’intégration (data-komozu-token), et le laisse vide pour un visiteur non connecté (le chat l’invite alors à se connecter).

import { createServer } from 'node:http';

createServer(async (req, res) => {
  const user = await getSignedInUser(req); // votre propre session, null pour un visiteur
  res.setHeader('Content-Type', 'text/html; charset=utf-8');
  res.end(`<!doctype html>
<h1>Club news</h1>
<script src="https://embed.komozu.com/komozu-embed.js" data-komozu-integration="int_…"
        data-komozu-token="${user?.komozuToken ?? ''}" defer></script>`);
}).listen(3000);

Le jeton ne passe jamais dans une URL : le script le transmet au chat par postMessage, il ne se retrouve donc ni dans l’historique du navigateur ni dans un en-tête Referer.

Le même jeton fonctionne avec les SDK pour développeurs :

• React : <KomozuChat clientId="kz_live_…" channel="general" token={user?.komozuToken ?? null} />
• JavaScript : new KomozuClient({ apiUrl, clientId, memberToken: user.komozuToken })

Avec le script, un utilisateur qui se connecte ou se déconnecte sans recharger la page : window.Komozu.setUser({ token }), ou window.Komozu.setUser({ token: null }) pour se déconnecter du chat (en React, changez la prop token).

Révoquer un jeton

Un jeton a fuité, ou un utilisateur a perdu l’accès à son compte ? Révoquez ses jetons :

const token = await komozu.members.revokeTokens(user.id);
await saveUser({ ...user, komozuToken: token }); // conservez le nouveau

Tous les jetons émis auparavant cessent immédiatement de fonctionner (401 TOKEN_REVOKED) et les chats ouverts du membre sont déconnectés. Vous pouvez aussi le faire depuis le tableau de bord : Membres → Jeton → Révoquer les jetons.

Depuis le tableau de bord

Vous pouvez aussi créer un membre à la main dans le tableau de bord (Membres → Nouveau membre), par exemple pour ouvrir un salon privé à quelques personnes. Son jeton s’affiche juste après, et à tout moment depuis Membres → Jeton : votre serveur l’écrit toujours dans la page.

Membres → Modifier change le nom et l’avatar d’un membre ; les chats ouverts affichent le changement tout de suite. Si votre serveur synchronise ses utilisateurs avec members.upsert, son prochain appel peut les remplacer.

Règles

• Un jeton est toujours obligatoire pour lire ou écrire : sans jeton, l’API répond 401 MEMBER_TOKEN_REQUIRED et le chat invite à se connecter, sans charger aucun message.
• Un jeton valide pour un membre qui n’a jamais été créé est refusé (401 MEMBER_NOT_FOUND).
• Ordre des vérifications : signature (401 INVALID_MEMBER_TOKEN) → expiration, seulement si le jeton en a une (401 TOKEN_EXPIRED) → membre connu (401 MEMBER_NOT_FOUND) → non révoqué (401 TOKEN_REVOKED) → non banni (403 MEMBER_BANNED) → accès au salon (403 CHANNEL_ACCESS_DENIED).
• Un jeton présent mais refusé n’est jamais ignoré : le chat indique que la session est terminée.
• Renouveler la clé secrète invalide tous les jetons signés avec l’ancienne : créez-en de nouveaux avec upsert.

Salons privés

const team = await komozu.channels.create({ name: 'U15 team', access: 'private' });
await komozu.channels.addMembers(team.slug, ['user_42', 'user_43']);
await komozu.channels.removeMembers(team.slug, ['user_43']); // son chat ouvert est déconnecté immédiatement

Les membres peuvent aussi être ajoutés depuis le tableau de bord (page du salon → Membres). Voir API serveur.