Skip to main content

Guide d'intégration du SDK iOS HappyOyster

Il s'agit du parcours d'intégration le plus court pour les développeurs iOS : de l'initialisation à l'affichage de l'image à l'écran, en passant par l'envoi d'instructions de contrôle, jusqu'à la fin de l'expérience. Pour les signatures complètes des méthodes, les champs et les codes d'erreur, reportez-vous à la Référence de l'API du SDK iOS.

Pour les signatures complètes des méthodes, les champs et les codes d'erreur, reportez-vous à la Référence de l'API du SDK iOS.

0. Ce que vous allez construire

Une boucle minimale de bout en bout : « entrer dans un monde → expérience vidéo en temps réel → interagir → terminer ». Les points d'entrée d'exécution sont le global HappyOysterEngine.shared et le handle de session à usage unique OysterTravel qu'il crée.
OysterStream.register()
HappyOysterEngine.shared: initialize → updateToken → createTravel
OysterTravel:             videoView / events → start → sendInstruct / sendCommand → end

1. Prérequis

Élément

Exigence

Système d'exploitation minimum

iOS 15.0+

Langage

Swift (async/await)

Threading

Les API publiques sont @MainActor ; appelez-les sur le thread principal

Importation

import HappyOysterSDK (point d'entrée agrégé, incluant déjà @_exported Core + World)

La communication en temps réel (AliRTC) est encapsulée dans le SDK ; les intégrateurs n'accèdent jamais directement à l'API RTC.

1.1 Ajouter le SDK via CocoaPods

Le SDK est distribué sous forme de binaire précompilé (xcframework) via des sous-spécifications CocoaPods, publiées sur le Trunk public de CocoaPods — référencez-le directement par version, aucun fichier podspec local n'est nécessaire.
# HappyOysterSDK / AliVCSDK_ARTC are both published on the public CocoaPods source.
source 'https://cdn.cocoapods.org/'

platform :ios, '15.0'
use_frameworks!

target 'YourApp' do
  # Aggregate entry point (Core + World); `import HappyOysterSDK` and you're set.
  pod 'HappyOysterSDK'
  # Optional default UI components (video view, control HUD).
  pod 'HappyOysterSDK/UI'
  # Video stream + AliRTC engine adapter (already depends on Stream; no need to declare it separately).
  pod 'HappyOysterSDK/StreamAliRTC'

  # RTC vendor binary: weak-linked by the SDK, not redistributed with it — bring your own (public CocoaPods source).
  pod 'AliVCSDK_ARTC', '7.11.0'
end
Exécutez ensuite pod install et ouvrez le fichier .xcworkspace généré (et non le .xcodeproj).
AliVCSDK_ARTCest requis chaque fois que vous intégrez HappyOysterSDK/StreamAliRTC : s'il est absent, le SDK bascule silencieusement vers Loopback — il se connecte toujours et atteint l'état running, mais affiche un écran noir sans erreur.

2. Deux types d'identifiants (à comprendre en premier pour éviter les pièges)

Le SDK n'obtient ni ne rafraîchit aucune identification par lui-même ; vous devez toutes les injecter :

Identifiant

Source

Objectif

Mode d'injection

Jeton d'authentification HTTP

Votre application le récupère depuis votre propre backend

Authentification générale pour les appels du SDK à la passerelle (longue durée de vie, nécessite un renouvellement)

updateToken(_:) ; le SDK ne conserve que le dernier

Ticket à usage unique

Émis par votre serveur après échange via l'API d'identification Travel

Utilisé pour une seule expérience, invalidé immédiatement après utilisation

Passé comme argument createTravel(ticket:)

Les deux ne sont pas interchangeables : updateToken sert à l'authentification générale, tandis que ticket est un identifiant de connexion à usage unique. Les clés AK / de signature existent uniquement sur votre serveur et ne sont jamais exposées au client.

3. Étapes d'intégration

Cycle de vie : enregistrer le moteur de streaming → initialiser → injecter le jeton → créer la session → attacher la vidéo + s'abonner aux événements → démarrer → interagir → terminer.

Étape 1 : Enregistrer le moteur de streaming

Le point d'entrée unique pour le rendu vidéo. Appelez-le une fois au lancement de l'application ; les appels répétés sont sûrs.
import HappyOysterSDK
import HappyOysterStream

OysterStream.register()

Étape 2 : Initialiser le SDK

Vous devez initialiser une fois avant d'appeler toute autre API. Pour changer de passerelle ou de modèle, appelez-la simplement à nouveau — au repos, la dernière configuration l'emporte et le jeton injecté est conservé ; l'appel est ignoré uniquement lorsqu'un travel est en cours, alors appelez d'abord end().
let engine = HappyOysterEngine.shared
engine.initialize(config: OysterConfig(
    apiHost: "[workspace-id].[region].maas.aliyuncs.com",  // Model Studio gateway host
    model: "happyoyster-1.0-adventure"                     // Versioned model name enabled for your account, required
))
// Optional: override the log level / signalling callback timeout
// OysterConfig(apiHost: "…", model: "…", logLevel: .debug, callbackTimeoutMs: 30_000)

// Both apiHost and model are required with no default: Happy Oyster is split into
// per-mode sub-models. See the Happy Oyster model documentation for available names
// and versions; they must match the account and region of your token.

Étape 3 : Injecter le jeton d'authentification HTTP (push)

Récupérez une clé API Model Studio temporaire depuis votre propre backend et injectez-la. Réinjectez-la après son expiration.
let token = await fetchTokenFromYourBackend()
engine.updateToken(token)

Étape 4 : Créer le handle de session

Créez un OysterTravel à partir d'un ticket à usage unique. Rien n'est encore connecté, mais la vue vidéo est déjà disponible.
let travel = try engine.createTravel(ticket: ticket)

Étape 5 : Attacher la vue vidéo et s'abonner aux événements

Le SDK fournit la vue, c'est à l'hôte de la placer. Abonnez-vous avant start() afin de ne pas manquer les premiers changements d'état.
containerView.addSubview(travel.videoView)     // SwiftUI: OysterVideoView(travel:)

let eventTask = Task {
    for await event in travel.events {
        switch event {
        case .statusChanged(let status): render(status)   // running / paused / ended / failed…
        case .error(let error):          handle(error)    // error.code / error.kind — see the API Reference
        }
    }
}

Étape 6 : Démarrer l'expérience

Connectez-vous et commencez à jouer. Le SDK maintient alors automatiquement la connexion en temps réel et le polling d'état, exposant l'état via events.
let data = try await travel.start()
// data.encryptedTravelId —— identifier of this experience, used for diagnostics / server reconciliation
// data.encryptedWorldId  —— identifier of the world you entered
// data.mode              —— adventure / directing / acting, determines the interaction UI
// data.aspectRatio       —— "9:16" / "16:9"; set for acting only, use it to pick the player orientation
start(maxExperienceTimeSec:) s'applique uniquement à adventure ; directing et acting ignorent ce paramètre.
Le mode du monde pour ce travel doit correspondre au model que vous avez transmis à initialize à l'étape 2. Avec des modèles par mode (happyoyster-1.0-adventure / -directing / -acting), chaque modèle est sa propre route d'application de passerelle, donc un seul initialize dessert des mondes d'un seul mode ; le ticket a été émis par votre serveur sous la route du mode de ce monde, et start() l'envoie vers la route du model actuellement configuré — une non-concordance entraîne un échec à cette étape. Avant d'entrer dans un monde d'un mode différent, appelez à nouveau initialize() avec le modèle correspondant — pas besoin de cleanup() ni de réappeler updateToken() :
HappyOysterEngine.shared.initialize(config: OysterConfig(
    apiHost: "…", model: "happyoyster-1.0-acting"))   // the model for this world's mode
Au repos (aucun travel en cours), la dernière configuration l'emporte et le jeton injecté est conservé. Le SDK ne peut pas vérifier la correspondance modèle/monde pour vous au préalable : le mode n'arrive que dans la réponse de cette étape (data.mode) ; avant l'appel, le SDK ne détient rien d'autre qu'un ticket opaque et un nom de modèle. Les applications proposant un seul mode ne sont pas affectées et s'initialisent une seule fois.
Pendant qu'un travel est en cours, un appel répété à initialize() est ignoré avec un avertissement — appelez d'abord end().

Étape 7 : Interaction en temps réel (choisir selon le mode)

if data.mode == .adventure {
    // Adventure: direction/view/action control (fire-and-forget; never throws, failures come via events)
    travel.sendCommand(OysterAdventureCommand(translation: .front, interaction: .jump))
} else {
    // Directing and acting: text instructions
    _ = try await travel.sendInstruct(content: "Pan to the castle; the hero starts running")
}
sendCommand applique en interne une limitation sur un cycle « dernier gagnant » de 42ms (24FPS), permettant ainsi à l'hôte de l'appeler à haute fréquence :
  • Les actions ponctuelles telles que sauter, attaquer, s'accroupir et sprinter sont envoyées une seule fois.
  • Le mouvement et la rotation de la vue sont envoyés en continu tant qu'ils sont maintenus, et vous arrêtez simplement d'appeler lors du relâchement.
  • Vous n'avez pas besoin d'envoyer none ou d'appeler flushCommands() lors du relâchement ; le SDK ne génère jamais de commande d'arrêt par lui-même, et le serveur termine l'action dès que le canal temps réel devient silencieux.

Étape 8 : Pause / Reprise / Rembobinage (dépendant du mode)

_ = try await travel.pause()           // supported by directing and acting
_ = try await travel.resume()
_ = try await travel.rewind(toSec: 10) // directing only
adventure ne prend en charge none de ces fonctions ; acting prend en charge pause/reprise mais pas le rembobinage — masquez le point d'entrée de rembobinage dans ces modes. Les appels non concordants sont rejetés localement par le SDK (103003 / 103002).

Étape 9 : Terminer l'expérience

Déconnecte, arrête le polling et libère toutes les ressources de la session ; le ticket est consommé. Idempotent — chaque chemin de sortie doit y aboutir.
_ = try? await travel.end()
eventTask.cancel()
Appelez await engine.cleanup() lors du démantèlement du SDK ou du changement de passerelle.

4. Exemple complet (SwiftUI)

import SwiftUI
import HappyOysterSDK
import HappyOysterStream

@main
struct MyApp: App {
    init() {
        OysterStream.register()                                     // Step 1
        HappyOysterEngine.shared.initialize(config: OysterConfig(   // Step 2
            apiHost: "[workspace-id].[region].maas.aliyuncs.com",
            model: "happyoyster-1.0-adventure"
        ))
    }
    var body: some Scene { WindowGroup { TravelScreen() } }
}

struct TravelScreen: View {
    @State private var travel: OysterTravel?
    @State private var eventTask: Task<Void, Never>?

    var body: some View {
        ZStack {
            if let travel {
                OysterVideoView(travel: travel)      // Step 5: SDK provides the view, host places it
                    .ignoresSafeArea()
            } else {
                Color.black.ignoresSafeArea()
            }
        }
        .task { await start() }
        .onDisappear { Task { await end() } }
    }

    @MainActor private func start() async {
        let engine = HappyOysterEngine.shared
        engine.updateToken(await fetchToken())                      // Step 3
        do {
            let ticket = await fetchTicket()                        // issued by your server
            let travel = try engine.createTravel(ticket: ticket)    // Step 4
            self.travel = travel

            eventTask = Task {                                      // Step 5
                for await event in travel.events {
                    switch event {
                    case .statusChanged(let status): print("status: \(status)")
                    case .error(let error):          print("error: \(error.code)")
                    }
                }
            }

            let data = try await travel.start()                     // Step 6
            if data.mode == .adventure {                            // Step 7
                travel.sendCommand(OysterAdventureCommand(translation: .front))
            } else {
                _ = try await travel.sendInstruct(content: "Suddenly it starts to pour")
            }
        } catch let error as OysterSDKError {
            // Handle start failure (see the error code table in the API Reference)
        } catch {}
    }

    @MainActor private func end() async {
        _ = try? await travel?.end()                                // Step 9
        eventTask?.cancel()
        travel = nil
    }
}

5. Bonnes pratiques

  • Cycle de vie : Appelez OysterStream.register() + initialize() aussi tôt que possible au lancement de l'application, une fois chacun globalement ; appelez toujours end() lorsque vous quittez la page d'expérience pour garantir la libération de la connexion temps réel et des ressources. OysterTravel est à usage unique — créez-en un nouveau via createTravel après qu'il ait atteint un état terminal.
  • Renouvellement du jeton : Assurez-vous que le jeton HTTP est à jour avant de commencer une expérience ; lorsque vous recevez un rappel d'erreur lié à l'authentification, récupérez un nouveau jeton et appelez updateToken (non fatal, ne met pas fin à l'expérience).
  • Gravité des erreurs : Pour les erreurs fatales, le SDK termine automatiquement l'expérience en cours, les expose via le .error de events, et passe à l'état terminal failed ; vous devriez revenir à l'écran affiché avant le « démarrage de l'expérience ». Les erreurs non fatales sont seulement exposées et peuvent faire l'objet d'une nouvelle tentative. Consultez le tableau complet des codes d'erreur dans la Référence de l'API.
  • Adaptation au mode : Les modes directing et acting affichent une zone de saisie de texte (sendInstruct) ; le mode adventure affiche des widgets de contrôle (sendCommand). Seul le mode directing affiche un point d'entrée de rembobinage. Pour les mondes acting, choisissez l'orientation du lecteur à partir de aspectRatio (portrait 9:16 par défaut).

6. Étapes suivantes