Skip to main content

Referência da API do HappyOyster Android SDK

O ponto de entrada para o HappyOyster Android SDK é o objeto singleton HappyOyster. Exceto por initialize, updateToken, attachVideo e sendCommand, todos os métodos de negócios são funções suspend que lançam SDKError em caso de falha. Abrange os três modos aventura/direção/atuação, a configuração obrigatória de model e aspectRatio.

Se a corrotina chamadora for cancelada, o SDK cancela a solicitação HTTP em trânsito dessa chamada, se houver, e propaga CancellationException inalterado em vez de convertê-lo para SDKError. O cancelamento não reverte uma solicitação que o servidor já aceitou. Para o fluxo de integração, instalação e melhores práticas, consulte Guia de Integração do SDK Android Happy Oyster.

Terminologia Principal

Termo

Significado

token

API Key do gateway Bailian: injetada como um token Bearer pelo seu aplicativo via updateToken(token). O SDK mantém apenas a mais recente; ele não a persiste nem a renova. Quando a Key mudar, você deve injetá-la novamente. O gateway exige que todas as solicitações do SDK, incluindo startTravel, usem este Bearer. Quando a Key Bearer estiver expirada ou inválida, o SDK lança SDKError(101002); nesse caso, você deve obter e injetar novamente a Key Bearer (updateToken), em vez de trocar por um novo ticket. Recomendação de segurança: o Bearer no lado do cliente deve usar um token de curta duração emitido pelo seu servidor, em vez de empacotar uma API Key de longa duração no aplicativo ou confirmá-la em um repositório de código.

ticket

Credencial de experiência de uso único: trocada pelo seu servidor via plataforma aberta e entregue ao cliente, usada apenas para um único startTravel. Torna-se inválida assim que a experiência termina (normal ou anormalmente) e não pode ser reutilizada. Erros de credencial no nível do ticket são identificados por códigos de servidor de seis dígitos (ex.: 401010 = ticket inválido/expirado, 401011 = ticket já utilizado), que o SDK repassa literalmente.

Requisitos de ambiente

Item

Requisito

minSdk

24 (Android 7.0) e superior

compileSdk

36

Linguagem

Kotlin (APIs de corrotina suspend)

ABI

arm64-v8a / armeabi-v7a (o mecanismo de comunicação em tempo real inclui bibliotecas nativas)

Rede

Acesso à internet pública necessário

Conceitos Principais

Conceito

Descrição

Mundo

Um mundo de IA, contendo personagens e cenários. Criado e gerenciado pelo seu servidor.

Travel

Uma única experiência em tempo real. Ciclo de vida básico: init → pending → running → completed (falha é failed). Nos modos de direção e Atuação, se a experiência suportar pausa, running pode entrar em paused via pauseTravel e depois retornar para running via resumeTravel (a direção pode adicionalmente usar rewindTravel, após o qual o servidor retoma a experiência automaticamente); running ⇄ paused pode ocorrer em ciclo várias vezes.

Modo

adventure (interação dispositivo/comando), directing (narrativa orientada por texto) ou acting (Atuação: narrativa orientada por texto cuja proporção de reprodução é fixada pelo servidor na criação do mundo). O SDK expõe uniformemente esses três valores.

Vídeo em tempo real

Estabelecida e mantida automaticamente pelo SDK após o sucesso de startTravel; você não precisa conectar/desconectar manualmente. Ela é liberada automaticamente em endTravel.

Visão geral

Métodos HappyOyster

Método

Descrição

initialize(context, config)

Inicializa o SDK. A reinicialização em estado ocioso é suportada; a reinicialização enquanto um Travel está iniciando, ativo ou terminando é rejeitada com 103004.

updateToken(token)

Injeta/atualiza a chave de API do gateway Bailian (token Bearer).

startTravel(ticket)

Inicia uma experiência com uma credencial de uso único e estabelece automaticamente a conexão de vídeo em tempo real.

pauseTravel()

Pausa a experiência assincronicamente (direção e Atuação, e apenas se a experiência suportar pausa); após a aceitação, a pausa real é determinada por onStatusChanged(Paused).

resumeTravel()

Retoma uma experiência pausada (direção e Atuação); inclui backoff de nova tentativa de 3× internamente.

rewindTravel(rewindToSec)

Retrocede para o número especificado de segundos (apenas direção, estado paused). O valor em segundos deve ser um múltiplo de 4. A Atuação não suporta retrocesso.

sendInstruct(content)

Envia uma instrução de texto para conduzir a narrativa (direção e Atuação, running ou paused).

sendCommand(command)

Envia comandos de controle de direção/visão/ação (modo aventura, apenas running; thread principal). Não disponível para Atuação.

attachVideo()

Retorna um SurfaceView para reprodução; adicione-o ao seu layout para renderizar (thread principal).

endTravel()

Encerra a experiência, desconectando automaticamente a conexão em tempo real e liberando todos os recursos da sessão.

VERSION

String de versão do SDK (SemVer), uma constante de tempo de compilação.

Eventos

Evento

Descrição

onStatusChanged(status)

Alteração de status da experiência (incluindo o ciclo de vida do vídeo em tempo real); os valores são definidos em TravelStatusValue.

