Skip to main content

Guide d'intégration du SDK Android HappyOyster

En intégrant le SDK Android HappyOyster, votre application peut entrer dans des mondes générés par l'IA en temps réel, offrant une expérience vidéo interactive en temps réel dans trois modes : Adventure (exploration de monde), Directing (mise en scène en temps réel) et Acting (jeu de rôle).

Happy Oyster est un produit d'exploration de mondes par IA. En intégrant le SDK Android Happy Oyster, votre application peut entrer dans des « mondes » générés par l'IA en temps réel, offrant une expérience vidéo interactive en temps réel en mode aventure, directing ou acting. Ce document s'adresse aux développeurs Android du côté intégrateur. Il couvre l'installation, l'authentification, le flux d'intégration complet, la gestion des événements et les bonnes pratiques, expliquant comment intégrer de manière fiable. Pour les API spécifiques (signatures, paramètres, valeurs de retour, codes d'erreur, modèles de données), reportez-vous à la Référence de l'API du SDK Android Happy Oyster.

1. Ce que vous pouvez faire

  • Démarrer une expérience (Travel) : entrez dans un monde prêt avec un identifiant à usage unique ; le SDK établit automatiquement la connexion vidéo en temps réel.
  • Lecture en temps réel : le SDK renvoie une vue vidéo que vous montez dans votre mise en page pour lire les visuels générés en temps réel par l'IA.
  • Interaction en temps réel :
    • mode réalisation (directing) : Envoyez des instructions textuelles pour diriger l'intrigue.
    • acting : envoyez également des instructions textuelles ; la pause et la reprise sont disponibles ; ne faites pas de retour en arrière et n'utilisez pas sendCommand. Utilisez le aspectRatio de la réponse de jonction pour définir l'orientation du lecteur (voir §13 Adaptation du mode).
    • mode aventure (adventure) : Envoyez des commandes de contrôle de direction/point de vue/action pour interagir avec le monde.
  • Contrôle du processus : Pause / reprise (réalisation et interprétation), rembobinage (réalisation uniquement), fin (les trois modes).
  • Rappels de statut et d'erreur : Percevez le statut et les exceptions de l'expérience en temps réel grâce aux écouteurs d'événements.
Le SDK n'est pas responsable de la création et de la gestion des mondes, et n'expose pas directement les détails de communication en temps réel de bas niveau ; ceux-ci sont gérés par votre serveur ou en interne par le SDK. Vous devez uniquement vous concentrer sur « démarrer l'expérience → lire → interagir → terminer ».

2. Installation

Le SDK Happy Oyster (cn.happyoyster:opensdk) est publié sur Maven Central ; son moteur de communication en temps réel sous-jacent (Alibaba Cloud ARTC) est publié sur Alibaba Cloud Maven. Les deux dépôts doivent être déclarés.

Exigences environnementales

Élément

Exigence

minSdk

24 (Android 7.0) et versions ultérieures

compileSdk

36

JDK

Cible de bytecode JDK 11 (chaîne d'outils hôte : JDK 11 ou supérieur recommandé)

Langage

Kotlin (API de coroutine suspend)

ABI

arm64-v8a / armeabi-v7a (le moteur de communication en temps réel contient des bibliothèques natives)

Réseau

Accès à l'Internet public requis

Ajoutez les dépôts dans le settings.gradle.kts à la racine du projet :
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()                                       // Happy Oyster SDK (cn.happyoyster:opensdk)
        maven("https://maven.aliyun.com/repository/public")  // real-time communication engine (Alibaba Cloud ARTC)
    }
}
Trouvez la dernière version publiée sur Maven Central, remplacez <version> ci-dessous par ce numéro de version exact, et ajoutez la dépendance dans le module build.gradle.kts :
dependencies {
    implementation("cn.happyoyster:opensdk:<version>")
}
Épinglez la dépendance à une version exacte. Consultez les notes de version avant la mise à niveau, et recompilez le code hôte après la mise à niveau.
Le SDK est publié sous forme d'AAR léger et n'intègre aucune dépendance tierce ; les dépendances transitives telles que le moteur de communication en temps réel sont récupérées automatiquement depuis les dépôts ci-dessus lors de la résolution, ainsi le dépôt Alibaba Cloud Maven est indispensable — son absence entraînera l'échec de la résolution de com.aliyun.aio:AliVCSDK_ARTC.

