Skip to main content

Référence de l'API du SDK iOS HappyOyster

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 updateToken(_:), et le SDK le transporte en tant que HTTP Bearer lors de la requête vers la passerelle. 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.

ticket

Identifiant d'essai à usage unique. Votre serveur l'échange via la plateforme ouverte get-travel-credential (préfixe tk_, valide pendant 30 minutes, à usage unique), utilisé comme argument de createTravel(ticket:) ; il devient invalide une fois l'expérience terminée ou expirée, et ne peut pas être réutilisé.

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 OysterTravel. À usage unique ; invalidé une fois qu'un état terminal est atteint, nécessitant un nouveau createTravel via le moteur.

Statut de la session

OysterTravelStatus : idle → prepare → running → pausing → paused (en pause, revient à prepare → running via reconnexion), plus deux états terminaux ended / failed (voir §7).

Mode

adventure (commandes de direction/vue/action), directing (scénario guidé par texte), ou acting (performance de personnage guidée par texte). Le mode renvoyé par start() détermine l'interface utilisateur en conséquence ; voir la §2 pour ce que chaque mode prend en charge.

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é

adventure

directing

acting

sendCommand (direction/vue/action)

Oui

Non

Non

sendInstruct (instruction textuelle)

Non

Oui

Oui

pause() / resume()

Non

Oui

Oui

rewind(toSec:)

Non

Oui

Non — masquer le point d'entrée

end()

Oui

Oui

Oui

start(maxExperienceTimeSec:)

Appliqué

Ignoré

Ignoré

Les mondes 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

initialize(config:)

Initialiser l'environnement d'exécution et enregistrer automatiquement le moteur en temps réel (une fois, avant createTravel)

updateToken(_:)

Injecter / mettre à jour le jeton d'authentification HTTP

createTravel(ticket:)

Créer un descripteur de session avec un identifiant à usage unique

cleanup()

Libérer les ressources (peut initialize à nouveau)

version

La version actuelle du SDK

OysterTravel — le descripteur de session pour une expérience, créé par createTravel(ticket:).

Méthode / Propriété

Description

videoView / OysterVideoView(travel:)

Vue de lecture (UIKit / SwiftUI)

events / status

Flux de push des changements de statut + erreurs / statut actuel observable

start() / start(maxExperienceTimeSec:)

Se connecter et jouer (demander éventuellement la durée maximale d'une expérience d'aventure)

sendInstruct(content:)

Instruction textuelle en mode réalisation

sendCommand(_:) / flushCommands()

Contrôle du mode Aventure

pause() / resume()

Pause / reprise (directing et acting)

rewind(toSec:)

Rembobinage (en pause uniquement)

end()

