Skip to main content

Referência da API do SDK iOS do HappyOyster

O ponto de entrada do SDK iOS do HappyOyster é o singleton de nível de processo HappyOysterEngine.shared. Os métodos de negócios são todos async throws, lançando OysterSDKError em caso de falha. Uma única experiência é conduzida por um identificador OysterTravel, abrangendo três modos — aventura, direção e atuação — tanto no UIKit quanto no SwiftUI.

  • Este documento é a descrição de recursos externos + referência de interface para o Happy Oyster iOS SDK: ele explica os parâmetros, tempo, uso e exemplos curtos de cada tipo e método público, um por um.
  • Para o fluxo de integração completo (configuração do projeto, configuração de dependências, coordenação do lado do servidor, execução de ponta a ponta), consulte a documentação do projeto de exemplo; não é repetido aqui.

1. Conceitos principais

Primeiro, alguns termos para facilitar a leitura do restante.

Conceito

Descrição

token

Token de autenticação HTTP (chave de API temporária do Bailian). Seu servidor a troca por meio da API do Bailian e a entrega; ela é injetada através de updateToken(_:), e o SDK a carrega como um HTTP Bearer ao solicitar o gateway. O SDK mantém apenas a mais recente, não a persiste nem a atualiza; após ela expirar, você a troca novamente e a reinjeta.

ticket

Credencial de teste de uso único. Seu servidor a troca por meio da plataforma aberta get-travel-credential (prefixo tk_, válida por 30 minutos, uso único), usada como o argumento createTravel(ticket:); ela se torna inválida assim que a experiência termina ou expira, e não pode ser reutilizada.

World

Um mundo de IA, contendo personagens e cenários. Criado e gerenciado pelo seu servidor; o SDK não está envolvido.

Travel

Uma única experiência em tempo real, correspondente a um identificador OysterTravel. Uso único; invalidado assim que um estado terminal é alcançado, exigindo um novo createTravel via mecanismo.

Status da sessão

OysterTravelStatus: idle → prepare → running → pausing → paused (pausado retorna para prepare → running via reconexão), mais dois estados terminais ended / failed (veja a §7).

Modo

adventure (comandos de direção/visualização/ação), directing (enredo orientado por texto) ou acting (atuação de personagem orientada por texto). O mode retornado por start() determina a UI de acordo; veja a §2 para o que cada modo suporta.

2. Visão geral

Após integrar este SDK, seu aplicativo pode entrar em "mundos" gerados em tempo real pela IA e ter uma experiência de vídeo interativo em tempo real em três modos — adventure, directing ou acting: iniciar a experiência → reprodução em tempo real → interação em tempo real → controle de processo (pause/resume/rewind/end) → callbacks de status e erro. Cada modo suporta um conjunto diferente de capacidades. Conduza sua UI a partir do mode retornado por start():

Capacidade

adventure

directing

acting

sendCommand (direção/visualização/ação)

Sim

Não

Não

sendInstruct (instrução de texto)

Não

Sim

Sim

pause() / resume()

Não

Sim

Sim

rewind(toSec:)

Não

Sim

Não — oculte o ponto de entrada

end()

Sim

Sim

Sim

start(maxExperienceTimeSec:)

Aplicado

Ignorado

Ignorado

Os mundos acting são priorizados para retrato: start() retorna um aspectRatio (9:16 / 16:9) para a sessão. Use-o para escolher a orientação do player e o tamanho do contêiner antes de puxar o fluxo (veja a §8).
import HappyOysterSDK; os pontos de entrada principais são de dois tipos. HappyOysterEngine — o ponto de entrada de orquestração, um singleton de nível de processo HappyOysterEngine.shared.

Método / Propriedade

Descrição

initialize(config:)

Inicializar o tempo de execução e registrar automaticamente o mecanismo em tempo real (uma vez, antes de createTravel)

updateToken(_:)

Injetar / atualizar o token de autenticação HTTP

