Ce document s’adresse aux développeurs frontend et full-stack et explique comment intégrer de manière fiable le SDK Web HappyOyster en production dans ses modes Adventure, Directing et Acting.
0. Exemple d’intégration minimal
Si votre backend a déjà renvoyé un token de clé API temporaire Model Studio et un ticket Travel, le flux du SDK frontend est le suivant :
ticket et celle du token de clé API temporaire Model Studio doivent toutes s’effectuer sur le backend de votre application ou par son intermédiaire.
1. Vue d’ensemble du flux de bout en bout
Une expérience complète fait principalement intervenir les composants suivants.
1.1 Composants
Composant | Responsabilité |
|---|---|
Frontend de l’application | Interface utilisateur, |
Backend de l’application | Stocke la clé API principale, appelle les API de monde d’Open Platform pour le compte du client et émet des identifiants temporaires Model Studio |
HappyOyster OpenAPI | Expose les API nécessaires au modèle de monde HappyOyster. |
HappyOyster SDK | SDK utilisé par le frontend de l’application. Il gère principalement les sessions Travel et l’accès au flux vidéo côté client. |

1.2 Déroulement de l’expérience
Étape | Acteur | Action | Description |
|---|---|---|---|
① Créer un monde | Backend de l’application → HappyOyster OpenAPI |
| Renvoie |
② Attendre que le monde soit prêt | Backend de l’application → HappyOyster OpenAPI |
| Interrogez périodiquement jusqu’à |
③ Obtenir un identifiant Travel | Backend de l’application → HappyOyster OpenAPI |
| Renvoie un |
④ Demander un jeton de clé API temporaire | Backend de l’application → HappyOyster OpenAPI |
| Renvoie un |
⑤ Transmettre le jeton de clé API temporaire et l’identifiant Travel | Frontend de l’application → backend de l’application → frontend de l’application | Demander une clé API temporaire et un identifiant Travel | Une fois que le frontend a reçu |
⑥ Démarrer l’expérience | Frontend de l’application → SDK HappyOyster | Consultez le « Sous-flux de démarrage du SDK » ci-dessous |
|
1.3 Sous-flux d’interaction du SDK (détail de l’étape ⑥)
1.3.1 Démarrer un Travel

Étape | API | Description |
|---|---|---|
1 |
| Réutilisez un Engine pour un même |
2 |
| Terminez avant |
3 |
|
|
4 |
| Enregistrez les écouteurs avant |
5 |
| Passe à |
1.3.2 Interagir en mode Adventure

1.3.3 Interagir en mode Directing / Acting