Autorisations

La bibliothèque du SDK elle-même ne déclare que INTERNET. Le moteur de communication en temps réel fusionne automatiquement un petit nombre d'autorisations de type réseau/Bluetooth/paramètres audio ; le manifeste de la bibliothèque n'inclut pas les autorisations de microphone ou de caméra. Le flux vidéo est une lecture en abonnement uniquement, et le SDK n'envoie pas d'audio réel au côté distant. L'hôte doit déclarer de lui-même : lorsque votre targetSdk est 33 ou supérieur, vous devez déclarer l'autorisation de notification dans le AndroidManifest.xml de l'hôte (le moteur de communication en temps réel inclut un service de premier plan) :
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
mode aventure (sendCommand) — la déclaration de l'autorisation du microphone est recommandée : les commandes de contrôle en temps réel du mode aventure empruntent une liaison montante portée par un flux audio silencieux qui établit l'« identité de l'éditeur » locale ; le SDK n'enregistre ni ne téléverse votre audio réel. RECORD_AUDIO n'est pas une condition préalable stricte pour le DataChannel — même sans cela, le flux silencieux reste un éditeur et la liaison montante est normalement disponible. Néanmoins, pour la stabilité sur tous les appareils, nous recommandons que, si votre application utilise sendCommand, vous déclariez l'autorisation dans le AndroidManifest.xml de l'hôte et la demandiez au moment de l'exécution avant l'appel.
<uses-permission android:name="android.permission.RECORD_AUDIO" />
À propos du code d'erreur 105004 : 105004 signifie que le canal en temps réel n'est pas prêt ou qu'un envoi a échoué (par exemple, une interruption DataChannel ou une anomalie du canal en temps réel). Ce n'est pas une conséquence nécessaire d'une autorisation manquante — il n'est pas déclenché directement par le non-octroi de RECORD_AUDIO. Le mode directing (sendInstruct) et la lecture vidéo ne sont pas affectés. Si votre application n'utilise pas le mode aventure, cette autorisation n'est pas nécessaire. Pour réduire les autorisations fusionnées, utilisez tools:node="remove".

3. Modèle d'authentification

Le SDK n'obtient ni ne rafraîchit les jetons, ce qui le garde léger. L'authentification comporte deux couches :
  1. Clé API de la passerelle Bailian (百炼) : injectée en tant que jeton Bearer par votre application via updateToken(token). Le SDK ne conserve que la plus récente ; il ne la persiste ni ne la rafraîchit, et après le changement de clé, vous la réinjectez. La passerelle exige que toutes les requêtes du SDK, y compris startTravel, utilisent ce Bearer. Lorsque la clé Bearer expire ou est invalide, le SDK lève SDKError(101002) ; dans ce cas, vous devez réobtenir et réinjecter la clé Bearer (updateToken) plutôt que d'échanger contre un nouveau ticket. Pendant le développement / Démo, vous pouvez utiliser votre clé API Bailian (百炼) principale directement comme Bearer (updateToken) pour faire fonctionner le flux. En production, passez toujours à un jeton à courte durée de vie émis par votre serveur, et n'intégrez jamais une clé API à longue durée de vie dans une application distribuée.
  2. Identifiant d'expérience à usage unique ticket : échangé par votre serveur via la plateforme ouverte et livré au client ; utilisé pour un seul startTravel. Il devient invalide après la fin de l'expérience (normalement ou anormalement) et ne peut pas être réutilisé. Les erreurs d'identifiant au niveau du ticket sont identifiées par des codes serveur à six chiffres (par exemple, 401010 = ticket invalide / expiré, 401011 = ticket déjà utilisé), que le SDK transmet tel quel.