createTravel(ticket:)

Criar um identificador de sessão com uma credencial de uso único

cleanup()

Liberar recursos (pode initialize novamente)

version

A versão atual do SDK

OysterTravel — o identificador de sessão para uma experiência, criado por createTravel(ticket:).

Método / Propriedade

Descrição

videoView / OysterVideoView(travel:)

Visualização de reprodução (UIKit / SwiftUI)

events / status

Fluxo de push de mudança de status + erro / status atual observável

start() / start(maxExperienceTimeSec:)

Conectar e reproduzir (opcionalmente, solicitar a duração máxima de uma experiência de aventura)

sendInstruct(content:)

Instrução de texto do modo Direção

sendCommand(_:) / flushCommands()

Controle do modo Aventura

pause() / resume()

Pausar / retomar (directing e acting)

rewind(toSec:)

Retroceder (apenas quando pausado)

end()

Encerrar (idempotente, certifique-se de chamá-lo)

pauseLocalAudioCapture() / resumeLocalAudioCapture()

Liberar / restaurar temporariamente o microfone

Também existem algumas exportações auxiliares: OysterLog para assumir o registro interno do SDK; HappyOysterEngine.version para ler a versão; OysterVideoView é a visualização de reprodução do SwiftUI (equivalente a videoView). O uso é descrito mais adiante. Ciclo de vida: inicializar → injetar token → criar sessão → montar vídeo + assinar eventos → iniciar reprodução → interagir → encerrar. O SDK não é responsável por criar ou gerenciar mundos (feito pelo seu servidor), nem expõe detalhes de comunicação em tempo real de baixo nível.

3. Início Rápido

Um fluxo completo da inicialização ao encerramento, com comentários passo a passo. Os detalhes de cada API estão na §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()
Para configuração do projeto, configuração de dependências (incluindo o adaptador AliRTC necessário e o binário do fornecedor), coordenação do lado do servidor e uma execução de ponta a ponta, consulte a documentação do projeto de exemplo.

4. Requisitos

Item

Requisito

Sistema operacional mínimo

iOS 15.0+ (todos os tipos públicos são marcados com @available(iOS 15.0, *))

Linguagem

Swift (async/await)

Concorrência

Acesso à thread principal (os tipos de entrada são marcados com @MainActor)

Rede

Acesso à rede pública necessário

Permissões

Info.plist deve incluir NSMicrophoneUsageDescription (veja abaixo)

Permissão de microfone: Uma experiência de vídeo interativo em tempo real precisa de um canal de áudio/vídeo em tempo real bidirecional (uplink + downlink), então o SDK ocupa o microfone local enquanto está em execução — isso não é gravação. Info.plist deve fornecer NSMicrophoneUsageDescription, caso contrário, iniciar a captura em tempo real causará uma falha. Quando você precisar de acesso exclusivo ao microfone (por exemplo, reconhecimento de fala), use pauseLocalAudioCapture() / resumeLocalAudioCapture() para liberá-lo e restaurá-lo temporariamente (veja a §6.2).

5. Integração e Autenticação

5.1 Integração e Dependências

import HappyOysterSDK é tudo o que você precisa no nível do código. O SDK é distribuído como um binário pré-compilado (xcframework) por meio de subspecs do CocoaPods, publicado no CocoaPods Trunk público — declare as dependências no seu 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 é obrigatório sempre que você puxar HappyOysterSDK/StreamAliRTC: se estiver faltando, o SDK retorna silenciosamente ao Loopback — ele pode se conectar e alcançar running, mas mostra uma tela preta sem erro.
A configuração do projeto e o fluxo de inicialização de ponta a ponta são tratados pelo projeto de exemplo; consulte a documentação do projeto de exemplo. Este documento foca na interface em si.

5.2 Modelo de Autenticação

