Skip to main content

Guide d’intégration du SDK Web HappyOyster

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.

Ce document s’adresse aux développeurs frontend et full-stack. Il explique comment intégrer le SDK de manière fiable en production. Pour chaque API, consultez la référence de l’API.

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 :
import { HappyOysterEngine, isSdkError } from "@happy-oyster/js-sdk";

const engine = new HappyOysterEngine({
  APIHost: "open-platform.example.com",
  model: "happyoyster-1.0-adventure", // Required; Adventure model shown as an example
  logLevel: "warn",
});

engine.updateToken(token);

const videoElement = document.querySelector("video") as HTMLVideoElement;
const travel = engine.createTravel({
  ticket,
  videoElement,
  maxExperienceTimeSec: 90, // Optional, Adventure only: 60 / 90 / 120
});

const offStatus = travel.on("statusChanged", (status) => {
  // Use status to drive loading states, disabled buttons, and player UI.
});

const offError = travel.onError((error) => {
  // Usually log, show a toast, and refresh the token if it has expired.
  if (isSdkError(error)) console.error(error.code, error.message);
});

try {
  await travel.start();
  // Enable controls or Directing input with travel.can(action) after the session is running.
} finally {
  offStatus();
  offError();
  await travel.end();
}
Cet extrait couvre uniquement le SDK. La création du monde, l’attente de sa disponibilité, la demande du 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, <video>, orchestration des sessions et appels au SDK

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.

happy-oyster-overview.png

1.2 Déroulement de l’expérience

Étape

Acteur

Action

Description

① Créer un monde

Backend de l’application → HappyOyster OpenAPI

POST /openapi/v1/worlds

Renvoie encryptedWorldId, status et firstFrame

② Attendre que le monde soit prêt

Backend de l’application → HappyOyster OpenAPI

GET /openapi/v1/worlds/build-status

Interrogez périodiquement jusqu’à status === ready (ignorez cette étape si le monde est déjà prêt lors de sa création)

③ Obtenir un identifiant Travel

Backend de l’application → HappyOyster OpenAPI

POST /openapi/v1/worlds/get-travel-credential

Renvoie un ticket à usage unique pour enter-travel

④ Demander un jeton de clé API temporaire

Backend de l’application → HappyOyster OpenAPI

POST /api/v1/tokens?expire_in_seconds=1800

Renvoie un token de clé API temporaire. Ne définissez pas une durée de validité trop courte, car le jeton pourrait expirer avant la fin de l’expérience et nécessiter des mises à jour fréquentes.

⑤ 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 token et ticket, il lance le flux du SDK

⑥ Démarrer l’expérience

Frontend de l’application → SDK HappyOyster

Consultez le « Sous-flux de démarrage du SDK » ci-dessous

new HappyOysterEngine/updateToken → createTravel → start()

1.3 Sous-flux d’interaction du SDK (détail de l’étape ⑥)

1.3.1 Démarrer un Travel

travel-start-flow.png
Exigences essentielles de l’ordre des appels

Étape

API

Description

1

new HappyOysterEngine()

Réutilisez un Engine pour un même APIHost + model

2

updateToken()

Terminez avant start()

3

createTravel()

videoElement est obligatoire

4

travel.on(...)

Enregistrez les écouteurs avant start()

5

await travel.start()

Passe à running après un démarrage réussi

1.3.2 Interagir en mode Adventure

adventure-command-flow.png

1.3.3 Interagir en mode Directing / Acting

adventure-control-flow.png
Le tableau suivant résume les différences entre Adventure, Directing et Acting :

Mode

API principales

Utilisation courante

Points d’attention

Adventure (1)

sendCommand()

Contrôle en temps réel au clavier, au joystick et par boutons

Envoyez uniquement après le passage à running ; maxExperienceTimeSec s’applique uniquement à ce mode

Directing (2)

sendInstruct(), pause(), resume(), rewind()

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 travel.can(action)

Acting (3)

sendInstruct(), pause(), resume()

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 ; rewind() n’est pas disponible et scriptlist ne peut pas utiliser sendInstruct()

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 token de 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’APIHost du SDK doit contenir uniquement le nom d’hôte, par exemple open-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

HappyOysterEngine

Configure APIHost et model, gère le jeton de clé API temporaire Model Studio (updateToken) et crée les sessions Travel

Travel

Représente une session : start établit la connexion RTC ; sendCommand, sendInstruct et les méthodes de cycle de vie contrôlent la session

États de la session (statusChanged) :
idle ──start()──► prepare ──video playable──► running ⇄ paused ──end()──► idle
Trois contraintes (détaillées plus loin) :
  • Chaque Engine ne peut avoir qu’un seul Travel actif à la fois.
  • videoElement doit ê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 APIHost avec le nom d’hôte seul d’Open Platform, sans https://, schéma ni chemin, par exemple open-platform.example.com.
  • Réutilisez un HappyOysterEngine pour un même APIHost + model. Avant de changer d’hôte ou de modèle, terminez le Travel actif et utilisez un Engine configuré pour la nouvelle cible.