Mode | API principales | Utilisation courante | Points d’attention |
|---|---|---|---|
Adventure ( |
| Contrôle en temps réel au clavier, au joystick et par boutons | Envoyez uniquement après le passage à |
Directing ( |
| Mise en scène en langage naturel et contrôle de la lecture | La pause, la reprise et le retour en arrière dépendent des capacités de la session ; vérifiez d’abord |
Acting ( |
| Expériences centrées sur le jeu d’acteur et configuration du rapport d’aspect | La pause et la reprise dépendent des capacités de la session ; |
1.4 Pratiques du backend de l’application (résumé)
Côté backend, respectez strictement les règles suivantes :
- Conservez la clé API principale uniquement sur le backend de l’application. Le navigateur doit recevoir uniquement un
tokende courte durée (démo :POST /server-api/temp-api-key). - Demandez les identifiants Travel via le backend. Vérifiez les autorisations du monde et de l’utilisateur avant d’émettre le
ticket; ne le codez pas en dur et ne le conservez pas durablement dans le cache du frontend. - N’émettez pas d’identifiant avant que le monde soit
ready. Sinon, enter-travel peut échouer ou fournir une expérience incomplète. - Pointez le backend de l’application et le SDK vers le même environnement Open Platform. Le backend peut utiliser une URL OpenAPI complète ; l’
APIHostdu SDK doit contenir uniquement le nom d’hôte, par exempleopen-platform.example.com.
2. Concepts fondamentaux du SDK
Dans le flux décrit au §1, le SDK est uniquement responsable de « entrer dans Travel → lire → contrôler → terminer ». Il existe deux objets principaux :
Objet | Rôle |
|---|---|
| Configure |
| Représente une session : |
statusChanged) :
- Chaque Engine ne peut avoir qu’un seul Travel actif à la fois.
videoElementdoit être fourni àcreateTravel.- Le jeton de clé API temporaire Model Studio et le ticket Travel ont des rôles différents (voir les étapes ④–⑤ du §1.2 et le §3.2).
3. Initialisation et gestion des jetons
3.1 Instanciation de l’Engine
Obligatoire
- Définissez
APIHostavec le nom d’hôte seul d’Open Platform, sanshttps://, schéma ni chemin, par exempleopen-platform.example.com. - Réutilisez un
HappyOysterEnginepour un mêmeAPIHost + model. Avant de changer d’hôte ou de modèle, terminez le Travel actif et utilisez un Engine configuré pour la nouvelle cible.
- Utilisez
logLevel: 'debug'en développement et'warn'ou'none'en production. - Créez l’Engine dans la couche d’orchestration des sessions plutôt que d’en créer un à chaque démarrage.
Champ | Obligatoire | Conseils |
|---|---|---|
| Oui | Indiquez uniquement le nom d’hôte, par exemple |
| Oui | Obligatoire, sans valeur par défaut ; utilisez le même modèle que le backend pour créer le monde et émettre son ticket. Il est fixe pour l’Engine et n’est déduit ni de |
| Non | Vous pouvez le transmettre au constructeur ou le définir ensuite avec |
| Non | Utilisez |
| Non | Augmentez la valeur si le réseau ou la préparation du rendu est lent ; prévoyez une nouvelle tentative après expiration du délai |
- Appeler plusieurs fois
new HappyOysterEngine()pendant le rendu ou dans un chemin fréquemment exécuté. - Transmettre une URL complète, par exemple avec
https://, ou appeler les API backend du SDK sans renseignerAPIHost.
3.2 Modèle à deux identifiants
Correspond aux étapes ③–⑤ du §1.2 :
Identifiant | Source | Méthode de configuration | Rôle |
|---|---|---|---|
Jeton de clé API temporaire Model Studio | Clé de courte durée émise par le backend de l’application |
| Authentifie les requêtes du SDK vers Open Platform |
Ticket Travel | Identifiant Travel demandé par le backend de l’application |
| Identifiant à usage unique pour une session Travel |
- Préparez les deux identifiants avant
travel.start(). - Le SDK ne conserve pas le jeton de manière persistante et ne le renouvelle pas automatiquement.
- Si le jeton expire ou si une erreur de heartbeat est reçue via
onError, demandez un nouveau jeton via le backend de l’application et appelezupdateToken.
- Confondre les deux identifiants.
- Exposer la clé API principale au frontend de l’application.
4. Cycle de vie de Travel
4.1 Créer et démarrer
Obligatoire
- Appelez
createTravel({ ticket, videoElement });ticketest l’identifiant Travel à usage unique, etvideoElementest fourni à ce stade. - Enregistrez
statusChangedetonErroravantawait travel.start()pour observer toutes les erreurs et tous les changements d’état.
- Affichez une interface de connexion pendant
preparepour éviter les clics répétés. UtiliseztravelInfoReadypour lire les métadonnées de session en amont etfirstFrameGeneratedcomme image d’attente lorsque la première image est disponible.
- Créer un Travel avant que l’élément DOM soit prêt.
4.2 Pendant l’exécution
- Pilotez l’interface à partir de
statusChanged:prepareindique l’attente de la vidéo, tandis querunningindique que l’interaction est disponible. - Respectez les cas d’utilisation et les conditions préalables de
pause,resumeetrewind(qui dépendent des capacités de la session ;rewindexige aussi que la session soitpausedet que le flux soit arrêté).
4.3 Terminer et recréer
Obligatoire
- Terminez la session avec
await travel.end(). - Assurez-vous que le Travel précédent est terminé avant d’en créer un autre.
- Appelez
travel.end()lors du nettoyage au déchargement de la page ou au changement de route.
- Après un échec, suivez « terminer → supprimer les écouteurs → réessayer à partir de l’étape ③ ou ⑤ du §1.2 ».
- Demandez un nouvel identifiant Travel lors d’une nouvelle tentative si l’identifiant est à usage unique.
- Appeler
createTravelune seconde fois sans terminer le premier Travel ; cela lève une exception de manière synchrone. - Quitter la page sans nettoyage, ce qui provoque une fuite des ressources RTC.
5. Élément vidéo et politiques du navigateur
Obligatoire
- Définissez
playsInlinesur<video>(obligatoire sur iOS). - Tenez compte de l’effet des politiques de lecture automatique du navigateur sur
autoPlayetmuted.
- Pendant
prepare, affichez la première image en superposition ; masquez-la lorsque la session passe àrunning. - Configurez
streamReadyTimeoutselon les besoins (valeur par défaut : 15 000 ms) et proposez une nouvelle tentative après expiration du délai. - Réservez un rapport d’aspect fixe pour le conteneur du lecteur.
- Transmettre une référence à l’élément vidéo avant son ajout au DOM.
- Laisser l’interface interactive alors que la session est
pausedou que le flux est déconnecté.
6. Abonnement aux événements et gestion des erreurs
6.1 Abonnement aux événements
Obligatoire
- Les événements appartiennent à
Travel, et non àHappyOysterEngine. - Conservez les fonctions de désabonnement renvoyées par
travel.on(...)ettravel.onError(...).
- Centralisez l’enregistrement et le nettoyage des écouteurs. Supprimez les anciens écouteurs avant de changer de session Travel.
Événement | Rôle |
|---|---|
| Affiche l’état, détecte la disponibilité de la vidéo ( |
| Lit |
| Lorsqu’une première image non vide existe, suit |
| Journalisation, notifications toast et déclenchement du renouvellement du jeton |
6.2 Niveaux d’erreur
- Échecs au démarrage :
travel.start()est rejeté (enter-travel / RTC / expiration du délai). - Erreurs d’exécution : signalées via
travel.onError(erreurs RTC, échecs d’authentification du heartbeat, etc.). - Les erreurs du backend de l’application et d’Open Platform aux étapes ①–④ du §1.2 sont traitées par la couche applicative et ne parviennent pas au SDK.
- Intercepter uniquement les erreurs de
start()sans écouteronError. - Enregistrer des écouteurs à plusieurs reprises sans se désabonner.
7. Envoi d’instructions : Command et Instruct
7.1 sendCommand (contrôle en temps réel)
sendCommand() assure le contrôle en temps réel en mode Adventure (1). Il envoie les commandes via le DataChannel RTC et n’est disponible que lorsque la session est running.
Le SDK envoie au maximum une commande toutes les 42 ms environ (soit environ 24 FPS). Si un cycle s’est écoulé depuis l’envoi précédent, il envoie immédiatement la nouvelle commande. Si sendCommand() est appelé plusieurs fois au cours du même cycle, seule la commande complète du dernier appel est envoyée. translation, rotation et interaction sont des dimensions de contrôle indépendantes. Les champs omis sont envoyés avec la valeur None ; le SDK ne fusionne pas les champs entre les appels, ne répète pas périodiquement la commande précédente et n’envoie pas automatiquement None.
Actions ponctuelles
Appelez sendCommand() une fois pour les actions ponctuelles telles que sauter ou attaquer :
sendCommand() tant qu’une commande de déplacement ou de rotation continue de la vue reste appuyée. L’application frontend n’a pas besoin de limiter les appels à un intervalle de 42 ms ; le SDK regroupe les appels fréquents pour produire environ 24 FPS. Au relâchement, envoyez explicitement None pour réinitialiser la commande :
- Envoyer de nombreuses commandes pendant
prepare. - Utiliser
sendCommandpour les instructions Directing en langage naturel.
7.2 sendInstruct (instructions de mise en scène)
Obligatoire
- Utilisez une session Directing (
2) ou une session Acting (3) qui n’est passcriptlist; appelezawait travel.sendInstruct({ content }).
- Vérifiez que
contentn’est pas vide avant l’envoi et empêchez les envois en double. - Informez l’utilisateur du résultat à partir des champs renvoyés, tels que
accepted.
8. Dépannage
Symptôme | Cause courante | Action à entreprendre |
|---|---|---|
L’initialisation du SDK échoue avec une erreur d’argument |
| Indiquez uniquement le nom d’hôte, par exemple |
|
| Demandez un nouveau |
| Le | Demandez un nouveau jeton au backend, puis appelez |
Le lecteur reste en chargement ou | Le flux distant n’est pas prêt, le réseau est lent ou | Proposez une nouvelle tentative ; augmentez |
Un second appel à | Le Travel précédent n’a pas été terminé | Appelez |
Les commandes ou instructions n’ont aucun effet | La session n’est pas | Pilotez la disponibilité des boutons à partir de |
ErrorCode du SDK, le TravelStatus actuel et les journaux des requêtes backend. Cela permet généralement d’identifier si le problème concerne les identifiants, l’état, le réseau ou le rendu.