Votre serveur est responsable de la création / gestion du World, de l'échange contre le ticket Travel et de sa livraison au client ; le SDK Android consomme uniquement des jetons et des tickets et ne fournit aucune interface de gestion de World. Lors de l'initialisation, vous devez transmettre l'API Host Bailian (百炼) de votre compte via SDKConfig.apiHost (sous la forme llm-xxxx.ap-southeast-1.maas.aliyuncs.com, copié depuis le champ "API Host" sur la page API Key de la console Bailian (百炼)) et transmettre le SDKConfig.model requis, sans valeur par défaut (happyoyster-1.0-directing / happyoyster-1.0-acting / happyoyster-1.0-adventure, correspondant à l'entrée Open API). Le SDK complète l'URL de la requête sous la forme https://{apiHost}/api/v2/apps/{model}/openapi/v1/{endpoint}, vous n'avez donc pas à l'assembler vous-même. Omettre model lors de la construction de SDKConfig est une erreur de compilation. Si model est vide, initialize lève de manière synchrone SDKError(100002) (raw = "SDKConfig.model must not be blank"), ne crée ni ne remplace d'exécution, et n'effectue aucune requête réseau. L'API Host, le modèle et la clé API injectée doivent correspondre au compte, à la région et à l'autorisation de modèle requis, sinon la passerelle retourne généralement AccessDenied (au moment de l'exécution, cela est levé en tant que SDKError(106003), avec le corps AccessDenied d'origine disponible dans SDKError.raw ; consultez la ligne 106003 du tableau des codes d'erreur de l'API Reference pour une liste de contrôle de dépannage). Pour des raisons de sécurité, nous recommandons fortement que le client injecte un jeton à courte durée de vie émis par votre serveur en tant que Bearer, plutôt que d'intégrer une clé API à longue durée de vie dans l'application ou de la valider dans un dépôt de code.
Avis de conformité régionale : pour respecter les exigences légales et de données applicables, si vos utilisateurs cibles incluent des utilisateurs américains, vous devez configurer un hôte API de la région américaine lors de l'initialisation du SDK pour les services fournis à ces utilisateurs. Les développeurs sont responsables de la configuration correcte et assument la responsabilité correspondante en vertu de la loi applicable en cas de non-respect de cette exigence.

4. Démarrage rapide

import cn.happyoyster.opensdk.*   // All entry-point classes live in this package: HappyOyster, SDKConfig, TravelStatusValue, ModeValue, SDKError, etc.

// Track the current experience status and this Travel's metadata; use them to decide whether interaction can be sent.
@Volatile private var currentStatus: TravelStatusValue? = null
@Volatile private var currentTravel: StartTravelData? = null

// 1) Initialize (recommended in Application.onCreate)
//    apiHost is required: your account's Bailian API Host (copied from the API Key page in the Bailian console)
//    model is required with no default: the complete model name and version; refer to the official Bailian HappyOyster model documentation for available values
HappyOyster.initialize(
    applicationContext,
    SDKConfig(
        apiHost = "llm-xxxx.ap-southeast-1.maas.aliyuncs.com",
        model = "happyoyster-1.0",
    ),
)

// 2) Inject the Bailian gateway API Key (as the Bearer token)
HappyOyster.updateToken(bailianApiKey)

// 3) Listen to SDK events: use onStatusChanged to drive the host state machine and gate interaction capabilities
HappyOyster.addListener(object : HappyOysterListener {
    override fun onStatusChanged(status: TravelStatusValue) {
        currentStatus = status
        when (status) {
            // Interaction is allowed only in running; adventure-mode sendCommand is valid only in running.
            TravelStatusValue.Running -> markInteractionAllowed()
            // Paused is the signal that pauseTravel has actually taken effect (asynchronous, see below); sendInstruct is still allowed here.
            TravelStatusValue.Paused -> markTravelPaused()
            // Terminal states: the SDK has already ended and released resources; clean up the host-side experience state.
            TravelStatusValue.Completed, TravelStatusValue.Failed -> clearActiveTravel()
            // init / pending: not yet ready, interaction unavailable.
            else -> markInteractionBlocked()
        }
    }
    override fun onError(error: SDKError) {
        // Unified error callback; see the error-codes section of the API Reference
    }
})