O SDK não obtém nem atualiza tokens, mantendo as coisas leves. A autenticação tem duas camadas, e o integrador gerencia seus ciclos de vida:
  1. Token de autenticação HTTP (chave de API temporária do Bailian): Seu servidor a troca por meio da API do Bailian e a entrega; ela é injetada através de updateToken(_:). Alguns serviços internos do SDK chamam o gateway do Bailian diretamente, carregando este token para autenticação — portanto, deve ser uma chave de API temporária emitida pelo Bailian, não um token do seu próprio serviço de negócios. O SDK mantém apenas a mais recente, não a persiste nem a atualiza; após ela expirar, você a troca novamente e a reinjeta.
  2. Credencial de teste de uso único ticket: Seu servidor a troca por meio da plataforma aberta get-travel-credential (prefixo tk_, válida por 30 minutos, uso único), usada como o argumento createTravel(ticket:); ela se torna inválida assim que a experiência termina (normal ou anormalmente) ou expira, e não pode ser reutilizada.
AK, chaves de assinatura e outras credenciais de alto privilégio existem apenas no seu servidor; o SDK do cliente nunca as toca. O que o cliente recebe é sempre uma Chave de API temporária de curta duração.
Feature Gate (interruptor remoto / atualização forçada): O servidor pode desabilitar remotamente o SDK ou definir uma versão mínima suportada. Enquanto desabilitado, chamadas protegidas (start / pause / resume / rewind / sendInstruct / sendCommand) são rejeitadas com 108001 e qualquer experiência em andamento é encerrada pelo SDK (veja a §9). OysterSDKError.raw carrega um motivo legível por humanos; solicite ao usuário que atualize quando a versão for muito baixa.
Como lidar com a expiração do token: Após o token de autenticação HTTP acima expirar, solicite imediatamente um novo token do seu servidor e injete-o via updateToken(_:). Há dois lugares onde você precisa determinar se o token expirou:
  1. Ao chamar APIs como engine.createTravel ou travel.start, trate o erro e verifique os tipos de erro de token expirado/inválido (101001 / 101002); após injetar um novo token, chame novamente a API correspondente.
  2. Ao ouvir o evento .error de OysterTravelEvent, verifique os tipos de erro de token expirado/inválido, solicite o token novamente e injete-o.

6. Referência da API

Existem dois tipos de entrada, ambos @MainActor e @available(iOS 15.0, *). Os métodos de negócios são async throws e lançam OysterSDKError em caso de falha; os métodos com valores de retorno são todos marcados com @discardableResult.

6.1 HappyOysterEngine

Um singleton de nível de processo, o ponto de entrada de orquestração. init não é público — use sempre HappyOysterEngine.shared; não o instancie você mesmo (o mecanismo subjacente em tempo real também é um singleton de processo).
@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:)
  • Propósito: Inicializar o tempo de execução e registrar automaticamente o mecanismo em tempo real (nenhum registro manual necessário pelo host).
  • Parâmetros: config.apiHost é a URL do gateway Bailian, não o seu servidor de negócios, e é obrigatória; em ambientes de pré-lançamento/teste, você deve passar explicitamente o gateway correspondente, caso contrário, as solicitações falharão (por exemplo, 106001, o domínio não pode ser resolvido). config.model é o nome do modelo versionado habilitado para sua conta e também é obrigatório, sem padrão — o Happy Oyster é dividido em submodelos por modo, portanto, o SDK não pode inferir qual usar. Ambos devem pertencer à mesma conta e região do token injetado. Outros campos estão na §8 OysterConfig.
  • Um modelo atende a um mode: cada modelo por modo tem sua própria rota de gateway, portanto, uma única initialize atende apenas a mundos desse único mode. Se o seu aplicativo oferece mundos em vários modos, basta chamar initialize() novamente com o modelo correspondente antes de entrar em um mundo de um modo diferente — enquanto ocioso, a configuração mais recente prevalece, nenhuma cleanup() é necessária e o token injetado é mantido; enquanto uma Travel está em andamento, a chamada é ignorada, portanto, end() primeiro. Um modelo que não corresponde ao mode do mundo é rejeitado pelo gateway com AccessDenied, normalizado para 106003.
  • Quando usar: Chame uma vez antes de createTravel, o mais cedo possível após o início do aplicativo.
  • Retorna: Bool — se o config que você passou teve efeito. É false em dois casos: a configuração é inválida (apiHost / model em branco ou não formando uma URL de gateway válida), ou uma Viagem está em andamento, então a chamada foi ignorada. Em ambos os casos, o tempo de execução permanece inalterado.
  • Nota: Enquanto ocioso, chamá-lo novamente reconfigura o tempo de execução com a nova configuração (alternar apiHost / model não precisa de cleanup(), e o token injetado é mantido); é uma operação nula com apenas um aviso enquanto uma Travel está em andamento, portanto, end() primeiro. Uma configuração inválida deixa o tempo de execução inalterado. Não use isReady para saber se uma re-initialize foi bem-sucedida — se for rejeitada, a configuração anterior ainda estará em vigor e isReady permanecerá true; isReady responde "o mecanismo está utilizável agora", o valor de retorno responde "a configuração que acabei de passar teve efeito".
