Zoom Video SDK UI Toolkit

Référence de base pour la boîte à outils UI du SDK Vidéo Zoom prédéfinie sur le web. Préférez choose-zoom-approach en premier si l'utilisateur pourrait encore avoir besoin du Meeting SDK à la place.

Documentation officielle : https://developers.zoom.us/docs/video-sdk/web/ui-toolkit/ Référence API : https://marketplacefront.zoom.us/sdk/uitoolkit/web/ Paquet NPM : https://www.npmjs.com/package/@zoom/videosdk-zoom-ui-toolkit Démo en direct : https://sdk.zoom.com/videosdk-uitoolkit

Liens rapides

Nouveau à UI Toolkit ? Suivez ce chemin :

1. Quick Start - Soyez opérationnel en 5 minutes (voir ci-dessous)
2. JWT Authentication - Génération de jetons côté serveur (obligatoire)
3. Composite vs Components - Choisissez votre approche
4. Framework Integration - Modèles React, Vue, Angular, Next.js
5. Integrated Index - Voir la section ci-dessous dans ce fichier

Vous rencontrez des problèmes ?

• Session ne se joint pas → Vérifiez JWT Authentication (problème le plus courant)
• Erreur de dépendance peer React 18 → Voir section Installation
• CSS ne se charge pas → Voir Troubleshooting
• Composants ne s'affichent pas → Vérifiez Component Lifecycle
• Commencez par les vérifications préalables → 5-Minute Runbook

Vue d'ensemble

La boîte à outils UI du SDK Vidéo Zoom est une bibliothèque UI vidéo prédéfinie qui rend des expériences complètes de vidéoconférence avec un code minimal. Contrairement au SDK Vidéo brut, la boîte à outils UI fournit :

• ✅ UI prête à l'emploi - Interface vidéo professionnelle dès le départ
• ✅ Zéro code UI - Pas besoin de construire des mises en page vidéo, des contrôles ou une gestion des participants
• ✅ Indépendant du framework - Fonctionne avec React, Vue, Angular, Next.js, vanilla JS
• ✅ Hautement personnalisable - Choisissez les fonctionnalités à activer, personnalisez les thèmes
• ✅ Fonctionnalités intégrées - Chat, partage d'écran, paramètres, arrière-plans virtuels inclus

Quand utiliser UI Toolkit :

• Vous voulez une solution vidéo complète rapidement
• Vous avez besoin de la cohérence de l'interface utilisateur de Zoom
• Vous ne voulez pas construire une interface vidéo personnalisée
• Vous avez besoin de fonctionnalités standard (chat, partage, participants)

Quand utiliser le SDK Vidéo brut à la place :

• Vous avez besoin d'un contrôle UI entièrement personnalisé
• Vous construisez une expérience vidéo non standard
• Vous avez besoin d'accès aux données vidéo/audio brutes
• Vous voulez construire votre propre pipeline de rendu

Installation

npm install @zoom/videosdk-zoom-ui-toolkit jsrsasign
npm install -D @types/jsrsasign

Remarque : Le support de React dépend de la version de la boîte à outils UI. Vérifiez les dépendances peer du paquet pour votre version installée (React 18 est généralement requis).

Quick Start

Utilisation basique (Vanilla JS)

import uitoolkit from "@zoom/videosdk-zoom-ui-toolkit";
import "@zoom/videosdk-ui-toolkit/dist/videosdk-zoom-ui-toolkit.css";

const container = document.getElementById("sessionContainer");

const config = {
  videoSDKJWT: "your_jwt_token",
  sessionName: "my-session",
  userName: "John Doe",
  sessionPasscode: "",
  features: ["video", "audio", "share", "chat", "users", "settings"],
};

uitoolkit.joinSession(container, config);

uitoolkit.onSessionJoined(() => {
  console.log("Session joined");
});

uitoolkit.onSessionClosed(() => {
  console.log("Session closed");
});

Intégration Next.js / React

'use client';

import { useEffect, useRef } from 'react';

