Referencia de la API del SDK de HappyOyster para iOS

​

1. Conceptos básicos

​

2. Descripción general

​

3. Inicio rápido

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://help.aliyun.com/en/model-studio/base-url?spm=a2c4g.11186623.help-menu-2400256.d_0_0_4.171c56fftIRQRt&scm=20140722.H_3042998._.OR_help-T_cn~zh-V_1
    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()

​

4. Requisitos

​

5. Integración y autenticación

​

5.1 Integración y dependencias

# 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'

​

5.2 Modelo de autenticación

1. Token de autenticación HTTP (API Key temporal de Bailian): Su servidor lo obtiene mediante intercambio a través de la API de Bailian y lo entrega al cliente; se inyecta mediante updateToken(_:). Algunos servicios internos del SDK llaman directamente a la puerta de enlace de Bailian, portando este token para la autenticación; por lo tanto, debe ser una API Key temporal emitida por Bailian, no un token de su propio servicio de negocio. El SDK conserva únicamente el más reciente, no lo persiste ni lo renueva; tras su caducidad, debe volver a obtenerlo e inyectarlo.
2. Credencial de prueba de un solo uso ticket: Su servidor la obtiene mediante intercambio a través de la plataforma abierta get-travel-credential (prefijo tk_, válida durante 30 minutos, de un solo uso) y se utiliza como argumento de createTravel(ticket:); deja de ser válida cuando la experiencia finaliza (de forma normal o anómala) o caduca, y no puede reutilizarse.

1. Al llamar a APIs como engine.createTravel o travel.start, maneje el error y verifique los tipos de error de token caducado/inválido (101001 / 101002); después de inyectar un nuevo token, vuelva a llamar a la API correspondiente.
2. Al escuchar el evento .error de OysterTravelEvent, verifique los tipos de error de token caducado/inválido, vuelva a solicitar el token e inyéctelo.

​

6. Referencia de API

​

6.1 HappyOysterEngine

@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)
}

• Propósito: Inicializar el entorno de ejecución y registrar automáticamente el motor en tiempo real (no se requiere registro manual por parte del host).
• Parámetros: config.apiHost es la URL de la puerta de enlace de Bailian, no la de su servidor de negocio, y es obligatoria; en entornos de prelanzamiento o prueba, debe pasar explícitamente la puerta de enlace correspondiente; de lo contrario, las solicitudes fallarán (por ejemplo, 106001, dominio no resuelto). config.model es el nombre del modelo versionado habilitado para su cuenta y también es obligatorio sin valor predeterminado: Happy Oyster se divide en submodelos por modo, por lo que el SDK no puede inferir cuál utilizar. Ambos deben pertenecer a la misma cuenta y región que el token inyectado. Otros campos se detallan en la §8 OysterConfig.
• Un modelo sirve a un mode: cada modelo por modo tiene su propia ruta de puerta de enlace, por lo que una sola llamada a initialize solo sirve mundos de ese único mode. Si su aplicación ofrece mundos en varios modos, simplemente llame a initialize() nuevamente con el modelo correspondiente antes de entrar a un mundo de un modo diferente; mientras está inactivo, prevalece la configuración más reciente, no se requiere cleanup() y se conserva el token inyectado; mientras un Travel está en curso, la llamada se ignora, así que invoque end() primero. Un modelo que no coincida con el mode del mundo es rechazado por la puerta de enlace con AccessDenied, normalizado a 106003.
• Cuándo usar: Llamar una vez antes de createTravel, lo antes posible después del inicio de la aplicación.
• Devuelve: Bool — indica si la config que usted proporcionó surtió efecto. Es false en dos casos: la configuración no es válida (apiHost / model en blanco o sin formar una URL de puerta de enlace válida), o hay un Travel en curso, por lo que se ignoró la llamada. En ambos casos, el entorno de ejecución permanece sin cambios.
• Nota: Mientras está inactivo, llamarlo nuevamente reconfigura el entorno de ejecución con la nueva configuración (cambiar apiHost / model no requiere cleanup(), y se conserva el token inyectado); es una operación nula con solo una advertencia mientras un Travel está en curso, así que invoque end() primero. Una configuración no válida deja el entorno de ejecución sin cambios. No utilice isReady para determinar si una re-initialize tuvo éxito: si fue rechazada, la configuración anterior sigue vigente y isReady permanece true; isReady responde a "¿está el motor usable ahora?", mientras que el valor de retorno responde a "¿surtió efecto la configuración que acabo de pasar?".

• Propósito: Configurar y tomar el control del registro interno del SDK, imprimiéndolo en su propio módulo de registro. Proporciona setMinimumLevel(_:) para establecer el nivel y setHandler(_:) para salida personalizada (véase el ejemplo de §3).

• Propósito: Inyectar / actualizar el token de autenticación HTTP (clave de API temporal de Bailian, §5.2).
• Cuándo usarlo: Después de initialize, puede llamarse en cualquier momento; vuelva a intercambiar y llame nuevamente después de que el token caduque o tras recibir un error relacionado con la autenticación (101001 / 101002).
• Nota: Es una operación nula con una advertencia cuando no se ha initialized.