Recommandé
  • 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.
Le tableau suivant résume les champs de configuration courants :

Champ

Obligatoire

Conseils

APIHost

Oui

Indiquez uniquement le nom d’hôte, par exemple open-platform.example.com ; n’incluez pas https:// ni de chemin

model

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 mode ni du ticket

token

Non

Vous pouvez le transmettre au constructeur ou le définir ensuite avec updateToken(token) ; utilisez également updateToken pour renouveler les jetons expirés

logLevel

Non

Utilisez debug en développement et warn ou none en production

streamReadyTimeout

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

À éviter
  • 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 renseigner APIHost.

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

sdk.updateToken(token)

Authentifie les requêtes du SDK vers Open Platform

Ticket Travel

Identifiant Travel demandé par le backend de l’application

createTravel({ ticket })

Identifiant à usage unique pour une session Travel

Obligatoire
  • 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.
Recommandé
  • 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 appelez updateToken.
À éviter
  • 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 }) ; ticket est l’identifiant Travel à usage unique, et videoElement est fourni à ce stade.
  • Enregistrez statusChanged et onError avant await travel.start() pour observer toutes les erreurs et tous les changements d’état.
Recommandé
  • Affichez une interface de connexion pendant prepare pour éviter les clics répétés. Utilisez travelInfoReady pour lire les métadonnées de session en amont et firstFrameGenerated comme image d’attente lorsque la première image est disponible.
À éviter
  • 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 : prepare indique l’attente de la vidéo, tandis que running indique que l’interaction est disponible.
  • Respectez les cas d’utilisation et les conditions préalables de pause, resume et rewind (qui dépendent des capacités de la session ; rewind exige aussi que la session soit paused et 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.
Recommandé
  • 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.
À éviter
  • Appeler createTravel une 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 playsInline sur <video> (obligatoire sur iOS).
  • Tenez compte de l’effet des politiques de lecture automatique du navigateur sur autoPlay et muted.
Recommandé
  • Pendant prepare, affichez la première image en superposition ; masquez-la lorsque la session passe à running.
  • Configurez streamReadyTimeout selon 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.
À éviter
  • Transmettre une référence à l’élément vidéo avant son ajout au DOM.
  • Laisser l’interface interactive alors que la session est paused ou 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(...) et travel.onError(...).
Recommandé
  • Centralisez l’enregistrement et le nettoyage des écouteurs. Supprimez les anciens écouteurs avant de changer de session Travel.

Événement

Rôle

statusChanged

Affiche l’état, détecte la disponibilité de la vidéo (running) et active ou désactive les boutons

travelInfoReady

Lit encryptedTravelId, le mode, la première image, la durée de l’expérience et le rapport d’aspect Acting avant la connexion RTC ; travel.getInfo() renvoie les mêmes données

firstFrameGenerated

Lorsqu’une première image non vide existe, suit travelInfoReady ; utilisez-la comme image d’attente pendant prepare

error (via onError)

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.
À éviter
  • Intercepter uniquement les erreurs de start() sans écouter onError.
  • 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 :
await travel.sendCommand({ interaction: "Jump" });
Actions continues Continuez à appeler 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 :
// Keep calling while the control is pressed
void travel.sendCommand({ translation: "Front" });

// Stop moving on release
void travel.sendCommand({ translation: "None" });
À éviter
  • Envoyer de nombreuses commandes pendant prepare.
  • Utiliser sendCommand pour 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 pas scriptlist ; appelez await travel.sendInstruct({ content }).
Recommandé
  • Vérifiez que content n’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

APIHost a été fourni sous forme d’URL complète, par exemple avec https:// ou un chemin

Indiquez uniquement le nom d’hôte, par exemple open-platform.example.com

travel.start() échoue car le ticket est invalide ou déjà utilisé

ticket est à usage unique ; il peut avoir expiré, avoir été réutilisé ou avoir été émis avant que le monde soit prêt

Demandez un nouveau ticket au backend ; assurez-vous que le monde est prêt avant d’entrer

onError signale une erreur d’authentification après le démarrage de la session

Le token de clé API temporaire Model Studio a expiré

Demandez un nouveau jeton au backend, puis appelez engine.updateToken(newToken)

Le lecteur reste en chargement ou start() dépasse le délai

Le flux distant n’est pas prêt, le réseau est lent ou streamReadyTimeout est trop court

Proposez une nouvelle tentative ; augmentez streamReadyTimeout si nécessaire ; consultez les journaux du backend et de RTC

Un second appel à createTravel() échoue car un Travel actif existe déjà

Le Travel précédent n’a pas été terminé

Appelez await travel.end() et nettoyez les écouteurs lorsque vous quittez, réessayez ou changez de session

Les commandes ou instructions n’ont aucun effet

La session n’est pas running ou l’API utilisée ne correspond pas au mode Adventure, Directing ou Acting actuel

Pilotez la disponibilité des boutons à partir de statusChanged ; appelez travel.can(action) avant les actions dépendantes du mode

Lors du débogage, consignez ensemble trois informations : l’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.