OysterLog
  • Propósito: Configurar e assumir o registro interno do SDK, imprimindo-o em seu próprio módulo de registro. Fornece setMinimumLevel(_:) para definir o nível e setHandler(_:) para saída personalizada (veja o exemplo da §3).
updateToken(_:)
  • Propósito: Injetar / atualizar o token de autenticação HTTP (Chave de API temporária do Bailian, §5.2).
  • Quando usar: Após initialize, pode ser chamado a qualquer momento; troque e chame novamente após o token expirar ou após receber um erro relacionado à autenticação (101001 / 101002).
  • Nota: Operação nula com um aviso quando não inicializado via initialize.
createTravel(ticket:)
  • Propósito: Criar um único identificador de sessão com um ticket de uso único.
  • Parâmetro: ticket é uma credencial de uso único; uma vez criada, é considerada ocupada para esta experiência.
  • Quando usar: Chame antes de cada nova experiência; o identificador retornado ainda não está conectado e você deve chamar travel.start() depois. O vídeo é obtido do identificador retornado (veja a §6.2).
  • Nota (throws síncrono): lança 100001 se não estiver initialized; lança 103004 se chamado novamente antes que a Viagem anterior tenha end()ed (cada mecanismo permite apenas uma Viagem ativa por vez).
cleanup()
  • Propósito: Liberar recursos do SDK (encerrar a viagem ativa, configuração de tempo de execução, token).
  • Quando usar: Ao sair completamente do SDK ou quando precisar alterar o config.
  • Nota: async — internamente, ele deterministicamente chama end() na viagem ativa atual primeiro, depois desmonta o tempo de execução, não deixando nada como fire-and-forget. Após a liberação, você pode chamar initialize novamente.

6.2 OysterTravel

O identificador de sessão criado por createTravel; uso único, invalidado assim que um estado terminal (end / encerramento do lado do servidor / falha) é alcançado, exigindo um novo createTravel por meio do mecanismo. Também é um ObservableObject (@Published status, pode direcionar diretamente o 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
}
Visualização de vídeo videoView / OysterVideoView(travel:)
  • Propósito: A entrada de renderização para a imagem remota — "o SDK fornece a visualização, o host a posiciona". Para UIKit, use travel.videoView; para SwiftUI, use OysterVideoView(travel:).
  • Quando usar: Disponível assim que o identificador é criado (o acesso repetido retorna a mesma visualização); monte-o em qualquer hierarquia e, assim que o mecanismo estiver pronto, ele renderiza automaticamente. A montagem antes ou depois de start() funciona em ambos os casos, sem tela preta.
  • Nota: Quando a sessão termina, o SDK libera automaticamente a vinculação de renderização; remova a visualização da hierarquia conforme necessário.