// 4) Start the experience (the ticket is delivered by your server)
lifecycleScope.launch {
    try {
        // Only one concurrent Travel is allowed per App at a time (alirtc limitation: even with a different ticket
        // you cannot start a second Travel concurrently within the same App). Calling again while an experience is in progress throws
        // SDKError(103004), whose raw carries only a redacted summary of the ticket currently playing, never the full ticket.
        val travel: StartTravelData = HappyOyster.startTravel(ticket)
        currentTravel = travel

        // Inspect the returned Travel metadata first, then decide how to interact:
        //   travel.mode          —— directing / adventure / acting
        //   travel.creationModel —— Simple / ScriptList
        //   travel.aspectRatio   —— Acting only; use to set player orientation
        val canSendInstruct = (travel.mode == ModeValue.Directing || travel.mode == ModeValue.Acting) &&
            travel.creationModel != CreationModelValue.ScriptList
        // Note: calling sendInstruct in ScriptList mode throws SDKError(103002); script content is not managed through this SDK.

        // 5) Mount the video View (the SDK returns the view; you add it to the layout)
        //    Acting: size the container from travel.aspectRatio first, then attachVideo() (see §13 Mode Adaptation) —
        //    the remote view is bound clip-to-fill, so a mismatched container orientation crops the picture.
        val videoView = HappyOyster.attachVideo()
        binding.videoContainer.addView(videoView)

        // 6) In-run interaction — you must wait for running before sending:
        //    - sendCommand (adventure): valid only in running; calling in init/pending/paused returns 103002.
        //    - sendInstruct (directing / Acting): valid in running or paused; calling in init/pending returns 103002.
        if (canSendInstruct && currentStatus == TravelStatusValue.Running) {
            HappyOyster.sendInstruct("突然下起了大雨")
        }
    } catch (e: SDKError) {
        // Handle start failure (e.g., 103004: an experience is already playing)
    }
}

// 7) Pause / Resume (directing and Acting; rewind is directing only)
//    pauseTravel is asynchronous: the method's return only means "accepted"; the actual pause is determined by onStatusChanged(paused).
//    Be sure to wait for the paused callback before allowing resumeTravel.
lifecycleScope.launch {
    if ((currentTravel?.mode == ModeValue.Directing || currentTravel?.mode == ModeValue.Acting) &&
        currentStatus == TravelStatusValue.Running
    ) {
        HappyOyster.pauseTravel()        // accepted; the host marks pausing and waits for the status callback
        // …after receiving onStatusChanged(Paused)…
    }
}
lifecycleScope.launch {
    if (currentStatus == TravelStatusValue.Paused) {
        HappyOyster.resumeTravel()       // call only after paused
    }
}

// 8) End the experience (the SDK automatically disconnects the real-time connection and releases resources)
lifecycleScope.launch { HappyOyster.endTravel() }

5. Abonnement aux événements et gestion des erreurs

Utilisez onStatusChanged pour piloter la machine à états de l'hôte et conditionner les capacités d'interaction ; utilisez onError pour recevoir les erreurs d'exécution de manière uniforme. Pour l'interface d'événements et les codes d'erreur complets, consultez la Référence de l'API du SDK Android Happy Oyster. Obligatoire
  • Enregistrez le listener immédiatement après le retour réussi de HappyOyster.initialize(...) ; addListener / removeListener doivent être appelés après initialize (les appeler avant l'initialisation lève SDKError(100001)).
  • Conditionnez l'exécution à onStatusChanged(Running) : les appels d'interaction ne sont autorisés qu'après running ; l'appel sendCommand en mode aventure n'est valide qu'en état running.
  • Gérez également onError ; ne vous contentez pas d'intercepter startTravel. Les erreurs fatales mettent également fin à l'expérience (consultez la section des codes d'erreur de la référence de l'API).
Recommandé
  • Appelez removeListener à un point approprié du cycle de vie (tel que onDestroy) pour éviter les fuites de mémoire.
À éviter
  • Enregistrer des écouteurs de manière répétée sans appeler removeListener.

6. Envoi d'instructions : sendInstruct et sendCommand

sendInstruct (réalisation / interprétation)

sendInstruct est utilisé dans directing et acting pour envoyer des instructions textuelles qui pilotent l'image ; il peut être appelé dans l'état running ou paused. À l'état paused, le SDK ne reprend pas automatiquement — l'hôte décide s'il doit d'abord appeler resumeTravel puis envoyer l'instruction (pour les détails du contrat tels que la limitation de débit et la validation d'état, voir la API Reference). Le creationModel d'un monde acting est toujours Simple, donc la restriction ScriptList s'applique uniquement à directing.

sendCommand (mode aventure)