onError(error)

Callback quando um fluxo automático interno falha; um erro fatal também encerra a experiência atual.

Tipos de dados principais

Tipo

Descrição

SDKConfig

Configuração de inicialização do SDK (apiHost e model são obrigatórios, além de logLevel, logcatEnabled, logHandler e callbackTimeoutMs).

TravelStatusValue

Status da experiência: Init / Pending / Running / Paused / Failed / Completed.

ModeValue

Modo de experiência: adventure / directing / acting.

CreationModelValue

Modelo de criação de mundo: Simple (padrão, orientado por instruções) / ScriptList (script estruturado, sendInstruct não suportado).

StartTravelData

Retornado por startTravel; contém metadados como mode, version, creationModel, aspectRatio e maxExperienceTimeSec.

AdventureCommand

Parâmetro para sendCommand; contém os três campos translation / rotation / interaction.

SDKError

Erro do SDK; contém code: Int e raw: Any? opcional.

HappyOyster.initialize

Inicializa o SDK; chame-o antes de qualquer outra API (preferencialmente em Application.onCreate). config é obrigatório e deve conter o apiHost Bailian da sua conta e um model de happyoyster-1.0-directing / happyoyster-1.0-acting / happyoyster-1.0-adventure (correspondente à entrada da Open API). O SDK constrói as URLs de solicitação da seguinte forma:
https://{apiHost}/api/v2/apps/{model}/openapi/v1/{endpoint}
model não possui valor padrão: omiti-lo ao construir SDKConfig resulta em erro de compilação. Passar um valor em branco faz com que initialize lance SDKError(100002) de forma síncrona; nenhum runtime é criado ou substituído e nenhuma solicitação de rede é feita. O SDK mantém apenas o contexto da aplicação, não uma Activity. A reinicialização é suportada apenas enquanto o runtime anterior estiver ocioso. Para trocar de modelos, reinicialize com o novo model enquanto estiver ocioso; se uma Travel estiver iniciando, ativa ou terminando, aguarde endTravel() primeiro.
Aviso de conformidade regional:
  • Para apoiar a conformidade com os requisitos legais e de dados aplicáveis, se seus usuários pretendidos incluírem usuários dos EUA, você deve configurar um API Host da região dos EUA durante a inicialização do SDK para os serviços fornecidos a esses usuários.
  • Os desenvolvedores são responsáveis pela configuração correta e assumem a responsabilidade correspondente sob a lei aplicável caso não cumpram este requisito.

Assinatura

fun initialize(context: Context, config: SDKConfig)

Parâmetros

Campo

Tipo

Obrigatório

Descrição

context

Context

Sim

Recomenda-se passar applicationContext.

config

SDKConfig

Sim

Configuração do SDK; deve conter os obrigatórios apiHost e model, sem valores padrão.

Retorna

Sem valor de retorno.

Erros

code

Descrição

100002

model está em branco. A inicialização falha sincronamente com SDKError.raw definido como SDKConfig.model must not be blank; nenhum runtime é criado ou substituído e nenhuma solicitação de rede é feita.

103004

Reinicialização rejeitada porque um Travel está iniciando, ativo ou terminando. Aguarde endTravel() e tente novamente.

HappyOyster.updateToken

Injeta/atualiza a Chave da API do gateway Bailian. Thread-safe e chamável após initialize; o SDK usa o token mais recente para startTravel e solicitações subsequentes de controle de experiência. O ticket é uma credencial de experiência de uso único e não deve ser confundido com o token Bearer.

Assinatura

fun updateToken(token: String)

Parâmetros

Campo

Tipo

Obrigatório

Descrição

token

String

Sim

A chave de API do gateway Bailian, usada como token Bearer.

Retorna

Sem valor de retorno.

Erros

code

Descrição

100001

O SDK não foi inicializado.

HappyOyster.startTravel

Inicia uma experiência com um ticket de uso único. Em caso de sucesso, o SDK estabelece automaticamente a conexão de vídeo em tempo real e inicia a sondagem interna de status, com o status exposto via onStatusChanged.
  • ticket é uma credencial de uso único e é considerada consumida assim que a chamada é feita.
  • Apenas uma Travel simultânea é permitida por aplicativo em qualquer momento; chamar novamente enquanto uma experiência está em andamento lança SDKError(103004), com SDKError.raw contendo apenas um resumo redigido do ticket atualmente ativo para diagnóstico, nunca o ticket completo.
  • Opcionalmente, passe maxExperienceTimeSec para limitar a duração máxima desta experiência (apenas exploração de mundo / modo aventura); consulte Parâmetros.