• Propósito: Crear un único identificador de sesión con un ticket de un solo uso.
• Parámetro: ticket es una credencial de un solo uso; una vez creada, se considera ocupada para esta experiencia.
• Cuándo usarlo: Llame antes de cada nueva experiencia; el identificador devuelto aún no está conectado y debe llamar a travel.start() después. El video se toma del identificador devuelto (véase §6.2).
• Nota (throws sincrónico): lanza 100001 si no se ha ejecutado initialize; lanza 103004 si se llama nuevamente antes de que el Travel anterior haya ejecutado end() (cada motor permite solo un Travel activo a la vez).

• Propósito: Liberar recursos del SDK (finalizar el travel activo, configuración de tiempo de ejecución, token).
• Cuándo usar: Al salir completamente del SDK o necesitar cambiar la config.
• Nota: async — internamente termina determinísticamente el travel activo actual mediante end() primero, luego desmantela el entorno de ejecución, sin dejar operaciones fire-and-forget. Después de la liberación, puede ejecutar initialize nuevamente.

​

6.2 OysterTravel

@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
}

• Propósito: El punto de entrada de renderizado para la imagen remota — "el SDK proporciona la vista, el host la coloca". Para UIKit, tome travel.videoView; para SwiftUI, use OysterVideoView(travel:).
• Cuándo usarlo: Disponible tan pronto como se crea el identificador (el acceso repetido devuelve la misma vista); móntela en cualquier jerarquía y, una vez que el motor esté listo, se renderiza automáticamente. Montarla antes o después de start() funciona en ambos casos, sin pantalla negra.
• Nota: Cuando finaliza la sesión, el SDK libera automáticamente el enlace de renderizado; elimine la vista de la jerarquía según sea necesario.

• Propósito: events es el flujo push de cambios de estado + errores; status es el estado externo actual observable; isEnded es un indicador legible sincrónicamente para el estado terminal.
• Cuándo usarlo: Se recomienda comenzar a consumir events antes de start(), para evitar perder los primeros estados.
• Nota: Cada acceso a events devuelve un flujo independiente, compatible con múltiples suscripciones; cancelar la suscripción equivale a finalizar la iteración for await (o destruir la Task retenida). En SwiftUI, puede observar directamente status con @StateObject/@ObservedObject (los errores siguen llegando a través de events). Consulte la §7.

• Propósito: Usar el ticket capturado en el momento de la creación para intercambiarlo por la configuración de travel + unión RTC y conectarse para reproducir. En caso de éxito, el SDK establece automáticamente la conexión en tiempo real y comienza el sondeo de estado interno, exponiendo el estado a través de events.
• Parámetro: maxExperienceTimeSec (opcional) — solicita la duración máxima (en segundos) de esta experiencia de aventura. El valor se envía al servidor tal cual; los valores permitidos, la duración efectiva real y el momento de finalización automática son decididos por el servidor; el SDK no realiza validación local. Pasar nil (o llamar a start() sin parámetros) utiliza la duración predeterminada del servidor. El modo Dirección ignora este parámetro. Cuando se agota el tiempo, el servidor finaliza la experiencia y el host recibe el estado terminal ended a través de events (igual que una finalización del lado del servidor, consulte la §7).
• Devuelve: OysterStartTravelData (mode / version / encryptedTravelId, etc., véase §8), que determina la interfaz de usuario de interacción.
• Errores: 401010/401011 (credencial no válida o ya utilizada), 403002 (mundo no listo), 403007 (especificación de servicio no habilitada, por ejemplo, actuación), 429001/429002 (límite de concurrencia / capacidad agotada), 500001 (fallo de recurso/servidor), 103004 (inicio concurrente).
• El mode del mundo del ticket debe coincidir con el model pasado a initialize (responsabilidad del llamante): con modelos por modo, cada modelo es su propia ruta de puerta de enlace, y start() envía el ticket a la ruta del modelo actualmente inicializado****. El SDK no verifica ni puede verificar esto por usted de antemano — mode se entrega mediante la respuesta a esta misma llamada de start() (OysterStartTravelData.mode); antes de la llamada, el SDK solo posee un ticket opaco y un nombre de modelo, sin ningún modo contra el cual comparar, e inferir el modo a partir del nombre del modelo sería adivinar un esquema de nomenclatura propiedad del servidor, lo cual el SDK no hace. Por lo tanto: antes de entrar en un mundo de un modo diferente, llame nuevamente a initialize() con el modelo correspondiente (mientras está inactivo, prevalece la configuración más reciente — no se requiere cleanup() y se conserva el token; mientras un Travel está en curso, la llamada se ignora, así que ejecute end() primero). En caso de discrepancia, esta llamada de start() falla en la puerta de enlace; al diagnosticar, verifique primero que el model actual y el mode del mundo del ticket pertenezcan juntos, luego consulte los códigos de error de credenciales anteriores.
• Nota (finalización automática por ausencia de flujo): El servidor envía un "tiempo de espera sin flujo" (predeterminado ~30 s). Si, tras conectarse, no se recibe ningún flujo dentro de esa duración (nunca alcanza running), el SDK finaliza automáticamente la experiencia, transiciona a failed y expone 105006 mediante .error de events (fatal; manéjelo regresando a la pantalla previa al inicio, sin necesidad de medir el tiempo usted mismo).