sendCommand est utilisé en mode aventure (adventure) pour envoyer des commandes de contrôle de direction/point de vue/action ; il n'est valide que dans running. Le SDK intègre une limitation de débit "le dernier gagne" de 42 ms (24 fps), l'hôte peut donc l'appeler à la fréquence d'images du jeu et le SDK fusionne automatiquement ; aucune limitation de débit manuelle n'est requise. Appelez une fois pour une action ponctuelle. Pour une action maintenue, continuez à appeler à chaque image pendant le maintien et envoyez explicitement une réinitialisation None lors du relâchement (pour le contrat détaillé de limitation de débit et de remontée des échecs, voir la API Reference). Pratique recommandée : dans l'interface utilisateur d'interaction en mode aventure de l'hôte, fournissez trois points d'entrée de commande indépendants (direction du mouvement + direction du point de vue + interaction d'action), maintenez la valeur actuellement maintenue pour chaque groupe, et envoyez un instantané complet à trois champs à chaque appel. Utilisez "None" uniquement pour les dimensions inactives. Lorsque des entrées de différentes dimensions sont maintenues simultanément, préservez et envoyez toutes les valeurs actives au lieu de réinitialiser les autres dimensions à "None".

7. Pause / Reprise / Rembobinage

Modes applicables : pause / reprise s'appliquent à directing et acting, et se comportent de manière identique dans les deux (y compris la barrière de 3 secondes ci-dessous) ; rewind est uniquement pour directing. L'appel de pauseTravel / resumeTravel / rewindTravel en mode aventure est rejeté par le SDK avec 103003. De plus, la version rapportée par le serveur doit être le jeton v2 requis par son mode (storyV2 pour directing, actingV2 pour acting) ; sinon, pause / reprise retournent 103002. La pause est asynchrone : le retour de la méthode pauseTravel signifie seulement qu'elle a été acceptée ; la pause réelle est déterminée par onStatusChanged(Paused). Entre « l'appel de pauseTravel » et « la réception du callback Paused », l'hôte peut marquer son état d'expérience local comme pausing ; ce n'est qu'après avoir reçu Paused que vous devez autoriser l'appel de resumeTravel ou de rewindTravel qui dépend de l'état de pause. Barrière interne au SDK pause→réouverture : une fois Paused reçu, l'hôte peut appeler resumeTravel / rewindTravel conformément au contrat. Si l'appel intervient dans la fenêtre de stabilisation de 3 secondes suivant la confirmation de la pause, la méthode de suspension du SDK attend le temps restant avant d'envoyer la requête qui rouvre la salle en temps réel. L'hôte n'a pas besoin d'un délai supplémentaire pause→reprise, et aucun délai n'est ajouté une fois que 3 secondes se sont écoulées naturellement. Temporisation des appels côté hôte (recommandé) : il est recommandé que l'hôte attende avant d'émettre un autre pauseTravel dans les 3 s suivant le retour réussi de resumeTravel, afin d'éviter les changements trop fréquents. Le SDK lui-même n'impose pas cette temporisation. Rewind : rewindTravel n'est disponible que dans l'état paused ; après le rembobinage, le serveur reprend automatiquement et le SDK se reconnecte automatiquement au RTC, sans aucune intervention de l'hôte. Séquence typique : pause → wait:paused → rewindTravel(sec). Les secondes de rembobinage rewindToSec doivent être un multiple de 4 (par exemple, 4, 8, 12) ; les non-multiples sont arrondis à l'inférieur par le serveur (par exemple, 7→4), et les secondes effectives réelles sont déterminées par le resumedAtSec retourné. Rewind est uniquement pour directing : l'appel de rewindTravel en mode acting ou adventure est rejeté par le SDK localement avec 103003, sans émettre de requête HTTP ; l'hôte doit masquer l'entrée de rembobinage plutôt que de simplement griser le bouton. Pour les détails du contrat tels que la sémantique asynchrone et le backoff de 3× tentatives (backoff de resumeTravel de 1 s / 2 s / 3 s), consultez la Référence de l'API du SDK Android Happy Oyster.

8. Journalisation

Tag Logcat du SDK : HappyOysterSDK. Le SDK fournit deux chemins de sortie de journaux indépendants :
  • Logcat intégré (désactivé par défaut) : le SDK écrit dans Logcat uniquement lorsque SDKConfig.logcatEnabled = true (par défaut false, totalement silencieux). SDKConfig.logLevel filtre son niveau minimum ; la valeur par défaut INFO contient déjà les ancres de cycle de vie nécessaires pour reconstruire une session (initialisation, début de Travel / transitions de statut / fin, jonction RTC / première image). Réduisez à WARN pour les erreurs uniquement, ou augmentez à DEBUG / VERBOSE pour un diagnostic plus approfondi. logLevel n'affecte pas logHandler.
  • Callback hôte logHandler (recommandé) : reçoit chaque LogRecord du SDK (le flux complet), totalement indépendant de logLevel / logcatEnabled, et peut transférer vers le propre système de journalisation de l'hôte (Logcat, fichiers, plateformes de crash, etc.). Le callback doit être rapide et non bloquant et ne doit pas rappeler le SDK ; les exceptions qu'il lève sont interceptées silencieusement ; LogRecord.message est expurgé et ne contient aucun jeton Bearer, ticket, ou jeton RTC en texte clair.