StartTravelData.creationModel (CreationModelValue, padrão CreationModelValue.Simple): indica o modelo de criação do mundo, ou seja, como o conteúdo do script é gerenciado. simple (padrão) é um mundo comum orientado por instruções; mundos de exploração de mundo também são normalizados para este valor. scriptlist é um mundo estruturado ScriptList — seu conteúdo de script não é acessado através deste SDK. No modo ScriptList (creationModel == CreationModelValue.ScriptList), chamar sendInstruct é rejeitado e lança SDKError(103002). Este campo tem como padrão simple. StartTravelData.aspectRatio (String?): a proporção de reprodução que o servidor atribuiu a esta sessão, como uma string width:height. Não-null apenas para Atuação—"9:16" (retrato, o padrão do servidor na criação) ou "16:9" (paisagem); null para os modos de exploração de mundo e direção, e null quando o servidor não reporta o valor. O SDK preserva valores desconhecidos literalmente (não os reduz a null), portanto, os hosts devem tratar qualquer valor não reconhecido como null e recorrer à sua própria orientação padrão; o próprio SDK não consome este campo. O valor é entregue com o valor de retorno de startTravel(): dimensione o contêiner de reprodução a partir dele após startTravel() retornar e antes de chamar attachVideo() e adicionar a visualização retornada ao seu layout — o SDK só começa a vincular o fluxo remoto para renderização quando o host anexa a visualização, então decidir a orientação nesse ponto ainda precede o primeiro quadro renderizado (no entanto, não há garantia de que isso ocorra antes de o SDK entrar na sala em tempo real). A visualização remota é vinculada com um modo de renderização clip-to-fill, de modo que um contêiner cuja orientação discorda deste valor corta a imagem em vez de aplicar letterboxing.

Assinatura

suspend fun startTravel(ticket: String): StartTravelData
suspend fun startTravel(ticket: String, maxExperienceTimeSec: Int?): StartTravelData

Parâmetros

Campo

Tipo

Obrigatório

Descrição

ticket

String

Sim

A credencial de experiência única, fornecida pelo seu servidor.

maxExperienceTimeSec

Int?

Não

Duração máxima desta experiência em segundos; o mundo encerra a sessão automaticamente assim que ela for atingida. Aplica-se apenas ao modo de exploração de mundo (aventura); ignorado nos modos de direção (direção em tempo real) e Atuação. Os valores permitidos são configurados pelo servidor, atualmente 60 / 90 / 120; passar null (ou usar a sobrecarga sem este parâmetro) aplica o padrão do servidor (atualmente 60). Passar um valor não suportado faz com que o servidor rejeite startTravel com 400000, lançando SDKError(400000) sem criar nenhuma Travel ativa. O SDK não valida o valor localmente — o conjunto permitido é autoritativo no servidor.

Retorna

Retorna StartTravelData, contendo metadados da experiência (mode, version, creationModel, aspectRatio, etc.). Inspecione os metadados retornados antes de decidir como interagir (ex.: travel.mode, travel.creationModel, travel.version); para Atuação, também dimensione o contêiner de reprodução a partir de travel.aspectRatio.

Erros

code

Descrição

401010

ticket inválido ou expirado

401011

ticket já usado

400000

Parâmetro inválido (ex.: maxExperienceTimeSec não está dentro do conjunto permitido pelo servidor); este startTravel falha ao iniciar

403002

Mundo não está em estado pronto

500001

Falha na alocação de recursos / serviço interno

103004

Uma Travel já está iniciando, ativa ou terminando, ou startTravel é chamado simultaneamente (apenas uma Travel é permitida por vez; SDKError.raw contém apenas um resumo redigido do ticket ativo)

HappyOyster.pauseTravel / HappyOyster.resumeTravel

Pausa / retoma a experiência. O SDK gerencia apenas um Travel por vez; encryptedTravelId é obtido internamente pelo SDK e não precisa ser passado pelo chamador. Pré-condições:
  • pauseTravel: pode ser chamado apenas em direção ou Atuação e quando o estado é running.
  • resumeTravel: pode ser chamado apenas em direção ou Atuação e quando o estado é paused.
Nem todas as experiências suportam pausa / retomada: a experiência deve relatar o identificador de versão que seu modo exige (StartTravelData.version—storyV2 para direção, actingV2 para Atuação; comparado ignorando espaços em branco ao redor e maiúsculas/minúsculas), caso contrário, tanto pauseTravel quanto resumeTravel retornam 103002. A Atuação suporta pausa / retomada, mas não suporta rewindTravel. A pausa é assíncrona (importante): pauseTravel é uma operação "pesada" — uma chamada bem-sucedida (retorno do método) significa apenas que a pausa foi aceita; naquele momento, a experiência ainda não está realmente pausada. A pausa só é efetiva quando o callback onStatusChanged reporta paused. Portanto, conduza a máquina de estados do host e o controle de chamadas a partir desse callback: entre "chamar pauseTravel" e "receber o callback paused", você pode marcar o estado local como pausing; somente após receber paused você deve permitir iniciar resumeTravel ou rewindTravel. Não trate o retorno de pauseTravel como já pausado. Tratamento da conexão em tempo real: após uma pausa real, o SDK desconecta a conexão em tempo real; ao retomar, o SDK entra novamente e restaura a imagem automaticamente usando a credencial entregue durante o mesmo startTravel, sem necessidade de intervenção do host. Barreira ordenada de desmontagem de pausa: após a emissão de Paused, a desmontagem da sala em tempo real no lado do servidor ainda pode sofrer um breve atraso. O SDK estabelece uma janela de estabilização de 3 segundos a partir da confirmação da pausa. Se resumeTravel ou rewindTravel for chamado dentro dessa janela, a chamada de suspensão aguarda primeiro de forma não bloqueante pelo tempo restante e, em seguida, envia a solicitação de API de reabertura da sala. Nenhum atraso é adicionado se 3 segundos já tiverem decorrido naturalmente. Isso evita que uma desmontagem tardia da pausa feche a sala recém-aberta e exponha 105001. Retentativa da API de retomada: resumeTravel tenta internamente até 3 vezes em caso de falha (backoff de 1 s / 2 s / 3 s) para lidar com indisponibilidade breve do serviço após uma pausa; somente se todas as 3 tentativas falharem o erro será propagado para cima.
⚠️ Nota: Recomenda-se que o host aguarde até 3 s após resumeTravel retornar com sucesso antes de iniciar pauseTravel novamente, para evitar trocas muito frequentes. Esta é uma recomendação de tempo de espera entre chamadas no lado do host e não é imposta pelo próprio SDK. Veja o Guia de Integração do Happy Oyster Android SDK para detalhes.

