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).
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 leaspectRatiode 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.
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 |
ABI |
|
Réseau | Accès à l'Internet public requis |
settings.gradle.kts à la racine du projet :
<version> ci-dessous par ce numéro de version exact, et ajoutez la dépendance dans le module build.gradle.kts :
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) :
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.
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 :
- 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 comprisstartTravel, utilisent ce Bearer. Lorsque la clé Bearer expire ou est invalide, le SDK lèveSDKError(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. - Identifiant d'expérience à usage unique
ticket: échangé par votre serveur via la plateforme ouverte et livré au client ; utilisé pour un seulstartTravel. 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.
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.
4. Démarrage rapide
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/removeListenerdoivent être appelés aprèsinitialize(les appeler avant l'initialisation lèveSDKError(100001)). - Conditionnez l'exécution à
onStatusChanged(Running): les appels d'interaction ne sont autorisés qu'aprèsrunning; l'appelsendCommanden mode aventure n'est valide qu'en étatrunning. - Gérez également
onError; ne vous contentez pas d'intercepterstartTravel. Les erreurs fatales mettent également fin à l'expérience (consultez la section des codes d'erreur de la référence de l'API).
- Appelez
removeListenerà un point approprié du cycle de vie (tel queonDestroy) pour éviter les fuites de mémoire.
- 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éfautfalse, totalement silencieux).SDKConfig.logLevelfiltre son niveau minimum ; la valeur par défautINFOcontient 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 àWARNpour les erreurs uniquement, ou augmentez àDEBUG/VERBOSEpour un diagnostic plus approfondi.logLeveln'affecte paslogHandler. - Callback hôte
logHandler(recommandé) : reçoit chaqueLogRecorddu SDK (le flux complet), totalement indépendant delogLevel/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.messageest expurgé et ne contient aucun jeton Bearer,ticket, ou jeton RTC en texte clair.
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
initializedansApplication.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 avec103004pendant qu'un Travel démarre, est actif ou se termine : attendez toujoursendTravel()d'abord. Le SDK ne rejette jamais un Travel actif comme effet secondaire deinitialize. - L'expérience est liée au cycle de vie de l'hôte : appelez
endTraveldans leonDestroyde l'Activity/Fragment(ou leonCleareddu 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 appelezremoveListener. - 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 danslifecycleScope/viewModelScopedepuis 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
CancellationExceptioninchangée plutôt que de la convertir enSDKError; 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()etsendCommand()sur le thread principal ; un appel hors du thread principal lève de manière synchrone uneIllegalStateException.
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 appelezupdateToken; 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
100002synchrone provenant de l'initialisation signifie quemodelest vide ; fournissez le nom et la version complets du modèle, puis initialisez à nouveau. Si unmodelnon 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; utilisezSDKError.rawet vérifiez que lemodel, l'hôte API, la clé API, le compte et la région correspondent.
13. Adaptation du mode
- Utilisez le
moderenvoyé parstartTravelpour décider des capacités d'interaction à exposer : les modes directing et acting utilisent l'instruction textuellesendInstruct(acting utilise égalementaspectRatiopour l'orientation du lecteur et masque le retour en arrière) ; le mode aventure utilise la commande de contrôlesendCommand. - 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 (actuellement60/90/120, par défaut60) ; directing et acting ignorent la valeur (le serveur l'ignore et renvoienull). Le passage d'une valeur non prise en charge fait retourner400000par 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.
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)
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 :
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 |
|
Session | le |
Heure de survenue | l'heure approximative (à la minute près suffit) |
Code d'erreur | le |
É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 |
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.