export default function VideoSession({ jwt, sessionName, userName }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const uitoolkitRef = useRef<any>(null);

  useEffect(() => {
    let isMounted = true;

    const init = async () => {
      const uitoolkitModule = await import('@zoom/videosdk-zoom-ui-toolkit');
      const uitoolkit = uitoolkitModule.default;
      uitoolkitRef.current = uitoolkit;

      // If TypeScript complains about CSS imports, configure your app to allow them
      // (for example via a global `declare module \"*.css\";`), or import the CSS from
      // a global entrypoint (Next.js layout/_app) instead of inlining here.
      await import('@zoom/videosdk-ui-toolkit/dist/videosdk-zoom-ui-toolkit.css');

      if (!isMounted || !containerRef.current) return;

      const config: any = {
        videoSDKJWT: jwt,
        sessionName: sessionName,
        userName: userName,
        sessionPasscode: '',
        features: ['video', 'audio', 'share', 'chat', 'users', 'settings'],
      };

      uitoolkit.joinSession(containerRef.current, config);
      uitoolkit.onSessionJoined(() => console.log('Joined'));
      uitoolkit.onSessionClosed(() => console.log('Closed'));
    };

    init();

    return () => {
      isMounted = false;
      if (uitoolkitRef.current && containerRef.current) {
        try {
          uitoolkitRef.current.closeSession(containerRef.current);
        } catch (e) {}
      }
    };
  }, [jwt, sessionName, userName]);

  return <div ref={containerRef} style={{ width: '100%', height: '100vh' }} />;
}

Fonctionnalités disponibles

Troubleshooting

• troubleshooting/common-issues.md - CSS, SSR, JWT/session join, limites de personnalisation

Génération de JWT Token (côté serveur)

Obligatoire : Générez les JWT tokens sur votre serveur, ne posez jamais le secret SDK côté client.

Route API Node.js / Next.js

import { NextRequest, NextResponse } from 'next/server';
import { KJUR } from 'jsrsasign';

const ZOOM_VIDEO_SDK_KEY = process.env.ZOOM_VIDEO_SDK_KEY;
const ZOOM_VIDEO_SDK_SECRET = process.env.ZOOM_VIDEO_SDK_SECRET;

export async function POST(request: NextRequest) {
  const { sessionName, role, userName } = await request.json();

  if (!sessionName || role === undefined) {
    return NextResponse.json({ error: 'Missing params' }, { status: 400 });
  }

  const iat = Math.floor(Date.now() / 1000);
  const exp = iat + 60 * 60 * 2; // 2 hours

  const oHeader = { alg: 'HS256', typ: 'JWT' };
  const oPayload = {
    app_key: ZOOM_VIDEO_SDK_KEY,
    role_type: role, // 0 = participant, 1 = host
    tpc: sessionName,
    version: 1,
    iat,
    exp,
    user_identity: userName || 'User',
  };

  const signature = KJUR.jws.JWS.sign(
    'HS256',
    JSON.stringify(oHeader),
    JSON.stringify(oPayload),
    ZOOM_VIDEO_SDK_SECRET
  );

  return NextResponse.json({ signature });
}

Champs de charge utile JWT

Référence API

Méthodes principales

uitoolkit.joinSession(container, config);
uitoolkit.closeSession(container);

Écouteurs d'événements

uitoolkit.onSessionJoined(callback);
uitoolkit.onSessionClosed(callback);
uitoolkit.offSessionJoined(callback);
uitoolkit.offSessionClosed(callback);

Méthodes de composant

uitoolkit.showChatComponent(container);
uitoolkit.hideChatComponent(container);
uitoolkit.showUsersComponent(container);
uitoolkit.hideUsersComponent(container);
uitoolkit.showControlsComponent(container);
uitoolkit.hideControlsComponent(container);
uitoolkit.showSettingsComponent(container);
uitoolkit.hideSettingsComponent(container);
uitoolkit.hideAllComponents();

Utilisation CDN (aucune étape de construction)

<link rel="stylesheet" href="https://source.zoom.us/uitoolkit/2.3.5-1/videosdk-zoom-ui-toolkit.css" />
<script src="https://source.zoom.us/uitoolkit/2.3.5-1/videosdk-zoom-ui-toolkit.min.umd.js"></script>

<div id="sessionContainer"></div>

<script>
  const uitoolkit = window.UIToolkit;

  uitoolkit.joinSession(document.getElementById('sessionContainer'), {
    videoSDKJWT: 'your_jwt',
    sessionName: 'my-session',
    userName: 'User',
    features: ['video', 'audio', 'chat']
  });
</script>

Next.js avec basePath

Lors du déploiement de Next.js sous un sous-chemin :

// next.config.ts
const nextConfig = {
  basePath: "/your-app-path",
  assetPrefix: "/your-app-path",
};