Assinatura

suspend fun pauseTravel(): TravelStateData
suspend fun resumeTravel(): TravelStateData

Parâmetros

Sem parâmetros.

Retorna

Retorna TravelStateData (contém encryptedTravelId, status).

Erros

code

Descrição

103001

Nenhuma experiência ativa

103002

Estado não permitido ou esta experiência não suporta pausa / retomada

103003

Chamado no modo aventura; apenas direção e Atuação suportam pausa / retomada

HappyOyster.rewindTravel

Retrocede para o número especificado de segundos. encryptedTravelId é obtido internamente pelo SDK. Pré-condições: chamável apenas no modo direção e quando o estado é paused (retrocesso não é permitido no estado running). Nem todas as experiências de direção suportam retrocesso, e as não suportadas retornam 103002. Após um retrocesso bem-sucedido, a experiência é retomada automaticamente e o SDK reconecta o RTC automaticamente, sem necessidade de intervenção do host. A Atuação não possui capacidade de retrocesso: chamá-la em Atuação é rejeitado localmente pelo SDK com 103003, e nenhuma solicitação é emitida. Na Atuação, os hosts devem ocultar o ponto de entrada de retrocesso em vez de apenas desativar o botão.

Assinatura

suspend fun rewindTravel(rewindToSec: Double): RewindTravelData

Parâmetros

Campo

Tipo

Obrigatório

Descrição

rewindToSec

Double

Sim

O número alvo de segundos para retroceder, que deve ser um múltiplo de 4 (ex.: 4, 8, 12). Um valor que não seja múltiplo de 4 é arredondado para baixo pelo servidor até o menor múltiplo de 4 mais próximo (ex.: passar 7 resulta em 4).

Retorna

Retorna RewindTravelData (contém encryptedTravelId, status, resumedAtSec), onde resumedAtSec é o número de segundos para o qual o servidor realmente retrocedeu (já arredondado para baixo para um múltiplo de 4).

Erros

code

Descrição

103001

Nenhuma experiência ativa

103002

O estado não é paused ou esta experiência não suporta retrocesso

103003

Chamado no modo aventura ou Atuação; apenas o modo direção suporta retrocesso

HappyOyster.sendInstruct

Envia uma instrução de texto para conduzir a narrativa. Válido em direção ou Atuação e quando o estado da experiência é running ou paused. encryptedTravelId é obtido internamente pelo SDK. Comportamento no estado pausado: o SDK não retoma automaticamente enquanto pausado; a instrução é enviada diretamente. Cabe ao host decidir se deve chamar resumeTravel primeiro antes de enviar a instrução.

Assinatura

suspend fun sendInstruct(content: String): SendInstructData

Parâmetros

Campo

Tipo

Obrigatório

Descrição

content

String

Sim

O conteúdo da instrução de texto a ser enviado.

Retorna

Retorna SendInstructData (contém encryptedTravelId, content, accepted).

Erros

code

Descrição

103001

Nenhuma experiência ativa (startTravel nunca foi chamado ou ela terminou)

103003

O modo atual não é nem direção nem Atuação (chamado no modo aventura)

103002

O estado da experiência não é nem running nem paused (ex.: ainda na fase init/pending); ou o mundo atual está no modo ScriptList (StartTravelData.creationModel == CreationModelValue.ScriptList) — o envio de instruções não é permitido no modo ScriptList, onde os scripts são gerenciados pela API da plataforma Bailian

403004

Bloqueio por moderação de conteúdo

404000

A Travel não existe

HappyOyster.sendCommand

Envia comandos de controle de direção/visão/ação. Válido apenas no modo aventura e quando running.
  • Chame na thread principal; uma chamada fora da thread principal lança sincronicamente IllegalStateException.
  • Nenhuma experiência ativa reporta 103001.
  • Chamar fora do modo aventura (direção / Atuação) reporta 103003.
  • Um estado não permitido reporta 103002.
  • O uplink é estabelecido via um fluxo de áudio silencioso (o SDK não grava nem envia áudio real); RECORD_AUDIO não é um pré-requisito rígido para o DataChannel, mas declará-lo e concedê-lo é recomendado para compatibilidade entre dispositivos (veja Guia de Integração do Happy Oyster Android SDK § Instalação · Permissões). 105004 significa que o canal em tempo real não está pronto ou houve falha no envio (ex.: interrupção da conexão do DataChannel ou anomalia no canal em tempo real); não é acionado diretamente por uma permissão ausente.