Eventos e status events / status / isEnded
  • Propósito: events é o fluxo de push de mudanças de status + erros; status é o status externo atual observável; isEnded é um sinalizador legível sincronamente para o estado terminal.
  • Quando usar: Recomenda-se começar a consumir events **antes de ** start(), para evitar a perda de status iniciais.
  • Nota: Cada acesso a events retorna um fluxo independente, suportando multi-assinatura; cancelar a assinatura = encerrar a iteração for await (ou destruir a Task mantida). No SwiftUI, você pode observar diretamente o status com @StateObject/@ObservedObject (os erros ainda chegam através de events). Veja a §7.
start() / start(maxExperienceTimeSec:)
  • Propósito: Use o ticket capturado no momento da criação para trocar pela configuração de viagem + ingresso no RTC e conectar para reproduzir. Em caso de sucesso, o SDK estabelece automaticamente a conexão em tempo real e inicia a pesquisa interna de status, expondo o status através de events.
  • Parâmetro: maxExperienceTimeSec (opcional) — solicita a duração máxima (em segundos) desta experiência de aventura. O valor é enviado ao servidor como está; os valores permitidos, a duração efetiva real e o tempo de término automático são todos decididos pelo servidor — o SDK não realiza validação local. Passar nil (ou chamar o start() sem parâmetros) usa a duração padrão do servidor. O modo de direção ignora este parâmetro. Quando o tempo acaba, o servidor encerra a experiência e o host recebe o estado terminal ended via events (o mesmo que um término no lado do servidor, consulte a §7).
  • Retorna: OysterStartTravelData (mode / version / encryptedTravelId, etc., veja a §8), que determina a UI de interação.
  • Erros: 401010/401011 (credencial inválida/usada), 403002 (mundo não pronto), 403007 (especificação de serviço não habilitada, por exemplo, acting), 429001/429002 (limite de simultaneidade / capacidade esgotada), 500001 (falha de recurso/servidor), 103004 (início simultâneo).
  • O mode do mundo do ticket deve corresponder ao model passado para initialize (responsabilidade do chamador): com modelos por modo, cada modelo tem sua própria rota de gateway, e start() envia o ticket para a rota do modelo atualmente inicializado. O SDK não verifica e não pode verificar isso para você de antemão — mode é entregue pela resposta a esta própria chamada de start() (OysterStartTravelData.mode); antes da chamada, o SDK mantém apenas um ticket opaco e um nome de modelo, sem modo para comparar, e inferir o modo a partir do nome do modelo seria adivinhar um esquema de nomenclatura de propriedade do servidor, o que o SDK não faz. Portanto: antes de entrar em um mundo de um modo diferente, chame initialize() novamente com o modelo correspondente (enquanto ocioso, a configuração mais recente prevalece — nenhuma cleanup() é necessária e o token é mantido; enquanto uma Travel está em andamento, a chamada é ignorada, portanto, end() primeiro). Em caso de incompatibilidade, este start() falha no gateway; ao diagnosticar, verifique primeiro se o model atual e o mode do mundo do ticket pertencem um ao outro e, em seguida, consulte os códigos de erro de credencial acima.
  • Nota (encerramento automático sem fluxo): O servidor envia um "tempo limite sem fluxo" (padrão ~30s). Se, após a conexão, nenhum fluxo for recebido dentro dessa duração (nunca alcança running), o SDK encerra automaticamente a experiência, faz a transição para failed e expõe 105006 via .error de events (fatal; lide com isso retornando à tela pré-início, sem necessidade de cronometrar você mesmo).
pause() / resume()
  • Propósito: Pausar / retomar a experiência (idempotente).
  • Quando usar: Suportado pelos mundos directing e acting; não suportado por adventure. Use o mode retornado por start() para decidir com antecedência se deve mostrar um botão de pausa. pause requer que o estado atual seja running; resume requer paused.
  • Erros: 103001 (nenhuma experiência ativa), 103002 (estado/versão não permitidos), 103003 (incompatibilidade de modo).
