HappyOyster iOS SDK API Reference

​

1. Core Concepts

​

2. Overview

​

3. Quick Start

import HappyOysterSDK

// 1) Initialize (as early as possible after app launch, once before createTravel)
let engine = HappyOysterEngine.shared
engine.initialize(config: OysterConfig(
    apiHost: "dashscope-intl.aliyuncs.com",// API Host (dashscope-intl.aliyuncs.com)
    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 (QwenCloud 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. Requirements

​

5. Integration and Authentication

​

5.1 Integration and Dependencies

# 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 Authentication Model

1. HTTP auth token (QwenCloud temporary API Key): Your server exchanges it via the QwenCloud API and delivers it down; it is injected through updateToken(_:). Some internal SDK services call the QwenCloud gateway directly, carrying this token for authentication — therefore it must be a temporary API Key issued by QwenCloud, not a token from your own business service. The SDK keeps only the latest one, does not persist or refresh it; after it expires, you re-exchange and re-inject it.
2. One-time trial credential ticket: Your server exchanges it via the open platform get-travel-credential (prefix tk_, valid for 30 minutes, single-use), used as the createTravel(ticket:) argument; it becomes invalid once the experience ends (normally or abnormally) or expires, and cannot be reused.

1. When calling APIs such as engine.createTravel or travel.start, handle the error and check for the token-expired/invalid error types (101001 / 101002); after injecting a new token, re-call the corresponding API.
2. When listening to the .error event of OysterTravelEvent, check for the token-expired/invalid error types, re-request the token, and inject it.

​

6. API Reference

​

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

• Purpose: Initialize the runtime and automatically register the real-time engine (no manual registration needed by the host).
• Parameters: config.apiHost is the QwenCloud gateway URL, not your business server, and is required; in pre-release/trial environments you must explicitly pass the corresponding gateway, otherwise requests fail (e.g. 106001, domain cannot be resolved). config.model is the versioned model name enabled for your account and is likewise required with no default — Happy Oyster is split into per-mode sub-models, so the SDK cannot infer which one to use. Both must belong to the same account as the injected token. Other fields are in §8 OysterConfig.
• One model serves one mode: each per-mode model is its own gateway route, so a single initialize only serves worlds of that one mode. If your app offers worlds in several modes, just call initialize() again with the matching model before entering a world of a different mode — while idle the latest config wins, no cleanup() is needed and the injected token is kept; while a Travel is in flight the call is ignored, so end() it first. A model that does not match the world's mode is rejected by the gateway with AccessDenied, normalized to 106003.
• When to use: Call once before createTravel, as early as possible after app launch.
• Returns: Bool — whether the config you passed took effect. It is false in two cases: the config is invalid (apiHost / model blank or not forming a valid gateway URL), or a Travel is in flight so the call was ignored. In both cases the runtime is left unchanged.
• Note: While idle, calling it again re-configures the runtime with the new config (switching apiHost / model needs no cleanup(), and the injected token is kept); it is a no-op with a warning only while a Travel is in flight, so end() it first. An invalid config leaves the runtime unchanged. Do not use isReady to tell whether a re-initialize succeeded — if it was rejected the previous config is still in effect and isReady remains true; isReady answers "is the engine usable now", the return value answers "did the config I just passed take effect".

• Purpose: Configure and take over the SDK's internal logging, printing it into your own logging module. Provides setMinimumLevel(_:) to set the level and setHandler(_:) for custom output (see the §3 example).

• Purpose: Inject / update the HTTP auth token (QwenCloud temporary API Key, §5.2).
• When to use: After initialize, callable at any time; re-exchange and call again after the token expires or after receiving an auth-related error (101001 / 101002).
• Note: A no-op with a warning when not initialized.

• Purpose: Create a single session handle with a one-time ticket.
• Parameter: ticket is a one-time credential; once created, it is considered occupied for this experience.
• When to use: Call before each new experience; the returned handle is not yet connected and you must call travel.start() afterwards. The video is taken from the returned handle (see §6.2).
• Note (synchronous throws): throws 100001 if not initialized; throws 103004 if called again before the previous Travel has end()ed (each engine allows only one active Travel at a time).

• Purpose: Release SDK resources (end the active travel, runtime config, token).
• When to use: When fully exiting the SDK or needing to change the config.
• Note: async — internally it deterministically end()s the current active travel first, then tears down the runtime, leaving no fire-and-forget. After release you can initialize again.

​

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
}

• Purpose: The rendering entry for the remote picture — "the SDK provides the view, the host places it". For UIKit, take travel.videoView; for SwiftUI, use OysterVideoView(travel:).
• When to use: Available as soon as the handle is created (repeated access returns the same view); mount it into any hierarchy, and once the engine is ready it renders automatically. Mounting before or after start() both work, with no black screen.
• Note: When the session ends, the SDK automatically releases the rendering binding; remove the view from the hierarchy as needed.

• Purpose: events is the push stream of status changes + errors; status is the observable current external status; isEnded is a synchronously readable flag for the terminal state.
• When to use: It is recommended to start consuming events before start(), to avoid missing early statuses.
• Note: Each access to events returns an independent stream, supporting multi-subscription; unsubscribing = ending the for await iteration (or destroying the held Task). In SwiftUI you can directly observe status with @StateObject/@ObservedObject (errors still come through events). See §7.

• Purpose: Use the ticket captured at create time to exchange for travel + RTC join configuration and connect to play. On success the SDK automatically establishes the real-time connection and begins internal status polling, surfacing status through events.
• Parameter: maxExperienceTimeSec (optional) — requests the maximum duration (in seconds) of this adventure experience. The value is sent to the server as-is; the allowed values, the actual effective duration, and the auto-end timing are all decided by the server — the SDK performs no local validation. Passing nil (or calling the parameterless start()) uses the server's default duration. Directing mode ignores this parameter. When the time is up, the server ends the experience and the host receives the ended terminal state via events (same as a server-side end, see §7).
• Returns: OysterStartTravelData (mode / version / encryptedTravelId, etc., see §8), which determines the interaction UI.
• Errors: 401010/401011 (credential invalid/used), 403002 (world not ready), 403007 (service specification not enabled, e.g. acting), 429001/429002 (concurrency limit / capacity exhausted), 500001 (resource/server failure), 103004 (concurrent start).
• The ticket's world mode must match the model passed to initialize (caller's responsibility): with per-mode models, each model is its own gateway route, and start() sends the ticket to the route of the currently initialized model. The SDK does not and cannot verify this for you beforehand — mode is delivered by the response to this very start() call (OysterStartTravelData.mode); before the call the SDK holds only an opaque ticket and a model name, with no mode to compare against, and inferring the mode from the model name would be guessing at a server-owned naming scheme, which the SDK does not do. So: before entering a world of a different mode, call initialize() again with the matching model (while idle the latest config wins — no cleanup() needed and the token is kept; while a Travel is in flight the call is ignored, so end() it first). On a mismatch this start() fails at the gateway; when diagnosing, first check that the current model and the mode of the ticket's world belong together, then consult the credential error codes above.
• Note (auto-end on no stream): The server sends a "no-stream timeout" (default ~30s). If, after connecting, no stream is received within that duration (it never reaches running), the SDK automatically ends the experience, transitions to failed, and surfaces 105006 via the .error of events (fatal; handle by returning to the pre-start screen, no need to time it yourself).

• Purpose: Pause / resume the experience (idempotent).
• When to use: Supported by directing and acting worlds; not supported by adventure. Use the mode returned by start() to decide in advance whether to show a pause button. pause requires the current state to be running; resume requires paused.
• Errors: 103001 (no active experience), 103002 (state/version not allowed), 103003 (mode mismatch).

• Purpose: Rewind to the specified seconds. On success the SDK automatically rejoins with the original rtcConfig and returns to playback.
• When to use: Can only be initiated in the paused state, and only by directing worlds — acting and adventure do not support rewind, so hide the rewind entry point in those modes and do not call it.
• Errors: 103001, 103002.

• Purpose: End the experience (idempotent, can be called repeatedly). After a successful call or an abnormal exit, the SDK automatically disconnects the real-time connection, stops polling, and releases all session resources; the ticket is invalidated at the same time, and the handle enters a terminal state.
• When to use / Note: Whether the user exits actively or the experience ends passively (timer expiry, receiving .ended/.failed, page destruction), make sure a single end() is reached, otherwise remote resources may not be released promptly. It is recommended to funnel all exit paths into the same idempotent cleanup method.

• Purpose: Send a text instruction to drive the storyline.
• When to use: Directing mode; sent directly when running, cached when paused and resent with the first frame after resuming back to running via reconnect.
• Errors: 103001, 103002, 103003 (called in adventure mode), 403004 (content moderation), 404000 (travel not found).

• sendCommand: Send direction/view/action control commands (see §8 OysterAdventureCommand; fire-and-forget, no return, does not throw). Effective only in adventure mode when running. External input can be high-frequency every frame, and the SDK throttles internally (latest-wins sampling, frame merging at RTC line rate); the host does not need to throttle itself. Note that the server's response to commands itself has latency, so the actual effective time is not fixed.
• flushCommands: Called at the moment of "key release / input release", immediately resending the last command already waiting in the queue; a pure no-op when there is no pending command, generating no new command.
• Errors (all surfaced via the .error of events, not throws): no active experience 103001; called in directing mode 103003; real-time channel not ready / send failed 105004.

• Purpose: Temporarily release / restore the SDK's occupation of local microphone capture.
• When to use: When something like speech recognition needs exclusive microphone access, pause first and resume afterwards.

​

7. Events and Status

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 is an ObservableObject; directly use @StateObject/@ObservedObject to observe status and drive the UI; errors still come from events.
• Imperative / UIKit: in a Task, for await event in travel.events { ... }, and switch over .statusChanged / .error; cancel the held Task when done.

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. Data Models

// Configuration
public struct OysterConfig: Sendable {
    public let apiHost: String             // QwenCloud 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. Error Codes

​

Server Error Codes (common)

​

Client-Local Error Codes

• Errors that auto-terminate the session (e.g. 105001/105002/105003/105006/108001): the host perceives this from the state-machine terminal state (status → failed, surfaced via the .statusChanged of events), and returns to the screen before "start experience" accordingly, with no need to judge fatality itself.
• Call-rejection errors (100001/103001/103002/103003/103004): thrown synchronously / the call is rejected when you actively call; they do not terminate the session.
• Other non-fatal errors (e.g. 101001/101002/105005/106001/106003): they do not terminate the session; retry as suggested or continue after re-injecting the token.