Limitação integrada de 42 ms (24 fps, último vence): sendCommand limita internamente as escritas no DataChannel em intervalos de 42 ms (cerca de 24 fps). A validação de estado executa sincronamente e imediatamente, lançando erro instantaneamente em caso de chamada ilegal; a escrita real no DataChannel é limitada de forma assíncrona. Se pelo menos 42 ms tiverem passado desde o envio anterior, o comando é despachado imediatamente (incluindo a primeira chamada). Caso contrário, o comando pendente é substituído pelo valor mais recente e despachado uma única vez no final da janela atual de 42 ms. Múltiplas chamadas em uma janela produzem, portanto, uma única escrita na rede contendo o último valor. O host pode chamar sendCommand na taxa de quadros do jogo sem implementar seu próprio limitador de taxa. Falhas de envio durante limitação: o flush limitado é assíncrono, e uma falha de envio não pode ser lançada para o chamador — o erro é exposto via callback onError (não fatal, 105004). Comandos pendentes são descartados quando a sessão termina (eles não serão enviados após o término da sessão). Campos e valores de AdventureCommand:

Campo

Semântica

Valores

translation

Movimento: frente/esquerda/trás/direita/diagonal/inativo

W / A / S / D / W_A / W_D / S_A / S_D / None

rotation

Visão: cima/baixo/esquerda/direita/diagonal/none

Mouse_Up / Mouse_Down / Mouse_Left / Mouse_Right / Mouse_Up_Left / Mouse_Up_Right / Mouse_Down_Left / Mouse_Down_Right / None

interaction

Interação: pular/atacar/agachar/correr/none

Jump / Attack / Squat / Sprint / None

Os três campos são grupos de comandos mutuamente exclusivos e independentes. Movimento/visão diagonal usa um valor combinado único (por exemplo, frente+esquerda é W_A, não W e A simultâneos no mesmo campo). Cada chamada deve carregar o estado atual completo. Melhores práticas: ações únicas versus ações contínuas Use o intervalo de 42 ms como modelo mental:
  • Ação única (por exemplo, tocar para pular/atacar ou dar um passo): chame uma vez. O SDK a envia no intervalo mais próximo; não são necessárias chamadas repetidas ou comando None subsequente.
    // Jump once
    HappyOyster.sendCommand(AdventureCommand("None", "None", "Jump"))
    
  • Ação mantida (por exemplo, continuar movendo ou rotacionando): chame a cada frame enquanto mantida. O SDK emite aproximadamente um comando a cada 42 ms. Ao soltar, envie explicitamente um comando contendo None para redefinir o estado. O SDK nunca gera um comando de redefinição automaticamente.
    // While held: call from the host's frame loop
    HappyOyster.sendCommand(AdventureCommand("W", "None", "None"))
    // On release: explicitly reset once
    HappyOyster.sendCommand(AdventureCommand("None", "None", "None"))
    

Assinatura

fun sendCommand(command: AdventureCommand)

Parâmetros

Campo

Tipo

Obrigatório

Descrição

command

AdventureCommand

Sim

Um objeto de comando contendo os três campos translation, rotation, interaction.

Retorna

Sem valor de retorno (síncrono). A validação de estado é executada de forma síncrona e imediata; a gravação no DataChannel é limitada assincronicamente.

Erros

code

Descrição

103001

Nenhuma experiência ativa

103002

Estado não permitido

103003

Chamado fora do modo aventura (direção / Atuação)

105004 (via onError)

Falha no envio de flush limitado por taxa (não fatal, callback assíncrono)

HappyOyster.attachVideo

Retorna um SurfaceView para reprodução, que você adiciona ao seu layout; o SDK completa internamente a vinculação de renderização com o fluxo remoto.
  • Chame na thread principal; uma chamada fora da thread principal lança sincronicamente IllegalStateException.
  • O SDK mantém apenas uma referência fraca à View retornada e libera a vinculação de renderização quando a experiência termina; você deve remover a View do layout manualmente.
  • Para experiências de Atuação, dimensione o contêiner de reprodução a partir de StartTravelData.aspectRatio antes de adicionar a view retornada ao seu layout: a renderização é vinculada com um modo clip-to-fill, portanto, uma orientação incompatível corta a imagem (veja startTravel).

Assinatura

fun attachVideo(): SurfaceView

Parâmetros

Sem parâmetros.

Retorna

Retorna um SurfaceView; adicione-o ao seu layout para reproduzir o vídeo em tempo real.

Erros

code

Descrição

100001

SDK não inicializado

HappyOyster.endTravel

Encerra a experiência. encryptedTravelId é obtido internamente pelo SDK. Após uma chamada bem-sucedida (ou uma saída anormal), o SDK desconecta automaticamente a conexão em tempo real, interrompe a sondagem interna e libera todos os recursos da sessão, e o ticket atual é invalidado ao mesmo tempo.