• Propósito: Pausar / reanudar la experiencia (idempotente).
• Cuándo usarlo: Soportado por mundos de directing y acting; no soportado por adventure. Use el mode devuelto por start() para decidir de antemano si mostrar un botón de pausa. pause requiere que el estado actual sea running; resume requiere paused.
• Errores: 103001 (sin experiencia activa), 103002 (estado/versión no permitidos), 103003 (discordancia de modo).

• Propósito: Rebobinar a los segundos especificados. En caso de éxito, el SDK se reincorpora automáticamente con el rtcConfig original y reanuda la reproducción.
• Cuándo usarlo: Solo puede iniciarse en el estado paused, y solo por mundos dedirecting — acting y adventure no admiten rebobinado, así que oculte el punto de entrada de rebobinado en esos modos y no lo llame.
• Errores: 103001, 103002.

• Propósito: Finalizar la experiencia (idempotente, puede llamarse repetidamente). Tras una llamada exitosa o una salida anómala, el SDK desconecta automáticamente la conexión en tiempo real, detiene el sondeo y libera todos los recursos de la sesión; el ticket se invalida simultáneamente y el identificador entra en un estado terminal.
• Cuándo usar / Nota: Ya sea que el usuario salga activamente o que la experiencia finalice pasivamente (caducidad del temporizador, recepción de .ended/.failed, destrucción de la página), asegúrese de que se ejecute una única llamada a end(); de lo contrario, los recursos remotos podrían no liberarse oportunamente. Se recomienda canalizar todas las rutas de salida hacia el mismo método de limpieza idempotente.

• Propósito: Enviar una instrucción de texto para impulsar la trama.
• Cuándo usarlo: Modo dirección; se envía directamente cuando está en running, se almacena en caché cuando está en paused y se reenvía con el primer fotograma tras reanudar a running mediante reconexión.
• Errores: 103001, 103002, 103003 (llamado en modo aventura), 403004 (moderación de contenido), 404000 (travel no encontrado).

• sendCommand: Envía comandos de control de dirección/vista/acción (consulte la §8 OysterAdventureCommand; fire-and-forget, sin retorno, no lanza excepciones). Efectivo únicamente en modo aventura cuando está running. La entrada externa puede ser de alta frecuencia en cada fotograma, y el SDK aplica limitación internamente (muestreo de última victoria, fusión de fotogramas a la tasa de línea RTC); el host no necesita aplicar limitación por sí mismo. Tenga en cuenta que la respuesta del servidor a los comandos tiene latencia inherente, por lo que el momento efectivo real no es fijo.
• flushCommands: Llamado en el momento de "liberación de tecla / liberación de entrada", reenviando inmediatamente el último comando ya en espera en la cola; es una operación nula pura cuando no hay ningún comando pendiente, sin generar ningún comando nuevo.
• Errores (todos expuestos a través del .error de events, no mediante throws): sin experiencia activa 103001; llamado en modo dirección 103003; canal en tiempo real no listo / envío fallido 105004.

• Propósito: Liberar / restaurar temporalmente la ocupación del SDK sobre la captura del micrófono local.
• Cuándo usarlo: Cuando algo como el reconocimiento de voz necesita acceso exclusivo al micrófono, ejecute pause primero y resume después.

​

7. Eventos y estado

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)
}

• SwiftUI: OysterTravel es un ObservableObject; use directamente @StateObject/@ObservedObject para observar status y controlar la interfaz de usuario; los errores siguen proviniendo de events.
• Imperativo / UIKit: en un Task, use for await event in travel.events { ... } y switch sobre .statusChanged / .error; cancele el Task retenido al finalizar.

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()

​

8. Modelos de datos

// 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)
}

​

9. Códigos de error

​

Códigos de error del servidor (comunes)

​

Códigos de error del cliente local

• Errores que finalizan automáticamente la sesión (por ejemplo, 105001/105002/105003/105006/108001): el host detecta esto a partir del estado terminal de la máquina de estados (status → failed, expuesto mediante .statusChanged de events) y regresa a la pantalla previa a "iniciar experiencia" en consecuencia, sin necesidad de evaluar por sí mismo la gravedad del error.
• Errores de rechazo de llamada (100001/103001/103002/103003/103004): se lanzan sincrónicamente / la llamada se rechaza cuando usted llama activamente; no terminan la sesión.
• Otros errores no fatales (por ejemplo, 101001/101002/105005/106001/106003): no terminan la sesión; reintente según lo sugerido o continúe después de volver a inyectar el token.