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.
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 |
ticket | Credencial de experiência de uso único: trocada pelo seu servidor via plataforma aberta e entregue ao cliente, usada apenas para um único |
Requisitos de ambiente
Item | Requisito |
|---|---|
minSdk | 24 (Android 7.0) e superior |
compileSdk | 36 |
Linguagem | Kotlin (APIs de corrotina |
ABI |
|
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: |
Modo |
|
Vídeo em tempo real | Estabelecida e mantida automaticamente pelo SDK após o sucesso de |
Visão geral
Métodos HappyOyster
Método | Descrição |
|---|---|
| Inicializa o SDK. A reinicialização em estado ocioso é suportada; a reinicialização enquanto um Travel está iniciando, ativo ou terminando é rejeitada com |
| Injeta/atualiza a chave de API do gateway Bailian (token Bearer). |
| Inicia uma experiência com uma credencial de uso único e estabelece automaticamente a conexão de vídeo em tempo real. |
| 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 |
| Retoma uma experiência pausada (direção e Atuação); inclui backoff de nova tentativa de 3× internamente. |
| Retrocede para o número especificado de segundos (apenas direção, estado |
| Envia uma instrução de texto para conduzir a narrativa (direção e Atuação, |
| Envia comandos de controle de direção/visão/ação (modo aventura, apenas |
| Retorna um |
| Encerra a experiência, desconectando automaticamente a conexão em tempo real e liberando todos os recursos da sessão. |
| String de versão do SDK (SemVer), uma constante de tempo de compilação. |
Eventos
Evento | Descrição |
|---|---|
| Alteração de status da experiência (incluindo o ciclo de vida do vídeo em tempo real); os valores são definidos em |
| 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 |
|---|---|
| Configuração de inicialização do SDK ( |
| Status da experiência: |
| Modo de experiência: |
| Modelo de criação de mundo: |
| Retornado por |
| Parâmetro para |
| Erro do SDK; contém |
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:
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.
- 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
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Recomenda-se passar |
|
| Sim | Configuração do SDK; deve conter os obrigatórios |
Retorna
Sem valor de retorno.
Erros
code | Descrição |
|---|---|
|
|
| Reinicialização rejeitada porque um Travel está iniciando, ativo ou terminando. Aguarde |
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
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | A chave de API do gateway Bailian, usada como token Bearer. |
Retorna
Sem valor de retorno.
Erros
code | Descrição |
|---|---|
| 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), comSDKError.rawcontendo apenas um resumo redigido do ticket atualmente ativo para diagnóstico, nunca o ticket completo. - Opcionalmente, passe
maxExperienceTimeSecpara 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
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | A credencial de experiência única, fornecida pelo seu servidor. |
|
| 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 |
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 |
|---|---|
|
|
|
|
| Parâmetro inválido (ex.: |
| Mundo não está em estado pronto |
| Falha na alocação de recursos / serviço interno |
| Uma Travel já está iniciando, ativa ou terminando, ou |
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.
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.
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
Parâmetros
Sem parâmetros.
Retorna
Retorna TravelStateData (contém encryptedTravelId, status).
Erros
code | Descrição |
|---|---|
| Nenhuma experiência ativa |
| Estado não permitido ou esta experiência não suporta pausa / retomada |
| 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
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| 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 |
|---|---|
| Nenhuma experiência ativa |
| O estado não é |
| 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
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | O conteúdo da instrução de texto a ser enviado. |
Retorna
Retorna SendInstructData (contém encryptedTravelId, content, accepted).
Erros
code | Descrição |
|---|---|
| Nenhuma experiência ativa ( |
| O modo atual não é nem direção nem Atuação (chamado no modo aventura) |
| O estado da experiência não é nem |
| Bloqueio por moderação de conteúdo |
| 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_AUDIOnã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).105004significa 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.
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 |
|---|---|---|
| Movimento: frente/esquerda/trás/direita/diagonal/inativo |
|
| Visão: cima/baixo/esquerda/direita/diagonal/none |
|
| Interação: pular/atacar/agachar/correr/none |
|
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
Nonesubsequente. -
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
Nonepara redefinir o estado. O SDK nunca gera um comando de redefinição automaticamente.
Assinatura
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Um objeto de comando contendo os três campos |
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 |
|---|---|
| Nenhuma experiência ativa |
| Estado não permitido |
| Chamado fora do modo aventura (direção / Atuação) |
| 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.aspectRatioantes 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 (vejastartTravel).
Assinatura
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 |
|---|---|
| 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
Parâmetros
Sem parâmetros.
Retorna
Retorna EndTravelData (contém encryptedTravelId, status, endedAt, durationSec).
Erros
code | Descrição |
|---|---|
| SDK não inicializado |
| 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
Retorna
A string de versão do SDK, como "x.y.z".
Escuta de eventos
Evento | Descrição |
|---|---|
| Alteração de status da experiência (incluindo o ciclo de vida do vídeo em tempo real); os valores são definidos em |
| 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). |
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
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 |
|---|---|---|
| Parâmetro inválido (enum inválido, etc.) | Verifique os parâmetros da solicitação ou a versão do SDK |
|
| Faça seu servidor reemitir uma credencial |
|
| A credencial é de uso único; reemita-a |
| O Mundo não existe, foi excluído ou não pertence ao desenvolvedor atual (incluindo um mundo já excluído dentro da credencial | Selecione novamente um Mundo válido |
| Mundo não está em estado pronto | Aguarde até que o mundo esteja pronto antes de iniciar |
| Violação de conteúdo de entrada (moderação de conteúdo); aplica-se às instruções de texto de | Modifique o conteúdo de entrada e tente novamente |
| 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 |
| Configuração de capacidade temporariamente indisponível | Tentar mais tarde |
| O recurso Travel não existe ou o ID não pertence à conta atual | Reiniciar a Travel |
| A solicitação entra em conflito com o estado atual do recurso | Verificar o estado da Travel |
| Limite de concorrência de SKU atingido | Tente novamente após o término de uma sessão existente (não confundir com |
| Nenhuma capacidade disponível no momento | Tentar mais tarde |
| Falha na alocação de recursos de inferência / serviço interno | Tentar mais tarde |
| Erro interno do sistema | Tentar mais tarde / relatar |
Códigos de erro locais do lado do cliente
code | Significado | Fatal? | Tratamento sugerido |
|---|---|---|---|
| Chamado antes da inicialização do SDK | Chamada rejeitada |
|
|
| Falha na inicialização | Passe um nome e versão completos do modelo não vazios e chame |
| API Key do gateway Bailian não injetada | Não | Tentar novamente após |
| 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.: | Não | Obtenha novamente a Chave Bearer e |
| Nenhuma experiência ativa no momento | Chamada rejeitada |
|
| O estado atual não permite esta operação (incluindo: incompatibilidade de estado; a experiência não suporta pausa / retomada / retrocesso para | Chamada rejeitada | Verifique o estado e o modo da experiência; |
| Incompatibilidade de modo: | Chamada rejeitada | Verifique se o modo atual corresponde ao requisito da interface |
| Uma chamada simultânea de | Chamada rejeitada | Aguarde |
| Falha na conexão em tempo real | Sim | Encerrar e reiniciar |
| Tempo esgotado para entrada em tempo real | Sim | Encerrar e reiniciar |
| Tempo esgotado aguardando o primeiro quadro de vídeo | Sim | Encerrar e reiniciar |
| Canal em tempo real não pronto / falha no envio | Não | Confirme se o canal em tempo real está pronto e tente novamente |
| Uma chamada de sinalização HTTP do gateway SDK não retornou dentro de | Não | Recomenda-se tentar novamente ou aumentar |
| 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 |
| Erro de rede local | Não | Tentável novamente |
| 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 |
| O serviço upstream retornou uma resposta de erro irreconhecível; o SDK manteve as informações originais em | Não | Tentável novamente; se persistir, investigue a disponibilidade do serviço juntamente com |
| SDK desativado remotamente (totalmente desligado ou versão muito baixa); o motivo está em | 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 |
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.- 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 viaonError; 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 defailed(ex.: falha de inferência500001); ② 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 chamarupdateTokennovamente 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 (rede106001, análise106002, anomalia upstream106003, erro de negócio5xxxxx) se enquadra nesta categoria — a sondagem continua no próximo ciclo, e somente quando lê um status defailedé que ela encerra a experiência; falha de autenticação101001e falha de envio assíncrono limitado desendCommand105004também são não fatais. Nota: o SDK nunca envia nenhum payload de keepalive próprio pelo canal em tempo real, portanto105004não pode aparecer enquanto a sessão estiver ociosa — só pode ser acionado pela sua própria chamada desendCommand.