Assinatura

suspend fun endTravel(): EndTravelData

Parâmetros

Sem parâmetros.

Retorna

Retorna EndTravelData (contém encryptedTravelId, status, endedAt, durationSec).

Erros

code

Descrição

100001

SDK não inicializado

103001

Nenhuma experiência ativa

HappyOyster.VERSION

Retorna a string de versão do SDK (SemVer), como "x.y.z". Este valor é uma constante de tempo de compilação injetada pela propriedade Gradle VERSION_NAME; pode ser lido com segurança sem chamar initialize primeiro.

Assinatura

val VERSION: String

Retorna

A string de versão do SDK, como "x.y.z".
Log.d("MyApp", "SDK version: ${HappyOyster.VERSION}")

Escuta de eventos

interface HappyOysterListener {
    fun onStatusChanged(status: TravelStatusValue) {}
    fun onError(error: SDKError) {}
}

fun addListener(listener: HappyOysterListener)
fun removeListener(listener: HappyOysterListener)
Os eventos do SDK são um canal de envio proativo para você, usado para relatar situações não acionadas por suas próprias chamadas explícitas (ex.: problemas na conexão em tempo real ou na sondagem de status que o SDK mantém automaticamente).

Evento

Descrição

onStatusChanged

Alteração de status da experiência (incluindo o ciclo de vida do vídeo em tempo real); os valores são definidos em TravelStatusValue.

onError

Callback quando um fluxo automático interno falha; um erro fatal também encerra a experiência atual (consulte a seção de códigos de erro).

⚠️ Nota: addListener / removeListener devem ser chamados após initialize; chamá-los antes da inicialização lança SDKError(100001). Recomenda-se registrar listeners imediatamente após HappyOyster.initialize(...) retornar com sucesso.

Modelos de Dados

// Configuration
data class SDKConfig(
    // Required: your account's Bailian API Host (e.g., llm-xxxx.ap-southeast-1.maas.aliyuncs.com), copied from the API Key page in the Bailian console;
    // must belong to the same account/region as the injected API Key, otherwise the gateway returns AccessDenied.
    val apiHost: String,
    // Required with no default: the complete HappyOyster model name and version (e.g., happyoyster-1.0);
    // refer to the official Bailian HappyOyster model documentation for available values.
    val model: String,
    // Minimum level for the built-in Logcat sink (does not affect logHandler); defaults to INFO, which
    // includes the lifecycle anchors (initialize, Travel start/status/end, RTC connect/first-frame) needed
    // to reconstruct a session timeline. Drop to WARN for errors-only, or raise to DEBUG/VERBOSE to diagnose.
    val logLevel: LogLevel = LogLevel.INFO,
    // Timeout for RTC join (timeout triggers 105002), first-frame wait (timeout triggers 105003), and SDK gateway HTTP signaling calls (timeout triggers 105005);
    // the two RTC phases are serial, so the worst-case wait is 2×callbackTimeoutMs (60s).
    val callbackTimeoutMs: Long = SDKConfig.DEFAULT_CALLBACK_TIMEOUT_MS, // 30_000ms
    // Whether the SDK writes its own logs to Android Logcat (tag HappyOysterSDK); defaults to false (silent).
    val logcatEnabled: Boolean = false,
    // Host log callback; receives the full stream of SDK LogRecords, unaffected by logLevel; defaults to null.
    val logHandler: HappyOysterLogHandler? = null,
) {
    companion object {
        /** Default callback timeout (milliseconds). Public constant, usable for comparison or display. */
        const val DEFAULT_CALLBACK_TIMEOUT_MS: Long = 30_000
    }
}

enum class LogLevel { VERBOSE, DEBUG, INFO, WARN, ERROR, NONE }

// Host log sink; injected via SDKConfig.logHandler; full firehose, unaffected by logLevel.
fun interface HappyOysterLogHandler {
    fun onLog(record: LogRecord)
}

// SDK structured log record; delivered to HappyOysterLogHandler; contains no sensitive values (Bearer /
// ticket / RTC token, RTC identity fields, and media URLs are all redacted). travelId (encryptedTravelId)
// is kept in full so it can be correlated with server-side session logs.
data class LogRecord(
    val level: LogLevel,
    val tag: String,        // fixed as "HappyOysterSDK"
    val message: String,    // readable log line (includes event name and details)
    val throwable: Throwable?,
    val timestampMs: Long,  // epoch milliseconds at emission time
)

// Status and mode (unknown values are preserved to allow service extension)
@JvmInline value class TravelStatusValue(val rawValue: String) {
    companion object {
        val Init = TravelStatusValue("init")
        val Pending = TravelStatusValue("pending")
        val Running = TravelStatusValue("running")
        val Paused = TravelStatusValue("paused")
        val Failed = TravelStatusValue("failed")
        val Completed = TravelStatusValue("completed")
    }
}
@JvmInline value class ModeValue(val rawValue: String) {
    companion object {
        val Adventure = ModeValue("adventure")
        val Directing = ModeValue("directing")
        val Acting = ModeValue("acting")
    }
}
@JvmInline value class CreationModelValue(val rawValue: String) {
    companion object {
        val Simple = CreationModelValue("simple")         // default; prompt/instruct-driven, world-exploration worlds normalize to this
        val ScriptList = CreationModelValue("scriptlist") // structured ScriptList world; sendInstruct not supported (throws 103002)
    }
}