Récupérez les routes API avec le chemin complet :

fetch('/your-app-path/api/token', { ... })

Prérequis

1. Identifiants Zoom Video SDK de Zoom Marketplace
2. React version compatible avec votre paquet UI Toolkit installé (vérifiez les dépendances peer ; React 18 est courant)
3. Génération JWT côté serveur (ne posez jamais le secret SDK)
4. Navigateur moderne avec support WebRTC

Support des navigateurs

Problèmes courants

Ressources

• GitHub : https://github.com/zoom/videosdk-zoom-ui-toolkit-web
• Documentation UI Toolkit : https://developers.zoom.us/docs/video-sdk/web/ui-toolkit/
• Exemple de endpoint Auth : https://github.com/zoom/videosdk-auth-endpoint-sample
• Marketplace : https://marketplace.zoom.us/

Index intégré

Cette section a été migrée depuis SKILL.md.

Navigation complète pour toute la documentation UI Toolkit.

📚 Commencez ici

Nouveau à UI Toolkit ? Suivez ce chemin d'apprentissage :

1. SKILL.md - Vue d'ensemble principale et quick start
2. 5-Minute Runbook - Vérifications préalables avant le débogage approfondi
3. Quick Start Guide - Code fonctionnel en 5 minutes (voir skill.md)
4. JWT Authentication - Génération de jetons côté serveur (voir skill.md)
5. Choose Your Mode - Composite vs Components (voir skill.md)

🎯 Concepts fondamentaux

Comprendre comment fonctionne UI Toolkit :

• Composite vs Components - Deux façons d'utiliser UI Toolkit (voir skill.md)
• UI Toolkit Architecture - Comment il enveloppe Video SDK en interne
• Feature Configuration - Compréhension de la structure featuresOptions
• Session Lifecycle - Flux Join → Active → Leave/Close → Destroy

📖 Guides complets

Démarrage

• Installation - Installation NPM et configuration React 18 (voir skill.md)
• Quick Start - Composite - Interface utilisateur complète en un conteneur (voir skill.md)
• Quick Start - Components - Éléments UI individuels (voir skill.md)
• JWT Authentication - Génération de jetons côté serveur (voir skill.md)

Intégration du framework

• React Integration - Patterns Hooks et useEffect (voir skill.md)
• Vue.js Integration - Composition API et Options API (voir skill.md)
• Angular Integration - Cycle de vie des composants (voir skill.md)
• Next.js Integration - App Router, Server Components (voir skill.md)
• Vanilla JavaScript - Utilisation sans framework (voir skill.md)

Sujets avancés

• Component Lifecycle - Patterns de montage, démontage, nettoyage
• Event Listeners - Réagir aux événements de session
• Session Management - Contrôle programmatique
• Quality Statistics - Surveiller la qualité de la connexion
• Custom Themes - Personnalisation de thème
• Virtual Backgrounds - Images d'arrière-plan personnalisées

📚 Référence API

Documentation API complète :

• Core Methods (voir skill.md)

  • joinSession() - Démarrer une session vidéo
  • closeSession() - Terminer la session et supprimer l'interface utilisateur
  • destroy() - Nettoyer l'instance UI Toolkit
  • leaveSession() - Quitter sans détruire l'interface utilisateur

• Component Methods (voir skill.md)

  • showControlsComponent() - Afficher la barre de contrôle
  • showChatComponent() - Afficher le panneau de chat
  • showUsersComponent() - Afficher la liste des participants
  • showSettingsComponent() - Afficher le panneau des paramètres
  • hideAllComponents() - Masquer tous les composants

• Event Listeners (voir skill.md)

  • onSessionJoined() - Session rejointe avec succès
  • onSessionClosed() - Session terminée
  • onSessionDestroyed() - UI Toolkit détruit
  • onViewTypeChange() - Mode de vue modifié
  • on() - S'abonner aux événements Video SDK
  • off() - Se désabonner des événements

• Information Methods (voir skill.md)

  • getSessionInfo() - Obtenir les détails de la session
  • getCurrentUserInfo() - Obtenir l'utilisateur actuel
  • getAllUser() - Obtenir tous les participants
  • getClient() - Obtenir le client Video SDK sous-jacent
  • version() - Obtenir les informations de version