rewind(toSec:)
  • Propósito: Retroceder para os segundos especificados. Em caso de sucesso, o SDK entra novamente automaticamente com o rtcConfig original e retorna à reprodução.
  • Quando usar: **Só pode ser iniciado no estado ** paused, e apenas por mundos directing — acting e adventure não suportam retrocesso, portanto, oculte o ponto de entrada de retrocesso nesses modos e não o chame.
  • Erros: 103001, 103002.
end()
  • Propósito: Encerrar a experiência (idempotente, pode ser chamado repetidamente). Após uma chamada bem-sucedida ou uma saída anormal, o SDK desconecta automaticamente a conexão em tempo real, para a pesquisa e libera todos os recursos da sessão; o ticket é invalidado ao mesmo tempo, e o identificador entra em um estado terminal.
  • Quando usar / Nota: Seja o usuário saindo ativamente ou a experiência terminando passivamente (expiração do temporizador, recebimento de .ended/.failed, destruição da página), certifique-se de que um único end() seja alcançado, caso contrário, os recursos remotos podem não ser liberados prontamente. Recomenda-se direcionar todos os caminhos de saída para o mesmo método de limpeza idempotente.
sendInstruct(content:) (modo de direção)
  • Propósito: Enviar uma instrução de texto para conduzir o enredo.
  • Quando usar: Modo de direção; enviado diretamente quando running, armazenado em cache quando paused e reenviado com o primeiro quadro após retomar para running via reconexão.
  • Erros: 103001, 103002, 103003 (chamado no modo aventura), 403004 (moderação de conteúdo), 404000 (viagem não encontrada).
sendCommand(_:) / flushCommands() (modo aventura)
  • sendCommand: Envia comandos de controle de direção/visualização/ação (veja a §8 OysterAdventureCommand; fire-and-forget, sem retorno, não lança exceções). Efetivo apenas no modo adventure quando running. A entrada externa pode ser de alta frequência a cada quadro, e o SDK faz limitação internamente (amostragem de vitória do mais recente, fusão de quadros na taxa de linha do RTC); o host não precisa fazer limitação por conta própria. Note que a resposta do servidor aos comandos em si tem latência, então o tempo efetivo real não é fixo.
  • flushCommands: Chamado no momento da "liberação da tecla / liberação da entrada", reenviando imediatamente o último comando já aguardando na fila; uma operação puramente nula quando não há nenhum comando pendente, não gerando nenhum novo comando.
  • Erros (todos exibidos via .error de events, não throws): nenhuma experiência ativa 103001; chamado no modo de direção 103003; canal em tempo real não pronto / falha no envio 105004.
pauseLocalAudioCapture() / resumeLocalAudioCapture()
  • Propósito: Liberar / restaurar temporariamente a ocupação da captura do microfone local pelo SDK.
  • Quando usar: Quando algo como reconhecimento de fala precisar de acesso exclusivo ao microfone, use pause primeiro e resume depois.

7. Eventos e Status

Os eventos estão anexados a OysterTravel.events e são o canal de push ativo do SDK para você, usados para expor situações não acionadas por suas próprias chamadas (por exemplo, problemas com a conexão em tempo real gerenciada internamente ou a pesquisa de 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)
}
Existem dois estilos de consumo, escolha um:
  • SwiftUI: OysterTravel é um ObservableObject; use diretamente @StateObject/@ObservedObject para observar status e conduzir a UI; os erros ainda vêm de events.
  • Imperativo / UIKit: em uma Task, for await event in travel.events { ... }, e switch sobre .statusChanged / .error; cancele a Task mantida quando terminar.
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 estados de processo + 2 estados terminais):

Status

Descrição

Tratamento típico

idle

após criar, antes de iniciar

—

prepare

conectando / reconectando (conexão / reconexão interna)

mostrar dica de conexão / reconexão