HappyOyster.initialize(
    context,
    SDKConfig(
        apiHost = "llm-xxxx.ap-southeast-1.maas.aliyuncs.com",  // required: your account's Bailian API Host
        model = "happyoyster-1.0",                          // required with no default: complete model name and version
        logcatEnabled = true,        // enable built-in Logcat (default false)
        logLevel = LogLevel.DEBUG,   // affects only the built-in Logcat
        logHandler = { record ->     // optional: forward to the host's own Logcat tag
            android.util.Log.d("MyApp/SDK", record.message, record.throwable)
        },
    ),
)
adb logcat -s HappyOysterSDK          # output only when built-in Logcat is enabled
adb logcat -s HappyOysterSDK MyApp    # also view the host App logs (replace MyApp with your tag)
Corrélation de session et de requête : le travelId (c'est-à-dire encryptedTravelId) dans les journaux du SDK est émis en entier et est la clé de session envoyée au serveur — incluez-le lors de l'investigation d'une session ou de l'ouverture d'un ticket pour aligner les journaux client et serveur. Chaque ligne de réponse HTTP porte également le requestId du serveur (le champ reqId=, affiché comme - lorsqu'il est absent) pour identifier une requête unique ; cet identifiant apparaît uniquement dans les journaux et n'est jamais exposé sur aucune valeur de retour publique.

9. Cycle de vie et mémoire

  • Appelez initialize dans Application.onCreate, une seule fois de manière globale.
  • La réinitialisation à l'état inactif (par exemple pour changer de région API ou de model) ferme l'exécution inactive précédente et réinitialise les listeners enregistrés et l'état des portes de fonctionnalités ; réenregistrez les listeners après son retour. La réinitialisation est rejetée avec 103004 pendant qu'un Travel démarre, est actif ou se termine : attendez toujours endTravel() d'abord. Le SDK ne rejette jamais un Travel actif comme effet secondaire de initialize.
  • L'expérience est liée au cycle de vie de l'hôte : appelez endTravel dans le onDestroy de l'Activity/Fragment (ou le onCleared du ViewModel) pour vous assurer que la connexion en temps réel et les ressources sont libérées.
  • Retirez la View renvoyée par attachVideo() de la mise en page à la fin (container.removeAllViews()), et appelez removeListener.
  • Le SDK ne conserve que le contexte de l'application ; de même, ne transmettez pas d'Activity au SDK.

10. Coroutines et threading

  • Les méthodes métier sont suspend ; appelez-les dans lifecycleScope / viewModelScope depuis n'importe quel contexte de coroutine. Le SDK coordonne l'état et le travail RTC sur son dispatcher principal tandis que HTTP reste en dehors du thread principal.
  • Si la coroutine appelante est annulée, le SDK annule la requête HTTP en cours de cet appel, le cas échéant, et propage CancellationException inchangée plutôt que de la convertir en SDKError ; ne l'interceptez pas et ne l'ignorez pas comme un échec opérationnel. L'annulation n'annule pas une requête que le serveur a déjà acceptée.
  • Appelez attachVideo() et sendCommand() sur le thread principal ; un appel hors du thread principal lève de manière synchrone une IllegalStateException.

11. Gestion des jetons

  • La clé API Bearer a une durée de validité limitée ; il est recommandé de s'assurer que le jeton est à jour avant d'entrer dans une expérience. À la réception de onError(101002) (jeton expiré), obtenez à nouveau la clé Bearer et appelez updateToken ; il n'est pas nécessaire d'échanger contre un nouveau ticket.

