Le point d'entrée du SDK iOS HappyOyster est le singleton au niveau du processus HappyOysterEngine.shared. Les méthodes métier sont toutes async throws et lèvent une OysterSDKError en cas d'échec. Une expérience unique est portée par un handle OysterTravel, couvrant trois modes — aventure, réalisation et jeu d'acteur — sur UIKit et SwiftUI.
- Ce document est la description des fonctionnalités externes + référence de l'interface pour le SDK Happy Oyster iOS : il explique les paramètres, le timing, l'utilisation et de courts exemples de chaque type et méthode publics, un par un.
- Pour le flux d'intégration complet (configuration du projet, configuration des dépendances, coordination côté serveur, exécution de bout en bout), consulter la documentation du projet d'exemple ; il n'est pas répété ici.
1. Concepts de base
Quelques termes d'abord, pour faciliter la lecture du reste.
Concept | Description |
|---|---|
jeton | Jeton d'authentification HTTP (clé API temporaire Bailian). Votre serveur l'échange via l'API Bailian et le transmet ; il est injecté via |
ticket | Identifiant d'essai à usage unique. Votre serveur l'échange via la plateforme ouverte |
Monde | Un monde IA, contenant des personnages et des scènes. Créé et géré par votre serveur ; le SDK n'est pas impliqué. |
Travel | Une seule expérience en temps réel, correspondant à un descripteur |
Statut de la session |
|
Mode |
|
2. Aperçu
Après avoir intégré ce SDK, votre application peut entrer dans des « mondes » générés en temps réel par l'IA, et vivre une expérience vidéo interactive en temps réel dans trois modes — adventure, directing, ou acting : démarrer l'expérience → lecture en temps réel → interaction en temps réel → contrôle du processus (pause/reprise/retour en arrière/fin) → rappels d'état et d'erreur.
Chaque mode prend en charge un ensemble de fonctionnalités différent. Piloter votre interface utilisateur à partir du mode renvoyé par start() :
Capacité |
|
|
|
|---|---|---|---|
| Oui | Non | Non |
| Non | Oui | Oui |
| Non | Oui | Oui |
| Non | Oui | Non — masquer le point d'entrée |
| Oui | Oui | Oui |
| Appliqué | Ignoré | Ignoré |
acting sont d'abord en portrait : start() renvoie un aspectRatio (9:16 / 16:9) pour la session. L'utiliser pour choisir l'orientation du lecteur et la taille du conteneur avant de récupérer le flux (voir §8).import HappyOysterSDK ; les points d'entrée principaux sont de deux types.
HappyOysterEngine — le point d'entrée d'orchestration, un singleton au niveau du processus HappyOysterEngine.shared.
Méthode / Propriété | Description |
|---|---|
| Initialiser l'environnement d'exécution et enregistrer automatiquement le moteur en temps réel (une fois, avant |
| Injecter / mettre à jour le jeton d'authentification HTTP |
| Créer un descripteur de session avec un identifiant à usage unique |
| Libérer les ressources (peut |
| La version actuelle du SDK |
OysterTravel — le descripteur de session pour une expérience, créé par createTravel(ticket:).
Méthode / Propriété | Description |
|---|---|
| Vue de lecture (UIKit / SwiftUI) |
| Flux de push des changements de statut + erreurs / statut actuel observable |
| Se connecter et jouer (demander éventuellement la durée maximale d'une expérience d'aventure) |
| Instruction textuelle en mode réalisation |
| Contrôle du mode Aventure |
| Pause / reprise ( |
| Rembobinage (en pause uniquement) |
| Terminer (idempotent, assurez-vous de l'appeler) |
| Céder / restaurer temporairement le microphone |
OysterLog pour prendre en charge la journalisation interne du SDK ; HappyOysterEngine.version pour lire la version ; OysterVideoView est la vue de lecture SwiftUI (équivalente à videoView). L'utilisation est décrite plus loin.
Cycle de vie : initialiser → injecter le jeton → créer la session → monter la vidéo + s'abonner aux événements → démarrer la lecture → interagir → terminer. Le SDK n'est pas responsable de la création ou de la gestion des mondes (effectuée par votre serveur), et n'expose pas non plus les détails de communication en temps réel de bas niveau.
3. Démarrage rapide
Un flux complet de l'initialisation à la fin, avec des commentaires étape par étape. Les détails de chaque API se trouvent dans la §6.
4. Prérequis
Élément | Exigence |
|---|---|
OS minimum | iOS 15.0+ (tous les types publics sont marqués |
Langage | Swift ( |
Concurrence | Accès au thread principal (les types d'entrée sont marqués |
Réseau | Accès au réseau public requis |
Autorisations |
|
Info.plist doit fournir NSMicrophoneUsageDescription, sinon le démarrage de la capture en temps réel plantera. Lorsque vous avez besoin d'un accès exclusif au microphone (par ex. reconnaissance vocale), utilisez pauseLocalAudioCapture() / resumeLocalAudioCapture() pour le libérer et le restaurer temporairement (voir §6.2).
5. Intégration et authentification
5.1 Intégration et dépendances
import HappyOysterSDK est tout ce dont vous avez besoin au niveau du code. Le SDK est distribué sous forme de binaire précompilé (xcframework) via les sous-spécifications CocoaPods, publié sur le Trunk public de CocoaPods — déclarer les dépendances dans votre Podfile :
AliVCSDK_ARTC est requis chaque fois que vous intégrez HappyOysterSDK/StreamAliRTC : s'il est manquant, le SDK revient silencieusement à Loopback — il peut se connecter et atteindre running, mais affiche un écran noir sans erreur.5.2 Modèle d'authentification
Le SDK n'obtient ni ne rafraîchit les jetons, ce qui permet de garder les choses légères. L'authentification comporte deux couches, et l'intégrateur gère leurs cycles de vie :
- Jeton d'authentification HTTP (clé API temporaire Bailian) : Votre serveur l'échange via l'API Bailian et le transmet ; il est injecté via
updateToken(_:). Certains services internes du SDK appellent directement la passerelle Bailian, en transportant ce jeton pour l'authentification — il doit donc s'agir d'une clé API temporaire émise par Bailian, et non d'un jeton provenant de votre propre service métier. Le SDK ne conserve que le plus récent, ne le persiste ni ne le rafraîchit ; après son expiration, vous le rééchangez et le réinjectez. - Identifiant d'essai à usage unique
ticket: Votre serveur l'échange via la plateforme ouverteget-travel-credential(préfixetk_, valide pendant 30 minutes, à usage unique), utilisé comme argument decreateTravel(ticket:); il devient invalide une fois l'expérience terminée (normalement ou anormalement) ou expirée, et ne peut pas être réutilisé.
start / pause / resume / rewind / sendInstruct / sendCommand) sont rejetés avec 108001 et toute expérience en cours est terminée par le SDK (voir §9). OysterSDKError.raw contient une raison lisible par l'homme ; invitez l'utilisateur à effectuer une mise à niveau lorsque la version est trop ancienne.updateToken(_:). Il y a deux endroits où vous devez déterminer si le jeton a expiré :
- Lors de l'appel d'API telles que
engine.createTraveloutravel.start, gérer l'erreur et vérifier les types d'erreur de jeton expiré/invalide (101001/101002) ; après avoir injecté un nouveau jeton, rappeler l'API correspondante. - Lors de l'écoute de l'événement
.errordeOysterTravelEvent, vérifier les types d'erreur de jeton expiré/invalide, redemander le jeton et l'injecter.
6. Référence de l'API
Il existe deux types d'entrée, tous deux @MainActor et @available(iOS 15.0, *). Les méthodes métier sont async throws et lèvent OysterSDKError en cas d'échec ; les méthodes avec valeurs de retour sont toutes marquées @discardableResult.
6.1 HappyOysterEngine
Un singleton au niveau du processus, le point d'entrée d'orchestration. init n'est pas public — toujours utiliser HappyOysterEngine.shared ; ne pas l'instancier vous-même (le moteur en temps réel sous-jacent est également un singleton de processus).
initialize(config:)
- Objectif : Initialiser l'environnement d'exécution et enregistrer automatiquement le moteur en temps réel (aucun enregistrement manuel n'est nécessaire par l'hôte).
- Paramètres :
config.apiHostest l'URL de la passerelle Bailian, et non votre serveur métier, et est obligatoire ; dans les environnements de pré-version ou d'essai, vous devez transmettre explicitement la passerelle correspondante, sinon les requêtes échouent (par ex.106001, le domaine ne peut pas être résolu).config.modelest le nom du modèle versionné activé pour votre compte et est également obligatoire sans valeur par défaut — Happy Oyster est divisé en sous-modèles par mode, de sorte que le SDK ne peut pas déduire lequel utiliser. Les deux doivent appartenir au même compte et à la même région que le jeton injecté. Les autres champs sont détaillés dans la §8OysterConfig. - Un modèle sert un
mode: chaque modèle par mode a sa propre route de passerelle, donc un seulinitializene sert que les mondes de ce seulmode. Si votre application propose des mondes dans plusieurs modes, appelez simplement à nouveauinitialize()avec le modèle correspondant avant d'entrer dans un monde d'un mode différent — au repos, la dernière configuration l'emporte, aucunecleanup()n'est nécessaire et le jeton injecté est conservé ; pendant qu'un Travel est en cours, l'appel est ignoré, alorsend()d'abord. Un modèle qui ne correspond pas aumodedu monde est rejeté par la passerelle avecAccessDenied, normalisé en106003. - Quand l'utiliser : Appeler une fois avant
createTravel, le plus tôt possible après le lancement de l'application. - Renvoie :
Bool— si laconfigque vous avez transmise a pris effet. Elle estfalsedans deux cas : la configuration est invalide (apiHost/modelvide ou ne formant pas une URL de passerelle valide), ou un Travel est en cours donc l'appel a été ignoré. Dans les deux cas, l'environnement d'exécution reste inchangé. - Remarque : Au repos, l'appeler à nouveau reconfigure l'environnement d'exécution avec la nouvelle configuration (changer
apiHost/modelne nécessite pas decleanup(), et le jeton injecté est conservé) ; c'est une opération nulle avec un avertissement uniquement lorsqu'un Travel est en cours, alorsend()d'abord. Une configuration invalide laisse l'environnement d'exécution inchangé. N'utilisez pasisReadypour savoir si une re-initializea réussi — si elle a été rejetée, la configuration précédente est toujours en vigueur etisReadyrestetrue;isReadyrépond à « le moteur est-il utilisable maintenant », la valeur de retour répond à « la configuration que je viens de transmettre a-t-elle pris effet ».
OysterLog
- Objectif : Configurer et prendre en charge la journalisation interne du SDK, en l'imprimant dans votre propre module de journalisation. Fournit
setMinimumLevel(_:)pour définir le niveau etsetHandler(_:)pour une sortie personnalisée (voir l'exemple de la §3).
updateToken(_:)
- Objectif : Injecter ou mettre à jour le jeton d'authentification HTTP (clé API temporaire Bailian, §5.2).
- Quand l'utiliser : Après
initialize, appelable à tout moment ; rééchanger et appeler à nouveau après l'expiration du jeton ou après la réception d'une erreur liée à l'authentification (101001/101002). - Remarque : Opération nulle avec un avertissement si
initializen'est pas appelé.
createTravel(ticket:)
- Objectif : Créer un descripteur de session unique avec un
ticketà usage unique. - Paramètre :
ticketest un identifiant à usage unique ; une fois créé, il est considéré comme occupé pour cette expérience. - Quand l'utiliser : Appeler avant chaque nouvelle expérience ; le descripteur renvoyé n'est pas encore connecté et vous devez appeler
travel.start()par la suite. La vidéo est extraite du descripteur renvoyé (voir §6.2). - Remarque (
throwssynchrone) : lève100001si noninitialize; lève103004si appelé à nouveau avant que le Travel précédent n'aitend()(chaque moteur n'autorise qu'un seul Travel actif à la fois).
cleanup()
- Objectif : Libérer les ressources du SDK (terminer le voyage actif, la configuration d'exécution, le jeton).
- Quand l'utiliser : Lors de la fermeture complète du SDK ou en cas de besoin de modifier la
config. - Remarque :
async— en interne, il appelle de manière déterministeend()sur le voyage actif actuel en premier, puis démantèle l'environnement d'exécution, sans laisser de processus « fire-and-forget ». Après la libération, vous pouvez à nouveauinitialize.
6.2 OysterTravel
Le handle de session créé par createTravel ; à usage unique, invalidé une fois qu'un état terminal (end / fin côté serveur / échec) est atteint, nécessitant un nouveau createTravel via le moteur. C'est aussi un ObservableObject (@Published status, peut piloter directement SwiftUI).
videoView / OysterVideoView(travel:)
- Objectif : Le point d'entrée de rendu pour l'image distante — « le SDK fournit la vue, l'hôte la place ». Pour UIKit, prendre
travel.videoView; pour SwiftUI, utiliserOysterVideoView(travel:). - Quand l'utiliser : Disponible dès la création du handle (un accès répété renvoie la même vue) ; montez-la dans n'importe quelle hiérarchie, et une fois le moteur prêt, elle s'affiche automatiquement. Le montage avant ou après
start()fonctionne dans les deux cas, sans écran noir. - Remarque : Lorsque la session se termine, le SDK libère automatiquement la liaison de rendu ; retirer la vue de la hiérarchie si nécessaire.
events / status / isEnded
- Objectif :
eventsest le flux push des changements de statut et des erreurs ;statusest le statut externe actuel observable ;isEndedest un indicateur lisible de manière synchrone pour l'état terminal. - Quand l'utiliser : Il est recommandé de commencer à consommer
eventsavantstart(), pour éviter de manquer les premiers statuts. - Remarque : Chaque accès à
eventsrenvoie un flux indépendant, prenant en charge les abonnements multiples ; se désabonner = terminer l'itérationfor await(ou détruire laTaskdétenue). Dans SwiftUI, vous pouvez observer directementstatusavec@StateObject/@ObservedObject(les erreurs transitent toujours parevents). Voir la §7.
start() / start(maxExperienceTimeSec:)
- Objectif : Utilisez le
ticketcapturé au moment de la création pour l'échanger contre la configuration de voyage + jointure RTC et vous connecter pour lire. En cas de succès, le SDK établit automatiquement la connexion en temps réel et lance l'interrogation interne de l'état, en exposant l'état viaevents. - Paramètre :
maxExperienceTimeSec(facultatif) — demande la durée maximale (en secondes) de cette expérience d'aventure. La valeur est envoyée au serveur telle quelle ; les valeurs autorisées, la durée effective réelle et le moment de fin automatique sont tous décidés par le serveur — le SDK n'effectue aucune validation locale. Passernil(ou appeler la méthode sans paramètrestart()) utilise la durée par défaut du serveur. Le mode Réalisation ignore ce paramètre. Lorsque le temps est écoulé, le serveur met fin à l'expérience et l'hôte reçoit l'état terminalendedviaevents(identique à une fin côté serveur, voir §7). - Retourne :
OysterStartTravelData(mode/version/encryptedTravelId, etc., voir §8), qui détermine l'interface utilisateur d'interaction. - Erreurs :
401010/401011(identifiant invalide/utilisé),403002(monde non prêt),403007(spécification de service non activée, par ex. acting),429001/429002(limite de concurrence / capacité épuisée),500001(défaillance de ressource/serveur),103004(démarrage simultané). - Le
modedu monde duticketdoit correspondre aumodeltransmis àinitialize(responsabilité de l'appelant) : avec les modèles par mode, chaque modèle possède sa propre route de passerelle, etstart()envoie leticketà la route du modèle actuellement initialisé. Le SDK ne le vérifie pas et ne peut pas le faire pour vous au préalable — lemodeest fourni par la réponse à cet appelstart()même (OysterStartTravelData.mode) ; avant l'appel, le SDK ne détient qu'unticketopaque et un nom de modèle, sans mode à comparer, et déduire le mode à partir du nom du modèle reviendrait à deviner un schéma de nommage propre au serveur, ce que le SDK ne fait pas. Donc : avant d'entrer dans un monde d'un mode différent, appelez à nouveauinitialize()avec le modèle correspondant (au repos, la dernière configuration l'emporte — aucuncleanup()n'est nécessaire et le jeton est conservé ; pendant qu'un Travel est en cours, l'appel est ignoré, alors appelez d'abordend()). En cas de non-concordance, cet appelstart()échoue au niveau de la passerelle ; lors du diagnostic, vérifiez d'abord que lemodelactuel et lemodedu monde duticketcorrespondent bien, puis consultez les codes d'erreur d'identification ci-dessus. - Remarque (fin automatique en l'absence de flux) : Le serveur envoie un « délai d'attente sans flux » (par défaut ~30s). Si, après la connexion, aucun flux n'est reçu pendant cette durée (il n'atteint jamais
running), le SDK met automatiquement fin à l'expérience, passe àfailed, et expose105006via le.errordeevents(fatal ; à gérer en retournant à l'écran de pré-démarrage, pas besoin de le chronométrer vous-même).
pause() / resume()
- Objectif : Mettre en pause / reprendre l'expérience (idempotent).
- Quand l'utiliser : Pris en charge par les mondes
directingetacting; non pris en charge paradventure. Utilisez lemoderenvoyé parstart()pour décider à l'avance s'il faut afficher un bouton de pause.pausenécessite que l'état actuel soitrunning;resumenécessitepaused. - Erreurs :
103001(aucune expérience active),103002(état/version non autorisé),103003(incompatibilité de mode).
rewind(toSec:)
- Objectif : Rembobiner aux secondes spécifiées. En cas de succès, le SDK rejoint automatiquement avec la configuration rtcConfig d'origine et reprend la lecture.
- Quand l'utiliser : Ne peut être initié que dans l'état
paused, et uniquement par les mondesdirecting—actingetadventurene prennent pas en charge le rembobinage, masquer donc le point d'entrée de rembobinage dans ces modes et ne pas l'appeler. - Erreurs :
103001,103002.
end()
- Objectif : Terminer l'expérience (idempotent, peut être appelé à plusieurs reprises). Après un appel réussi ou une sortie anormale, le SDK déconnecte automatiquement la connexion en temps réel, arrête l'interrogation et libère toutes les ressources de la session ; le
ticketest invalidé en même temps, et le handle entre dans un état terminal. - Quand l'utiliser / Remarque : Que l'utilisateur quitte activement ou que l'expérience se termine passivement (expiration du minuteur, réception de
.ended/.failed, destruction de la page), assurez-vous qu'un seulend()soit atteint, sinon les ressources distantes pourraient ne pas être libérées rapidement. Il est recommandé de canaliser tous les chemins de sortie vers la même méthode de nettoyage idempotente.
sendInstruct(content:) (mode de réalisation)
- Objectif : Envoyer une instruction textuelle pour diriger le scénario.
- Quand l'utiliser : Mode de réalisation ; envoyé directement lorsque
running, mis en cache lorsquepausedet renvoyé avec la première image après la reprise versrunningvia reconnexion. - Erreurs :
103001,103002,103003(appelé en mode aventure),403004(modération de contenu),404000(voyage non trouvé).
sendCommand(_:) / flushCommands() (mode aventure)
sendCommand: Envoyez des commandes de contrôle de direction/vue/action (voir §8OysterAdventureCommand; fire-and-forget, aucun retour, ne lève pas d'exception). Efficace uniquement en mode adventure lorsquerunning. L'entrée externe peut être à haute fréquence à chaque image, et le SDK limite le débit en interne (échantillonnage du dernier gagnant, fusion d'images au débit de ligne RTC) ; l'hôte n'a pas besoin de se limiter lui-même. Notez que la réponse du serveur aux commandes a elle-même une latence, de sorte que le temps d'effet réel n'est pas fixe.flushCommands: Appelé au moment du « relâchement de touche / relâchement d'entrée », renvoyant immédiatement la dernière commande déjà en attente dans la file d'attente ; une pure non-opération lorsqu'il n'y a pas de commande en attente, ne générant aucune nouvelle commande.- Erreurs (toutes remontées via le
.errordeevents, pasthrows) : aucune expérience active103001; appelé en mode de réalisation103003; canal en temps réel non prêt / échec de l'envoi105004.
pauseLocalAudioCapture() / resumeLocalAudioCapture()
- Objectif : Libérer ou restaurer temporairement l'occupation de la capture du microphone local par le SDK.
- Quand l'utiliser : Lorsqu'une fonctionnalité comme la reconnaissance vocale a besoin d'un accès exclusif au microphone, appeler d'abord
pausepuisresume.
7. Événements et statut
Les événements sont attachés à OysterTravel.events et constituent le canal push actif du SDK vers vous, utilisé pour faire remonter des situations non déclenchées par vos propres appels (par ex. des problèmes avec la connexion en temps réel gérée en interne ou l'interrogation de statut).
- SwiftUI :
OysterTravelest unObservableObject; utiliser directement@StateObject/@ObservedObjectpour observerstatuset piloter l'interface utilisateur ; les erreurs proviennent toujours deevents. - Impératif / UIKit : dans une
Task,for await event in travel.events { ... }, etswitchsur.statusChanged/.error; annuler laTaskmaintenue une fois terminé.
OysterTravelStatus (5 états de processus + 2 états terminaux) :
Statut | Description | Traitement typique |
|---|---|---|
| après la création, avant le démarrage | — |
| connexion / reconnexion (connexion / reconnexion interne) | afficher l'indication de connexion / reconnexion |
| flux prêt, interactif (lecture interne) | afficher l'image et les contrôles |
| pause acceptée, en attente de la confirmation du serveur | afficher « mise en pause… » |
| en pause (confirmé) | afficher l'état en pause (seul |
| terminé (fin active ou fin côté serveur). Terminal | finaliser et fermer la page |
| échoué. Terminal | afficher l'erreur et terminer |
ended / failed, la session est terminée et toutes les opérations de session (pause/reprise/sendCommand…) ne prennent plus effet. Les rappels peuvent être déclenchés sur le thread principal, vous pouvez donc mettre à jour l'interface utilisateur directement.8. Modèles de données
@available(iOS 15.0, *). Les valeurs de retour et paramètres ci-dessous sont des sorties du SDK, construits sur place en interne avec des types Swift natifs (Date / TimeInterval / OysterTravelStatus) ; ils ne sont pas Codable et n'exposent pas les détails du protocole (snake_case) — le décodage du protocole se fait à l'intérieur du SDK.- Remarque : les rawValues des commandes sont en lower camelCase (par ex.
front/mouseLeft/jump) ; les valeurs d'énumération ci-dessus font autorité. - Remarque :
modeest extérieurementadventure(wander) /directing(histoire) /acting(jeu de rôle) ; la définition deOysterModeValuefait autorité. - Remarque :
aspectRatioest une chaîne ouverte (actuellement9:16/16:9, d'autres peuvent être ajoutées). L'analyser commewidth:heightet comparer le ratio au lieu de faire correspondre les valeurs connues.
9. Codes d'erreur
Le SDK signale les erreurs uniformément sous forme de OysterSDKError, et le type est toujours distingué par code — ne jugez pas le type par « le chemin d'où provient l'erreur » : le même code peut être levé par une méthode métier (async throws) ou exposé via le .error de events. Pour une correspondance typée, utilisez error.kind (voir §8 OysterErrorKind).
Codes d'erreur : serveur 4xxxxx/5xxxxx, client-local 1xxxxx.
Codes d'erreur serveur (courants)
code | Signification | Traitement suggéré |
|---|---|---|
| Paramètres invalides (valeur d'énumération invalide, etc.) | Vérifier les paramètres de la requête ou la version du SDK |
| Identifiant d'expérience ( | Faire réémettre l'identifiant par le serveur |
| Identifiant d'expérience ( | Identifiant à usage unique ; réémettre |
| Le monde n'existe pas, a été supprimé ou n'appartient pas au développeur actuel (y compris un monde supprimé après l'émission de l'identifiant) | Choisir à nouveau un Monde valide |
| État du monde non prêt | Attendre que le monde soit prêt avant de commencer |
| L'API n'autorise que la clé API principale | Une clé temporaire ne peut pas être utilisée pour cette API |
| Contenu d'entrée rejeté par la modération de contenu ; s'applique aux instructions textuelles de | Modifier l'entrée et réessayer |
| La spécification de service demandée n'est pas activée | Ne pas réessayer comme si la capacité était pleine ; passer à une spécification activée (généralement : le compte n'a pas de spécification d'interprétation) |
| Configuration de la capacité temporairement indisponible | Réessayer plus tard |
| La ressource n'existe pas (propriété du monde/wander ou aucun artefact) | Vérifier l'ID / le statut |
| La requête est en conflit avec l'état actuel de la ressource | Vérifier l'état de l'expérience |
| Limite de concurrence atteinte pour cette spécification | Réessayer après la fin d'une session existante (ne pas confondre avec |
| Capacité disponible insuffisante | Réessayer plus tard |
| Erreur système interne | Réessayer plus tard / le signaler |
| Allocation des ressources d'inférence ou défaillance du service interne | Réessayer plus tard |
Codes d'erreur client-local
code | Signification | Le SDK termine automatiquement la session | Traitement suggéré |
|---|---|---|---|
| Appelé avant l'initialisation du SDK ; couvre également un | Non (levé de manière synchrone, rejet de cet appel) |
|
| Jeton d'authentification HTTP non injecté | Non | réessayer après |
| Jeton d'authentification HTTP invalide / rejeté | Non | rééchanger le jeton puis réessayer |
| Aucune expérience active actuellement | Non (rejet de cet appel) |
|
| L'état/la version actuel(le) ne permet pas cette opération | Non (rejet de cet appel) | vérifier l'état de l'expérience / |
| Incompatibilité de mode (par ex. | Non (rejet de cet appel) | choisir la bonne API par |
| Création/démarrage simultané de l'expérience | Non (levé de manière synchrone) | sérialiser les appels, |
| Échec de la connexion en temps réel | Oui | terminer et redémarrer |
| Expiration du délai de connexion en temps réel | Oui | terminer et redémarrer |
| Délai d'attente dépassé pour la première image vidéo | Oui | terminer et redémarrer |
| Canal en temps réel non prêt / échec de l'envoi | dépend (échec de l'envoi actif ; le heartbeat est en lecture seule) | envoyer après |
| Délai d'attente du rappel (par défaut 30s) | Non | réessayer, et augmenter |
| Aucun flux après la connexion ; le SDK termine automatiquement l'expérience | Oui | terminer et redémarrer |
| Erreur de réseau local | Non | réessayable |
| Échec de l'analyse de la réponse | dépend | mettre à niveau le SDK / signaler |
| Aucun code d'erreur reconnaissable / code d'erreur de chaîne de proxy | Non | réessayable |
| Désactivé à distance par le commutateur de fonctionnalité du serveur (arrêt complet ou version trop ancienne ; raison dans | Oui | Suivre la raison dans |
OysterSDKError n'a pas de isFatal). Sémantiquement, « fatal » signifie spécifiquement si le SDK met activement fin à la session (déconnexion RTC, libération de l'ensemble de la session) —
- Erreurs qui mettent fin automatiquement à la session (par ex.
105001/105002/105003/105006/108001) : l'hôte perçoit cela depuis l'état terminal de la machine à états (status → failed, exposé via le.statusChangeddeevents), et retourne à l'écran précédant le « démarrage de l'expérience » en conséquence, sans avoir besoin d'évaluer la fatalité elle-même. - Erreurs de rejet d'appel (
100001/103001/103002/103003/103004) : levées de manière synchrone / l'appel est rejeté lorsque vous appelez activement ; elles ne mettent pas fin à la session. - Autres erreurs non fatales (par ex.
101001/101002/105005/106001/106003) : elles ne mettent pas fin à la session ; réessayer comme suggéré ou continuer après avoir réinjecté le jeton.
106001 peut avoir deux causes : une erreur de réseau local ou un apiHost incorrect. Si une nouvelle tentative ne rétablit pas la requête, vérifier si apiHost est configuré correctement.106003 apparaissant après avoir défini model signifie généralement que le nom ou la version du modèle est incorrect ou non activé pour votre compte : vérifiez le modèle avec l'apiHost et le jeton, qui doivent tous appartenir au même compte et à la même région — la passerelle rejette une incompatibilité avec AccessDenied, normalisée sous ce code.