Terminer (idempotent, assurez-vous de l'appeler)

pauseLocalAudioCapture() / resumeLocalAudioCapture()

Céder / restaurer temporairement le microphone

Il existe également quelques exports d'aide : 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.
import HappyOysterSDK

// 1) Initialize (as early as possible after app launch, once before createTravel)
let engine = HappyOysterEngine.shared
engine.initialize(config: OysterConfig(
    apiHost: "[workspace-id].[region].maas.aliyuncs.com",// For the API host, refer to the Bailian documentation https://www.alibabacloud.com/help/en/model-studio/base-url
    model: "happyoyster-1.0-adventure"                  // Versioned model name enabled for your account, required; see the Happy Oyster model documentation
))

// 2) (Optional) Take over logging: set level + custom output
OysterLog.setMinimumLevel(.info)
OysterLog.setHandler { level, tag, message in
    print("[Oyster][\(level)][\(tag)] \(message)")
}

// 3) Inject the HTTP auth token (Bailian temporary API Key, delivered by your server)
engine.updateToken(temporaryApiKey)

// 4) Create a session handle with a one-time ticket (not yet connected)
let travel = try engine.createTravel(ticket: ticket)

Task { @MainActor in
    // 5) Mount the video (UIKit; for SwiftUI use OysterVideoView(travel:))
    containerView.addSubview(travel.videoView)

    // 6) Subscribe to events before start, to avoid missing early statuses
    let eventTask = Task {
        for await event in travel.events {
            switch event {
            case .statusChanged(let status): render(status)   // §7 status table
            case .error(let error):          handle(error)     // §9 error.code / error.kind
            }
        }
    }

    do {
        // 7) Connect and play
        let data = try await travel.start()

        // 8) Interact based on mode
        if data.mode == .directing {
            _ = try await travel.sendInstruct(content: "Suddenly it starts to pour")
        } else {
            travel.sendCommand(OysterAdventureCommand(translation: .front))
        }
    } catch let error as OysterSDKError {
        handle(error)
    }

    // 9) Funnel every exit path into a single end()
    _ = try? await travel.end()
    eventTask.cancel()
}

// Exit the SDK / switch gateway: await engine.cleanup()
Pour la configuration du projet, la configuration des dépendances (y compris l'adaptateur AliRTC requis et le binaire du fournisseur), la coordination côté serveur et une exécution de bout en bout, consulter la documentation du projet d'exemple.

4. Prérequis

Élément

Exigence

OS minimum

iOS 15.0+ (tous les types publics sont marqués @available(iOS 15.0, *))

Langage

Swift (async/await)

Concurrence

Accès au thread principal (les types d'entrée sont marqués @MainActor)

Réseau

Accès au réseau public requis

Autorisations

Info.plist doit inclure NSMicrophoneUsageDescription (voir ci-dessous)

Autorisation du microphone : Une expérience vidéo interactive en temps réel nécessite un canal audio/vidéo en temps réel bidirectionnel (liaison montante + descendante), le SDK occupe donc le microphone local pendant son exécution — il ne s'agit pas d'un enregistrement. 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 :
# HappyOysterSDK / AliVCSDK_ARTC are both published on the public CocoaPods source.
pod 'HappyOysterSDK', '1.0.3'              # Aggregate entry point (Core + World)
pod 'HappyOysterSDK/UI', '1.0.3'           # Optional default UI components (video view, control HUD)
pod 'HappyOysterSDK/StreamAliRTC', '1.0.3' # Video stream + AliRTC engine adapter (already depends on Stream)

# RTC vendor binary: weak-linked by the SDK, not redistributed with it — bring your own.
pod 'AliVCSDK_ARTC', '7.11.0'
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.
La configuration du projet et le flux d'initialisation de bout en bout sont gérés par le projet d'exemple ; consulter la documentation du projet d'exemple. Ce document se concentre sur l'interface elle-même.

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 :
  1. 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.
  2. Identifiant d'essai à usage unique ticket : Votre serveur l'échange via la plateforme ouverte get-travel-credential (préfixe tk_, valide pendant 30 minutes, à usage unique), utilisé comme argument de createTravel(ticket:) ; il devient invalide une fois l'expérience terminée (normalement ou anormalement) ou expirée, et ne peut pas être réutilisé.
Les AK, clés de signature et autres identifiants à privilèges élevés n'existent que sur votre serveur ; le SDK client ne les touche jamais. Ce que le client reçoit est toujours une clé API temporaire à courte durée de vie.
Feature Gate (commutateur distant / mise à niveau forcée) : Le serveur peut désactiver le SDK à distance ou définir une version minimale prise en charge. Lorsqu'il est désactivé, les appels contrôlés (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.
Gestion de l'expiration du jeton : Après l'expiration du jeton d'authentification HTTP ci-dessus, demander immédiatement un nouveau jeton à votre serveur et l'injecter via updateToken(_:). Il y a deux endroits où vous devez déterminer si le jeton a expiré :
  1. Lors de l'appel d'API telles que engine.createTravel ou travel.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.
  2. Lors de l'écoute de l'événement .error de OysterTravelEvent, 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).
@MainActor @available(iOS 15.0, *)
public final class HappyOysterEngine {
    public static let shared: HappyOysterEngine            // the unique process-level instance
    public static let version: String                      // current SDK version

    @discardableResult
    public func initialize(config: OysterConfig) -> Bool  // initialize (once before createTravel)
    public func updateToken(_ token: String)               // inject/update the HTTP auth token
    public func createTravel(ticket: String) throws -> OysterTravel  // create a session handle with a one-time credential
    public func cleanup() async                            // release resources (can initialize again)
}
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.apiHost est 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.model est 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 §8 OysterConfig.
  • Un modèle sert un mode : chaque modèle par mode a sa propre route de passerelle, donc un seul initialize ne sert que les mondes de ce seul mode. Si votre application propose des mondes dans plusieurs modes, appelez simplement à nouveau initialize() avec le modèle correspondant avant d'entrer dans un monde d'un mode différent — au repos, la dernière configuration l'emporte, aucune cleanup() n'est nécessaire et le jeton injecté est conservé ; pendant qu'un Travel est en cours, l'appel est ignoré, alors end() d'abord. Un modèle qui ne correspond pas au mode du monde est rejeté par la passerelle avec AccessDenied, normalisé en 106003.
  • Quand l'utiliser : Appeler une fois avant createTravel, le plus tôt possible après le lancement de l'application.
  • Renvoie : Bool — si la config que vous avez transmise a pris effet. Elle est false dans deux cas : la configuration est invalide (apiHost / model vide 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 / model ne nécessite pas de cleanup(), et le jeton injecté est conservé) ; c'est une opération nulle avec un avertissement uniquement lorsqu'un Travel est en cours, alors end() d'abord. Une configuration invalide laisse l'environnement d'exécution inchangé. N'utilisez pas isReady pour savoir si une re-initialize a réussi — si elle a été rejetée, la configuration précédente est toujours en vigueur et isReady reste true ; isReady ré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 et setHandler(_:) 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 initialize n'est pas appelé.
createTravel(ticket:)
  • Objectif : Créer un descripteur de session unique avec un ticket à usage unique.
  • Paramètre : ticket est 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 (throws synchrone) : lève 100001 si non initialize ; lève 103004 si appelé à nouveau avant que le Travel précédent n'ait end() (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éterministe end() 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 à nouveau initialize.

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).
@MainActor @available(iOS 15.0, *)
public final class OysterTravel: ObservableObject {
    @Published public private(set) var status: OysterTravelStatus   // current external status (observable)
    public var isEnded: Bool { get }                                // whether a terminal state is reached (synchronously readable)
    public var videoView: UIView { get }                            // UIKit playback view; for SwiftUI use OysterVideoView(travel:)
    public var events: AsyncStream<OysterTravelEvent> { get }       // status change + error, multi-subscribe

    @discardableResult public func start() async throws -> OysterStartTravelData   // connect and play
    @discardableResult public func start(maxExperienceTimeSec: Int?) async throws -> OysterStartTravelData  // connect and play + request max experience duration (adventure mode only)
    @discardableResult public func pause() async throws -> OysterTravelStateData   // pause (directing / acting)
    @discardableResult public func resume() async throws -> OysterTravelStateData  // resume
    @discardableResult public func rewind(toSec: TimeInterval) async throws -> OysterRewindTravelData  // rewind (paused only)
    @discardableResult public func end() async throws -> OysterEndTravelData       // end (idempotent, be sure to call)
    @discardableResult public func sendInstruct(content: String) async throws -> OysterSendInstructData  // directing-mode text instruction

    public func sendCommand(_ command: OysterAdventureCommand)      // adventure-mode control (fire-and-forget)
    public func flushCommands()                                     // manually send an already-submitted pending command
    public func pauseLocalAudioCapture() async                      // temporarily yield the microphone
    public func resumeLocalAudioCapture() async                     // restore microphone occupation
}
Vue vidéo 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, utiliser OysterVideoView(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.
Événements et statut events / status / isEnded
  • Objectif : events est le flux push des changements de statut et des erreurs ; status est le statut externe actuel observable ; isEnded est un indicateur lisible de manière synchrone pour l'état terminal.
  • Quand l'utiliser : Il est recommandé de commencer à consommer events avant start(), pour éviter de manquer les premiers statuts.
  • Remarque : Chaque accès à events renvoie un flux indépendant, prenant en charge les abonnements multiples ; se désabonner = terminer l'itération for await (ou détruire la Task détenue). Dans SwiftUI, vous pouvez observer directement status avec @StateObject/@ObservedObject (les erreurs transitent toujours par events). Voir la §7.
start() / start(maxExperienceTimeSec:)
  • Objectif : Utilisez le ticket capturé 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 via events.
  • 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. Passer nil (ou appeler la méthode sans paramètre start()) 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 terminal ended via events (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 mode du monde du ticket doit correspondre au model transmis à initialize (responsabilité de l'appelant) : avec les modèles par mode, chaque modèle possède sa propre route de passerelle, et start() envoie le ticket à 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 — le mode est fourni par la réponse à cet appel start() même (OysterStartTravelData.mode) ; avant l'appel, le SDK ne détient qu'un ticket opaque 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 à nouveau initialize() avec le modèle correspondant (au repos, la dernière configuration l'emporte — aucun cleanup() n'est nécessaire et le jeton est conservé ; pendant qu'un Travel est en cours, l'appel est ignoré, alors appelez d'abord end()). En cas de non-concordance, cet appel start() échoue au niveau de la passerelle ; lors du diagnostic, vérifiez d'abord que le model actuel et le mode du monde du ticket correspondent 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 expose 105006 via le .error de events (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 directing et acting ; non pris en charge par adventure. Utilisez le mode renvoyé par start() pour décider à l'avance s'il faut afficher un bouton de pause. pause nécessite que l'état actuel soit running ; resume nécessite paused.
  • 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 mondes directing — acting et adventure ne 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 ticket est 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 seul end() 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 lorsque paused et renvoyé avec la première image après la reprise vers running via 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 §8 OysterAdventureCommand ; fire-and-forget, aucun retour, ne lève pas d'exception). Efficace uniquement en mode adventure lorsque running. 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 .error de events, pas throws) : aucune expérience active 103001 ; appelé en mode de réalisation 103003 ; canal en temps réel non prêt / échec de l'envoi 105004.
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 pause puis resume.

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).
var events: AsyncStream<OysterTravelEvent> { get }

@available(iOS 15.0, *)
public enum OysterTravelEvent {
    case statusChanged(OysterTravelStatus)
    // The SDK's internal flow errored, e.g. an internal API request error or a streaming error; note you must check for token expiration here and re-request the token
    case error(OysterSDKError)
}
Il existe deux styles de consommation, choisissez-en un :
  • SwiftUI : OysterTravel est un ObservableObject ; utiliser directement @StateObject/@ObservedObject pour observer status et piloter l'interface utilisateur ; les erreurs proviennent toujours de events.
  • Impératif / UIKit : dans une Task, for await event in travel.events { ... }, et switch sur .statusChanged / .error ; annuler la Task maintenue une fois terminé.
let task = Task {
    for await event in travel.events {
        switch event {
        case .statusChanged(let status): render(status)   // see table below
        case .error(let error):          handle(error)     // error.code / error.kind, see §9
        }
    }
}
// When done: task.cancel()
OysterTravelStatus (5 états de processus + 2 états terminaux) :

Statut

Description

Traitement typique

idle

après la création, avant le démarrage

—

prepare

connexion / reconnexion (connexion / reconnexion interne)

afficher l'indication de connexion / reconnexion

running

flux prêt, interactif (lecture interne)

afficher l'image et les contrôles

pausing

pause acceptée, en attente de la confirmation du serveur

afficher « mise en pause… »

paused

en pause (confirmé)

afficher l'état en pause (seul directing affiche l'entrée de rembobinage)

ended

terminé (fin active ou fin côté serveur). Terminal

finaliser et fermer la page

failed

échoué. Terminal

afficher l'erreur et terminer

Après être entré dans 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.
Lors de l'interrogation interne de l'état, le SDK signale automatiquement les signaux de présence de l'état de tirage et de lecture du client (connexion / lecture / pause / reconnexion / déconnexion), afin que le serveur puisse distinguer les états côté flux des états côté client — comportement purement interne au SDK, dont l'hôte n'a pas besoin d'avoir connaissance ou d'y participer.

8. Modèles de données

Tous les types publics sont marqués @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.
// Configuration
public struct OysterConfig: Sendable {
    public let apiHost: String             // Bailian gateway URL (not a business server), required, passed explicitly by the host
    public let model: String               // Versioned model name (e.g. "happyoyster-1.0-adventure"), required, no default
    public let logLevel: OysterLogLevel?   // .debug/.info/.warning/.error; defaults to .warning when nil
    public let callbackTimeoutMs: Int      // global callback timeout, default 30000; surfaced as 105005 on timeout
    public init(apiHost: String, model: String, logLevel: OysterLogLevel? = nil, callbackTimeoutMs: Int = 30_000)
}

public enum OysterLogLevel: Int, Comparable, CaseIterable, Sendable {
    case debug, info, warning, error
}

// External session status (§7)
public enum OysterTravelStatus: String, Equatable, Sendable, CustomStringConvertible {
    case idle      // after create, before start
    case prepare   // connecting / reconnecting
    case running   // stream ready, interactive
    case pausing   // pause accepted, awaiting server confirmation
    case paused    // paused (confirmed)
    case ended     // terminal: active end or server-side end
    case failed    // terminal: failed
}

// Open string value (preserves unknown values for server-side extension; encoded/decoded as a bare JSON string "running")
public struct OysterRawValue: RawRepresentable, Equatable, Hashable, Codable, Sendable {
    public let rawValue: String
    public init(rawValue: String) { self.rawValue = rawValue }
}
public typealias OysterModeValue = OysterRawValue
public extension OysterModeValue {
    static let adventure = OysterModeValue(rawValue: "adventure")
    static let directing  = OysterModeValue(rawValue: "directing")
    static let acting     = OysterModeValue(rawValue: "acting")
}

// start() return (SDK output, not Codable)
public struct OysterStartTravelData: Equatable, Sendable {
    public let encryptedTravelId: String  // identifier for this experience
    public let encryptedWorldId: String
    public let mode: OysterModeValue       // adventure / directing / acting
    public let playUrl: String?            // currently always returned as null by the server
    public let firstFrame: String?         // first-frame image URL, may be null (produced asynchronously)
    public let version: String             // world version identifier (diagnostics; drive interaction UI from `mode`)
    public let aspectRatio: String?        // "9:16" / "16:9"; only set for acting worlds, nil otherwise
}

// Control API returns (SDK output, not Codable; status is the external enum OysterTravelStatus)
public struct OysterTravelStateData: Equatable, Sendable { public let encryptedTravelId: String; public let status: OysterTravelStatus }
public struct OysterRewindTravelData: Equatable, Sendable { public let encryptedTravelId: String; public let status: OysterTravelStatus; public let resumedAtSec: TimeInterval }
public struct OysterEndTravelData: Equatable, Sendable { public let encryptedTravelId: String; public let status: OysterTravelStatus; public let endedAt: Date; public let duration: TimeInterval }
public struct OysterSendInstructData: Equatable, Sendable { public let encryptedTravelId: String; public let content: String; public let accepted: Bool }

// Adventure-mode control command (strongly typed enums; values aligned with the internal WorldControlParams)
public struct OysterAdventureCommand: Equatable, Sendable {
    public enum Translation: String { case none, front, back, left, right, frontLeft, frontRight, backLeft, backRight }
    public enum Rotation: String { case none, mouseUp, mouseDown, mouseLeft, mouseRight, mouseUpLeft, mouseUpRight, mouseDownLeft, mouseDownRight }
    public enum Interaction: String { case none, jump, attack, crouch, sprint }
    public let translation: Translation   // movement for this command; submit every frame while held, then stop
    public let rotation: Rotation          // view rotation for this command; submit every frame while held, then stop
    public let interaction: Interaction    // one-shot action for this command; submit once
    public init(translation: Translation = .none, rotation: Rotation = .none, interaction: Interaction = .none)
    public init(_ params: WorldControlParams)   // convenient bridge from the default control WorldControlParams (consistent rawValue)
}

// Unified error (§9)
public struct OysterSDKError: Error {
    public let code: Int
    public let raw: Any?                  // the SDK's internal raw error info; structure is not guaranteed stable, for logging/diagnostics only
    public var kind: OysterErrorKind      // typed view of the numeric code, for exhaustive switch (computed property)
    public init(code: Int, raw: Any? = nil)
    // Error code constants are in the nested OysterSDKError.Code (e.g. .notInitialized = 100001)
}

// Typed semantic view of error codes: local codes are named cases; server-side 4xxxxx/5xxxxx converge to .server(code:)
public enum OysterErrorKind: Equatable, Sendable {
    case notInitialized, tokenMissing, tokenInvalid, noActiveTravel, invalidState, sendCommandInDirecting
    case concurrentTravel, realtimeConnectFailed, realtimeJoinTimeout, firstFrameTimeout
    case channelNotReady, callbackTimeout, localNetwork, responseDecodeFailed
    case streamAutoEnd, proxyOrUnrecognized, featureGateDisabled
    case server(code: Int), unknown(code: Int)
}
  • Remarque : les rawValues des commandes sont en lower camelCase (par ex. front / mouseLeft / jump) ; les valeurs d'énumération ci-dessus font autorité.
  • Remarque : mode est extérieurement adventure (wander) / directing (histoire) / acting (jeu de rôle) ; la définition de OysterModeValue fait autorité.
  • Remarque : aspectRatio est une chaîne ouverte (actuellement 9:16 / 16:9, d'autres peuvent être ajoutées). L'analyser comme width:height et 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é

400000

Paramètres invalides (valeur d'énumération invalide, etc.)

Vérifier les paramètres de la requête ou la version du SDK

401010

Identifiant d'expérience (ticket) invalide ou expiré

Faire réémettre l'identifiant par le serveur

401011

Identifiant d'expérience (ticket) déjà utilisé

Identifiant à usage unique ; réémettre

403001

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

403002

État du monde non prêt

Attendre que le monde soit prêt avant de commencer

403003

L'API n'autorise que la clé API principale

Une clé temporaire ne peut pas être utilisée pour cette API

403004

Contenu d'entrée rejeté par la modération de contenu ; s'applique aux instructions textuelles de sendInstruct

Modifier l'entrée et réessayer

403007

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)

403008

Configuration de la capacité temporairement indisponible

Réessayer plus tard

404000

La ressource n'existe pas (propriété du monde/wander ou aucun artefact)

Vérifier l'ID / le statut

409000

La requête est en conflit avec l'état actuel de la ressource

Vérifier l'état de l'expérience

429001

Limite de concurrence atteinte pour cette spécification

Réessayer après la fin d'une session existante (ne pas confondre avec 500001)

429002

Capacité disponible insuffisante

Réessayer plus tard

500000

Erreur système interne

Réessayer plus tard / le signaler

500001

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é

100001

Appelé avant l'initialisation du SDK ; couvre également un initialize qui n'a pas pris effet parce que apiHost/model était vide ou invalide

Non (levé de manière synchrone, rejet de cet appel)

initialize d'abord, et vérifier que apiHost et model sont correctement définis

101001

Jeton d'authentification HTTP non injecté

Non

réessayer après updateToken

101002

Jeton d'authentification HTTP invalide / rejeté

Non

rééchanger le jeton puis réessayer updateToken

103001

Aucune expérience active actuellement

Non (rejet de cet appel)

createTravel + start d'abord

103002

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 / version

103003

Incompatibilité de mode (par ex. sendCommand appelé sur un monde non adventure)

Non (rejet de cet appel)

choisir la bonne API par mode, voir le tableau des capacités de la §2

103004

Création/démarrage simultané de l'expérience

Non (levé de manière synchrone)

sérialiser les appels, end d'abord l'ancienne session

105001

Échec de la connexion en temps réel

Oui

terminer et redémarrer

105002

Expiration du délai de connexion en temps réel

Oui

terminer et redémarrer

105003

Délai d'attente dépassé pour la première image vidéo

Oui

terminer et redémarrer

105004

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 running

105005

Délai d'attente du rappel (par défaut 30s)

Non

réessayer, et augmenter callbackTimeoutMs si nécessaire

105006

Aucun flux après la connexion ; le SDK termine automatiquement l'expérience

Oui

terminer et redémarrer

106001

Erreur de réseau local

Non

réessayable

106002

Échec de l'analyse de la réponse

dépend

mettre à niveau le SDK / signaler

106003

Aucun code d'erreur reconnaissable / code d'erreur de chaîne de proxy

Non

réessayable

108001

Désactivé à distance par le commutateur de fonctionnalité du serveur (arrêt complet ou version trop ancienne ; raison dans raw)

Oui

Suivre la raison dans raw ; guider l'utilisateur vers une mise à niveau lorsque la version est trop ancienne

Comment évaluer la fatalité : La fatalité n'est plus exposée sous forme de champ booléen (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 .statusChanged de events), 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.