running

stream pronto, interativo (reprodução interna)

mostrar imagem e controles

pausing

pausa aceita, aguardando confirmação do servidor

mostrar "pausando…"

paused

pausado (confirmado)

mostrar estado pausado (apenas directing mostra a entrada de retrocesso)

ended

encerrado (encerramento ativo ou pelo servidor). Terminal

encerrar e fechar a página

failed

falhou. Terminal

mostrar erro e encerrar

Após entrar em ended / failed, a sessão foi encerrada e todas as operações da sessão (pause/resume/sendCommand…) não têm mais efeito. Os callbacks podem ser acionados na thread principal, para que você possa atualizar a UI diretamente.
Durante a pesquisa interna de status, o SDK relata automaticamente os heartbeats de estado de pull/reprodução do cliente (conectando / reproduzindo / pausado / reconectando / desconectado), para que o servidor possa distinguir os estados do lado do fluxo dos estados do lado do cliente — comportamento puramente interno do SDK, do qual o host não precisa estar ciente ou participar.

8. Modelos de dados

Todos os tipos públicos são marcados com @available(iOS 15.0, *). Os valores de retorno/parâmetros abaixo são saídas do SDK, construídos internamente no local com tipos nativos do Swift (Date / TimeInterval / OysterTravelStatus); eles não Codable são e não expõem detalhes do formato de rede (snake_case) — a decodificação do formato de rede acontece dentro do 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)
}
  • Nota: os rawValues dos comandos estão em lower camelCase (por exemplo, front / mouseLeft / jump); os valores de enumeração acima são autoritativos.
  • Nota: mode é externamente adventure (wander) / directing (história) / acting (interpretação de papéis); a definição de OysterModeValue é autoritativa.
  • Nota: aspectRatio é uma string aberta (atualmente 9:16 / 16:9, mais podem ser adicionadas). Analise-a como width:height e compare a proporção em vez de corresponder a valores conhecidos.

9. Códigos de erro

O SDK relata erros uniformemente como OysterSDKError, e o tipo é sempre distinguido por code — não julgue o tipo por "qual caminho o erro veio": o mesmo code pode ser lançado por um método de negócio (async throws) ou exposto via .error de events. Para correspondência tipada, use error.kind (veja a §8 OysterErrorKind). Códigos de erro: servidor 4xxxxx/5xxxxx, cliente-local 1xxxxx.

Códigos de Erro do Servidor (comuns)

code

Significado

Tratamento sugerido

400000

Parâmetros inválidos (valor de enum inválido, etc.)

Verifique os parâmetros da solicitação ou a versão do SDK

401010

Credencial da experiência (ticket) inválida ou expirada

Solicite ao servidor que reemita a credencial

401011

Credencial da experiência (ticket) já utilizada

Credencial de uso único; reemitir

403001

O mundo não existe, foi excluído ou não pertence ao desenvolvedor atual (incluindo um mundo excluído após a emissão da credencial)

Escolha um World válido novamente

403002

Estado do World não está pronto

Aguarde o World estar pronto antes de iniciar

403003

A API permite apenas a chave de API primária

Uma chave temporária não pode ser usada para esta API

403004

Conteúdo de entrada rejeitado pela moderação de conteúdo; aplica-se às instruções de texto de sendInstruct

Altere a entrada e tente novamente

403007

A especificação de serviço solicitada não está habilitada

Não tente novamente como se a capacidade estivesse cheia; mude para uma especificação habilitada (normalmente: a conta não tem especificação de atuação)

403008

Configuração de capacidade temporariamente indisponível

Tente novamente mais tarde

404000

O recurso não existe (propriedade do mundo/wander ou nenhum artefato)

Verificar ID / status

409000

A solicitação entra em conflito com o estado atual do recurso

Verifique o estado da experiência

429001

Limite de concorrência atingido para esta especificação

Tente novamente após o término de uma sessão existente (não confunda com 500001)