// startTravel return
data class StartTravelData(
    val encryptedTravelId: String, // identifier for subsequent control interfaces
    val encryptedWorldId: String,
    val mode: ModeValue,           // adventure / directing / acting
    val creationModel: CreationModelValue = CreationModelValue.Simple, // world creation model; Simple (default) is instruct-driven, ScriptList does not support sendInstruct
    val playUrl: String?,
    val firstFrame: String?,       // first-frame image address, may be produced asynchronously
    val bgmUrl: String?,
    val version: String,           // world version identifier; Acting is actingV2
    val aspectRatio: String? = null, // Acting only: 9:16 / 16:9; other modes null. Use to set player orientation
    val maxExperienceTimeSec: Int? = null, // server-reported max experience time (seconds); non-null only for adventure; null for directing / acting
)

// Control interface parameters and returns
data class AdventureCommand(
    val translation: String, // movement: forward/left/back/right/diagonal (W_A, …)/idle
    val rotation: String,    // view: up/down/left/right/diagonal (Mouse_Up_Left, …)/none
    val interaction: String, // interaction: jump/attack/squat/sprint/none
)
data class TravelStateData(val encryptedTravelId: String, val status: TravelStatusValue)
data class RewindTravelData(val encryptedTravelId: String, val status: TravelStatusValue, val resumedAtSec: Double)
data class EndTravelData(val encryptedTravelId: String, val status: TravelStatusValue, val endedAt: String, val durationSec: Int)
data class SendInstructData(val encryptedTravelId: String, val content: String, val accepted: Boolean)

// Error (identified by code; the original information is in raw)
// Note: SDKError is not a data class (no copy()/destructuring), it is a plain class.
class SDKError(val code: Int, val raw: Any? = null) : Exception("Happy Oyster SDK error: $code")

Códigos de erro

Os erros são identificados por um code numérico. O SDK repassa códigos de erro de negócio que o chamador pode tratar (comumente 4xxxxx / 5xxxxx); os códigos de erro locais do SDK são 1xxxxx.

Códigos de erro de negócio (comuns)

code

Significado

Tratamento sugerido

400000

Parâmetro inválido (enum inválido, etc.)

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

401010

ticket inválido ou expirado

Faça seu servidor reemitir uma credencial

401011

ticket já usado

A credencial é de uso único; reemita-a

403001

O Mundo não existe, foi excluído ou não pertence ao desenvolvedor atual (incluindo um mundo já excluído dentro da credencial startTravel)

Selecione novamente um Mundo válido

403002

Mundo não está em estado pronto

Aguarde até que o mundo esteja pronto antes de iniciar

403004

Violação de conteúdo de entrada (moderação de conteúdo); aplica-se às instruções de texto de sendInstruct

Modifique o conteúdo de entrada e tente novamente

403007

Especificação de serviço não habilitada para esta conta

Não tente novamente como capacidade cheia; mude para uma especificação habilitada ou solicite a habilitação

403008

Configuração de capacidade temporariamente indisponível

Tentar mais tarde

404000

O recurso Travel não existe ou o ID não pertence à conta atual

Reiniciar a Travel

409000

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

Verificar o estado da Travel

429001

Limite de concorrência de SKU atingido

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

429002

Nenhuma capacidade disponível no momento

Tentar mais tarde

500001

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

Tentar mais tarde

500000

Erro interno do sistema

Tentar mais tarde / relatar

Códigos de erro locais do lado do cliente

code

Significado

Fatal?

Tratamento sugerido

100001

Chamado antes da inicialização do SDK

Chamada rejeitada

initialize primeiro

100002

model estava em branco durante a inicialização do SDK; lançado sincronamente com SDKError.raw definido como SDKConfig.model must not be blank; nenhum runtime é criado ou substituído e nenhuma solicitação de rede é feita

Falha na inicialização

Passe um nome e versão completos do modelo não vazios e chame initialize novamente; consulte a documentação oficial do modelo Bailian HappyOyster para valores disponíveis

101001

API Key do gateway Bailian não injetada

Não

Tentar novamente após updateToken

101002

Chave Bearer da API do gateway Bailian expirada ou rejeitada. Nota: esta é a Chave Bearer do gateway, não o ticket de uso único; erros de credencial no nível do ticket são identificados por códigos de servidor de seis dígitos (ex.: 401010/401011)

Não

Obtenha novamente a Chave Bearer e updateToken; não é necessário trocar por um novo ticket

103001

Nenhuma experiência ativa no momento

Chamada rejeitada

startTravel primeiro

103002

O estado atual não permite esta operação (incluindo: incompatibilidade de estado; a experiência não suporta pausa / retomada / retrocesso para pauseTravel/resumeTravel/rewindTravel (seu version não é o identificador v2 exigido pelo seu modo); estado não é paused para rewindTravel; creationModel == ScriptList para sendInstruct)