12. Récupération d'erreur

  • En cas d'erreurs fatales : nettoyez l'état actuel de l'expérience (y compris en supprimant la vue vidéo), invitez l'utilisateur et autorisez le redémarrage.
  • En cas de gigue réseau (106001) et d'anomalies temporaires du service en amont (106003) : un nombre limité de tentatives peut être effectué.
  • Un 100002 synchrone provenant de l'initialisation signifie que model est vide ; fournissez le nom et la version complets du modèle, puis initialisez à nouveau. Si un model non vide a un nom ou une version incorrect, a été retiré, n'est pas encore publié ou n'est pas autorisé, la passerelle renvoie généralement AccessDenied, mappé à 106003 ; utilisez SDKError.raw et vérifiez que le model, l'hôte API, la clé API, le compte et la région correspondent.
(Pour la classification fatale / non fatale, consultez la section des codes d'erreur de la Référence de l'API du SDK Android Happy Oyster.)

13. Adaptation du mode

  • Utilisez le mode renvoyé par startTravel pour décider des capacités d'interaction à exposer : les modes directing et acting utilisent l'instruction textuelle sendInstruct (acting utilise également aspectRatio pour l'orientation du lecteur et masque le retour en arrière) ; le mode aventure utilise la commande de contrôle sendCommand.
  • En mode aventure, vous pouvez utiliser la surcharge startTravel(ticket, maxExperienceTimeSec) pour plafonner la durée maximale de cette expérience (en secondes ; la session se termine automatiquement une fois atteinte). Les valeurs autorisées sont configurées par le serveur (actuellement 60 / 90 / 120, par défaut 60) ; directing et acting ignorent la valeur (le serveur l'ignore et renvoie null). Le passage d'une valeur non prise en charge fait retourner 400000 par le serveur et ce démarrage échoue. Consultez la API Reference pour les détails des paramètres.

interprétation : Définition de l'orientation du joueur à partir de aspectRatio

StartTravelData.aspectRatio est non-null uniquement pour acting : "9:16" (portrait, la valeur par défaut côté serveur lors de la création du monde) ou "16:9" (paysage) ; il est null pour adventure et directing. Le canevas est fixé lors de la création du monde (spécifié par votre serveur via l'Open API), donc pour le client, c'est un résultat en lecture seule. Le SDK préserve les valeurs non reconnues textuellement, l'hôte doit donc traiter toute valeur qu'il ne reconnaît pas comme null et revenir à sa propre orientation par défaut. Timing : décidez de l'orientation du conteneur de lecture après le retour de startTravel() et avant d'appeler attachVideo() et de monter le SurfaceView retourné dans votre mise en page. Le SDK ne commence à lier et rendre le flux distant qu'une fois la vue de l'hôte attachée, donc décider de l'orientation à ce stade précède toujours la première image rendue. La valeur est livrée avec la valeur de retour de startTravel() et il n'est pas garanti qu'elle arrive avant que le SDK ne rejoigne le canal de communication en temps réel — elle doit seulement être appliquée avant attachVideo(). Conséquence : la vue distante est liée avec un mode de rendu clip-to-fill — un conteneur dont l'orientation ne correspond pas à aspectRatio recadre l'image (par exemple, un flux portrait 9:16 placé dans un conteneur 16:9 perd la majeure partie de son haut et de son bas) au lieu de l'adapter avec des bandes noires.
// After startTravel() returns and before attachVideo(): size the container from aspectRatio first
val ratio: Float = when (travel.aspectRatio) {   // width / height
    "9:16" -> 9f / 16f                           // portrait (the Acting server-side default)
    "16:9" -> 16f / 9f                           // landscape
    else -> HOST_DEFAULT_RATIO                   // null or unrecognized: fall back to your own default orientation
}
// Apply `ratio` to the container, for example:
//   - Compose: Modifier.fillMaxWidth().aspectRatio(ratio)
//   - Views: put the container in a ConstraintLayout, full width, height driven by the ratio (height=0dp in XML)
binding.videoContainer.updateLayoutParams<ConstraintLayout.LayoutParams> {
    dimensionRatio = ratio.toString()
}

// Only once the container orientation is settled, mount the video View returned by the SDK
val videoView = HappyOyster.attachVideo()
binding.videoContainer.addView(videoView)
Lorsque le mode acting n'est pas activé pour le compte (ou que la spécification est désactivée), la création et la jonction du monde sont toutes deux rejetées par le serveur : startTravel échoue avec 403007 (rejeté avant la création du Travel), que le SDK transmet tel quel. Ne réessayez pas ce code en pensant que la capacité est pleine ; invitez plutôt à demander l'activation.

14. Exemple complet (extrait de ViewModel + Activity)

class TravelViewModel : ViewModel() {

    private val listener = object : HappyOysterListener {
        override fun onStatusChanged(status: TravelStatusValue) {
            _status.value = status
        }
        override fun onError(error: SDKError) {
            _error.value = error
        }
    }

    init { HappyOyster.addListener(listener) }

    fun start(ticket: String) = viewModelScope.launch {
        try {
            val travel = HappyOyster.startTravel(ticket)
            _travel.value = travel
        } catch (e: SDKError) {
            _error.value = e
        }
    }

    fun send(text: String) = viewModelScope.launch {
        runCatching { HappyOyster.sendInstruct(text) }
    }

    fun stop() = viewModelScope.launch { runCatching { HappyOyster.endTravel() } }

    override fun onCleared() {
        HappyOyster.removeListener(listener)
        viewModelScope.launch { runCatching { HappyOyster.endTravel() } }
    }
}

// Mount the video in the Activity
val videoView = HappyOyster.attachVideo()
binding.videoContainer.addView(videoView)
// On end
binding.videoContainer.removeAllViews()

15. Guide de dépannage DevOps

Lorsqu'un problème survient pendant l'intégration (impossibilité d'entrer dans un Travel, écran noir sans vidéo, coupure du flux en pleine session, anomalies de pause/reprise, ...), l'ouverture des journaux du SDK est le moyen le plus rapide de localiser le problème. Ce chapitre présente un flux de dépannage standard, utile à la fois pour votre propre vérification et pour nous fournir suffisamment d'informations en une seule fois.

15.1 Activation des journaux

Choisissez une sortie de journal selon vos besoins lors du dépannage (voir §8 Logging) : pour une vérification rapide, définissez logcatEnabled = true et lisez-le avec adb logcat, en augmentant logLevel à DEBUG ou VERBOSE lors du diagnostic (la valeur par défaut INFO contient déjà la chronologie complète du cycle de vie ; réduisez à WARN pour les erreurs uniquement) ; pour alimenter votre propre système, utilisez logHandler pour recevoir chaque LogRecord (non affecté par logLevel) et écrivez-le dans votre fichier ou votre plateforme de crash.

15.2 ID de corrélation de session : travelId

Le travelId (c'est-à-dire StartTravelData.encryptedTravelId) dans les journaux du SDK est émis en entier. C'est l'identifiant unique qui traverse une session et la clé de session envoyée au serveur. C'est la clé pour aligner les journaux client avec les enregistrements de session côté serveur — incluez toujours le travelId de la session en échec lors du signalement d'un problème.

15.3 Collecte des journaux

Lors de la reproduction du problème, enregistrez les journaux du SDK dans un fichier :
# Clear history, reproduce the issue, then capture SDK logs to a file
adb logcat -c
adb logcat -s HappyOysterSDK > happyoyster-sdk.log
# To also see your own app logs (replace MyApp with your tag):
adb logcat -s HappyOysterSDK MyApp > happyoyster-sdk.log

15.4 Ce qu'il faut inclure lors du signalement d'un problème

Pour éviter plusieurs allers-retours, veuillez joindre les éléments suivants :

Élément

Remarques

Version du SDK

HappyOyster.VERSION

Session travelId

le encryptedTravelId de la session en échec (voir 15.2)

Heure de survenue

l'heure approximative (à la minute près suffit)

Code d'erreur

le SDKError.code capturé (significations dans le tableau des codes d'erreur de la référence de l'API)

Étapes de reproduction

chemin d'action + résultat attendu + résultat réel

Environnement

modèle d'appareil, version d'Android, réseau (WiFi/cellulaire)

Fichier journal

le journal HappyOysterSDK de 15.3 (DEBUG/VERBOSE recommandé)

15.5 Concernant l'anonymisation et le partage des journaux

Les journaux du SDK sont conçus pour être sûrs à partager : les identifiants (jeton Bearer, ticket Travel, jeton RTC), les identifiants internes RTC et les URL des médias sont caviardés avant d'être écrits, de sorte qu'ils n'apparaissent jamais en texte brut ; travelId est un identifiant de session (et non un identifiant de connexion) et n'est conservé en entier que pour la corrélation. Même ainsi, nous recommandons de transférer les fichiers journaux via un canal de confiance plutôt que de les coller publiquement sur des plateformes non contrôlées.