• Control Methods (voir skill.md)

  • changeViewType() - Changer le mode de vue
  • mirrorVideo() - Inverser la vidéo personnelle
  • isSupportCustomLayout() - Vérifier le support du dispositif

• Statistics Methods (voir skill.md)

  • subscribeAudioStatisticData() - Statistiques de qualité audio
  • subscribeVideoStatisticData() - Statistiques de qualité vidéo
  • subscribeShareStatisticData() - Statistiques de qualité de partage

🔧 Configuration

• Feature Configuration (voir skill.md)

  • Structure featuresOptions
  • Options audio/vidéo
  • Chat, Users, Settings
  • Arrière-plan virtuel
  • Recording, Captions (fonctionnalités payantes)
  • Personnalisation de thème
  • Modes de vue

• Session Configuration (voir skill.md)

  • Obligatoire : videoSDKJWT, sessionName, userName
  • Optionnel : sessionPasscode, sessionIdleTimeoutMins
  • Mode débogage
  • Endpoint web
  • Paramètres de langue

⚠️ Troubleshooting

Problèmes courants

• Erreur de dépendance peer React 18
• JWT token invalide
• CSS ne se charge pas
• Composants ne s'affichent pas
• Échecs de jonction de session

Voir : troubleshooting/common-issues.md

Problèmes spécifiques au framework

• React : SSR, hydration, nettoyage
• Vue : Réactivité, cycle de vie
• Angular : Imports de module, AOT
• Next.js : App Router, basePath

Problèmes de session

• Échecs d'authentification
• Problèmes de connexion
• Vidéo/audio ne fonctionnant pas
• Problèmes de partage d'écran

📦 Exemples d'applications

Dépôts officiels :

🌐 Ressources externes

• Documentation officielle : https://developers.zoom.us/docs/video-sdk/web/ui-toolkit/
• Référence API : https://marketplacefront.zoom.us/sdk/uitoolkit/web/
• Paquet NPM : https://www.npmjs.com/package/@zoom/videosdk-zoom-ui-toolkit
• Marketplace : https://marketplace.zoom.us/
• Forum développeur : https://devforum.zoom.us/
• Démo en direct : https://sdk.zoom.com/videosdk-uitoolkit
• Changelog : https://developers.zoom.us/changelog/ui-toolkit/web/

🎓 Chemin d'apprentissage

Débutant

1. Lire la vue d'ensemble SKILL.md
2. Suivre Quick Start - Composite
3. Générer JWT sur le serveur
4. Rejoindre votre première session
5. Explorer les fonctionnalités disponibles

Intermédiaire

1. Essayer Component Mode
2. Ajouter des écouteurs d'événements
3. Personnaliser le thème
4. Ajouter des arrière-plans virtuels
5. Intégrer avec votre framework

Avancé

1. Accéder au Video SDK sous-jacent
2. S'abonner aux statistiques de qualité
3. Gérer tous les cas limites
4. Implémenter des mises en page personnalisées
5. Construire une application prête pour la production

📋 Carte de référence rapide

Exemple de travail minimal

import uitoolkit from "@zoom/videosdk-zoom-ui-toolkit";
import "@zoom/videosdk-ui-toolkit/dist/videosdk-zoom-ui-toolkit.css";

const config = {
  videoSDKJWT: "YOUR_JWT",
  sessionName: "test-session",
  userName: "User",
  featuresOptions: {
    video: { enable: true },
    audio: { enable: true }
  }
};

uitoolkit.joinSession(document.getElementById("container"), config);
uitoolkit.onSessionJoined(() => console.log("Joined"));
uitoolkit.onSessionClosed(() => uitoolkit.destroy());

Règles à retenir

1. ✅ Toujours générer JWT côté serveur
2. ✅ Toujours appeler destroy() au nettoyage
3. ✅ Toujours utiliser React 18 (pas 17/19)
4. ✅ Toujours importer le fichier CSS
5. ❌ Jamais exposer le secret SDK côté client
6. ❌ Jamais ignorer le nettoyage onSessionClosed
7. ❌ Jamais appeler des composants avant joinSession

📞 Support

• Forum développeur : https://devforum.zoom.us/
• Support développeur : https://developers.zoom.us/support/
• Support Premier : https://explore.zoom.us/en/support-plans/developer/

Navigation : ← Retour à SKILL.md

Variables d'environnement

• Voir references/environment-variables.md pour les clés .env standardisées et où trouver chaque valeur.