Chamada rejeitada

Verifique o estado e o modo da experiência; sendInstruct está indisponível no modo ScriptList (creationModel == CreationModelValue.ScriptList), onde o conteúdo do script não é gerenciado por este SDK

103003

Incompatibilidade de modo: sendCommand chamado em direção ou Atuação, ou pauseTravel / resumeTravel / rewindTravel / sendInstruct chamados em aventura, ou rewindTravel chamado em Atuação

Chamada rejeitada

Verifique se o modo atual corresponde ao requisito da interface

103004

Uma chamada simultânea de startTravel, ou reinicialização enquanto uma Travel está iniciando, ativa ou terminando (apenas uma Travel é permitida por vez; SDKError.raw para início simultâneo contém apenas um resumo redigido do ticket)

Chamada rejeitada

Aguarde endTravel() antes de tentar novamente

105001

Falha na conexão em tempo real

Sim

Encerrar e reiniciar

105002

Tempo esgotado para entrada em tempo real

Sim

Encerrar e reiniciar

105003

Tempo esgotado aguardando o primeiro quadro de vídeo

Sim

Encerrar e reiniciar

105004

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

Não

Confirme se o canal em tempo real está pronto e tente novamente sendCommand após running; se um dispositivo específico apresentar mau funcionamento, tente declarar e conceder RECORD_AUDIO (veja Guia de Integração do Happy Oyster Android SDK § Instalação · Permissões)

105005

Uma chamada de sinalização HTTP do gateway SDK não retornou dentro de callbackTimeoutMs (padrão 30s); os tempos limite de ingresso RTC e primeiro quadro usam 105002 e 105003, respectivamente

Não

Recomenda-se tentar novamente ou aumentar callbackTimeoutMs

105006

Término automático por falta de fluxo: o primeiro quadro nunca chegou ou o fluxo foi interrompido durante a execução e não se recuperou antes do tempo limite. O SDK encerra proativamente a experiência atual

Sim

Encerrar e reiniciar

106001

Erro de rede local

Não

Tentável novamente

106002

Falha na análise da resposta

Não

Lançado para o chamador quando acionado por uma chamada explícita; na sondagem de status interna, apenas onError é emitido e a experiência não é encerrada

106003

O serviço upstream retornou uma resposta de erro irreconhecível; o SDK manteve as informações originais em SDKError.raw (incluindo rejeições de borda do gateway, como AccessDenied)

Não

Tentável novamente; se persistir, investigue a disponibilidade do serviço juntamente com raw. Se raw contiver AccessDenied (mais frequentemente na primeira solicitação após a inicialização), trata-se de um problema de configuração do gateway; verifique nesta ordem: ① se o nome e a versão do model estão corretos, ainda disponíveis, publicados e autorizados; ② ortografia do apiHost; ③ se apiHost, model e a Key injetada via updateToken correspondem à conta e região exigidas; ④ se sua conta foi adicionada à lista de permissões do aplicativo

108001

SDK desativado remotamente (totalmente desligado ou versão muito baixa); o motivo está em SDKError.raw (String)

Sim (quando o SDK detecta um resultado de desativação, ele encerra automaticamente a experiência em andamento; você pode reiniciar após a recuperação)

Notifique o usuário com base no motivo em raw; oriente uma atualização quando a versão for muito baixa

"Fatal?" refere-se especificamente a se isso aciona o SDK para terminar automaticamente a experiência atual. Erros de validação síncrona, como 100001/100002/103xxx, apenas rejeitam/lançam exceção para essa chamada (100002 falha diretamente a inicialização) e não terminam uma experiência.
Fatal vs não fatal:
  • Erros fatais: o SDK encerra automaticamente a experiência atual (desconecta a conexão em tempo real, libera recursos, chama endTravel) e os expõe via onError; o host deve limpar o estado da experiência atual e permitir um reinício. Existem quatro categorias: ① a sondagem interna de status lê um status de experiência de failed (ex.: falha de inferência 500001); ② erro fatal de conexão em tempo real (105001/105002/105003); ③ término automático por falta de fluxo (105006: o primeiro quadro nunca chegou, ou o fluxo foi interrompido durante a execução e não se recuperou antes do tempo limite, e o SDK o encerra proativamente); ④ SDK desativado remotamente (108001).
  • Erros não fatais: não encerram a experiência e são expostos apenas via onError; você pode chamar updateToken novamente ou aguardar a recuperação do serviço/canal em tempo real antes de continuar. Uma única falha na própria sondagem interna de status (rede 106001, análise 106002, anomalia upstream 106003, erro de negócio 5xxxxx) se enquadra nesta categoria — a sondagem continua no próximo ciclo, e somente quando lê um status de failed é que ela encerra a experiência; falha de autenticação 101001 e falha de envio assíncrono limitado de sendCommand 105004 também são não fatais. Nota: o SDK nunca envia nenhum payload de keepalive próprio pelo canal em tempo real, portanto 105004 não pode aparecer enquanto a sessão estiver ociosa — só pode ser acionado pela sua própria chamada de sendCommand.