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.
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.
1. Prérequis
Élément | Exigence |
|---|---|
Système d'exploitation minimum | iOS 15.0+ |
Langage | Swift ( |
Threading | Les API publiques sont |
Importation |
|
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.
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) |
|
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 |
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.
É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().
É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.
É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.
É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.
É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.
start(maxExperienceTimeSec:) s'applique uniquement à adventure ; directing et acting ignorent ce paramètre.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() :
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.
initialize() est ignoré avec un avertissement — appelez d'abord end().Étape 7 : Interaction en temps réel (choisir selon le mode)
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
noneou d'appelerflushCommands()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)
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.
await engine.cleanup() lors du démantèlement du SDK ou du changement de passerelle.4. Exemple complet (SwiftUI)
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 toujoursend()lorsque vous quittez la page d'expérience pour garantir la libération de la connexion temps réel et des ressources.OysterTravelest à usage unique — créez-en un nouveau viacreateTravelaprè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
.errordeevents, et passe à l'état terminalfailed; 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 deaspectRatio(portrait9:16par défaut).
6. Étapes suivantes
- API complète (
pause()/resume()/rewind(toSec:), modèles de données, codes d'erreur) → Référence de l'API du SDK iOS