429002

Capacidade disponível insuficiente

Tente novamente mais tarde

500000

Erro interno do sistema

Tente novamente mais tarde / reporte

500001

Falha na alocação de recursos de inferência ou no serviço interno

Tente novamente mais tarde

Códigos de Erro do Cliente Local

code

Significado

O SDK encerra a sessão automaticamente

Tratamento sugerido

100001

Chamado antes da inicialização do SDK; também cobre um initialize que não teve efeito porque apiHost/model estava em branco ou inválido

Não (lançado sincronamente, rejeitando esta chamada)

initialize primeiro, e verifique se tanto apiHost quanto model estão definidos corretamente

101001

Token de autenticação HTTP não injetado

Não

tente novamente após updateToken

101002

Token de autenticação HTTP inválido / rejeitado

Não

troque o token e tente novamente com updateToken

103001

Nenhuma experiência ativa no momento

Não (rejeitando esta chamada)

createTravel + start primeiro

103002

O estado/versão atual não permite esta operação

Não (rejeitando esta chamada)

verificar estado da experiência / version

103003

Incompatibilidade de modo (por exemplo, sendCommand chamado em um mundo não adventure)

Não (rejeitando esta chamada)

escolha a API correta por mode, consulte a tabela de capacidades da §2

103004

Criação/início concorrente da experiência

Não (lançado sincronamente)

serializar chamadas, end a sessão antiga primeiro

105001

Falha na conexão em tempo real

Sim

encerrar e reiniciar

105002

Tempo limite de entrada em tempo real

Sim

encerrar e reiniciar

105003

Tempo limite ao aguardar o primeiro quadro de vídeo

Sim

encerrar e reiniciar

105004

Canal em tempo real não está pronto / falha no envio

depende (falha no envio ativo; o heartbeat é apenas para relatório)

enviar após running

105005

Tempo limite de callback (padrão 30s)

Não

tente novamente e aumente callbackTimeoutMs se necessário

105006

Nenhum stream após a entrada; o SDK encerra a experiência automaticamente

Sim

encerrar e reiniciar

106001

Erro de rede local

Não

tente novamente

106002

Falha ao analisar a resposta

depende

atualize o SDK / reporte

106003

Nenhum código de erro reconhecível / código de erro de string de proxy

Não

tente novamente

108001

Desativado remotamente pelo interruptor de recursos do servidor (desligamento total ou versão muito antiga; motivo em raw)

Sim

Siga o motivo em raw; oriente o usuário a atualizar quando a versão for muito antiga

Como julgar a fatalidade: A fatalidade não é mais exposta como um campo booleano (OysterSDKError não tem isFatal). Semanticamente, "fatal" significa especificamente se o SDK encerra ativamente a sessão (desconectar o RTC, liberar toda a sessão) —
  • Erros que encerram automaticamente a sessão (por exemplo, 105001/105002/105003/105006/108001): o host percebe isso a partir do estado terminal da máquina de estados (status → failed, exposto via .statusChanged de events), e retorna para a tela antes de "iniciar experiência" de acordo, sem necessidade de julgar a própria fatalidade.
  • Erros de rejeição de chamada (100001/103001/103002/103003/103004): lançados sincronamente / a chamada é rejeitada quando você chama ativamente; eles não encerram a sessão.
  • Outros erros não fatais (por exemplo, 101001/101002/105005/106001/106003): eles não encerram a sessão; tente novamente conforme sugerido ou continue após reinjetar o token.
106001 pode ter duas causas: um erro de rede local ou um apiHost incorreto. Se tentar novamente não recuperar a solicitação, verifique se apiHost está configurado corretamente.
106003 aparecendo após você definir model geralmente significa que o nome/versão do modelo está errado ou não está habilitado para sua conta: verifique o modelo junto com o apiHost e o token, que devem pertencer à mesma conta e região — o gateway rejeita uma incompatibilidade com AccessDenied, normalizado para este código.