Ao integrar o HappyOyster Android SDK, seu App pode entrar em mundos gerados por IA em tempo real, proporcionando uma experiência de vídeo interativo em tempo real em três modos: Adventure (exploração de mundo), Directing (direção em tempo real) e Acting (interpretação de papéis).
1. O Que Você Pode Fazer
- Iniciar uma experiência (Travel): Entre em um mundo pronto com uma credencial de uso único; o SDK estabelece automaticamente a conexão de vídeo em tempo real.
- Reprodução em tempo real: O SDK retorna uma View de vídeo que você monta em seu layout para reproduzir os visuais gerados em tempo real pela IA.
- Interação em tempo real:
- modo de direção (directing): Envie instruções de texto para conduzir a história.
- atuação: Também envia instruções de texto; pausar/retomar estão disponíveis; não retroceda e não use
sendCommand. Use oaspectRatioda resposta de entrada para definir a orientação do jogador (veja §13 Adaptação de modo). - modo aventura (adventure): Envie comandos de controle de direção/ponto de vista/ação para interagir com o mundo.
- Controle de processo: Pausar / retomar (direção e atuação), retroceder (apenas direção), encerrar (todos os três modos).
- Callbacks de status e erro: Perceba o status e as exceções da experiência em tempo real através de listeners de eventos.
2. Instalação
O SDK do Happy Oyster (cn.happyoyster:opensdk) é publicado no Maven Central; seu mecanismo de comunicação em tempo real subjacente (Alibaba Cloud ARTC) é publicado no Alibaba Cloud Maven. Ambos os repositórios devem ser declarados.
Requisitos de ambiente
Item | Requisito |
|---|---|
minSdk | 24 (Android 7.0) e superior |
compileSdk | 36 |
JDK | Alvo de bytecode JDK 11 (toolchain do host: JDK 11 ou superior recomendado) |
Linguagem | Kotlin (API de corrotina |
ABI |
|
Rede | Acesso à internet pública necessário |
settings.gradle.kts da raiz do projeto:
<version> abaixo por esse número exato de versão e adicione a dependência no módulo build.gradle.kts:
com.aliyun.aio:AliVCSDK_ARTC falhe na resolução.Permissões
A própria biblioteca do SDK declara apenas INTERNET. O mecanismo de comunicação em tempo real mescla automaticamente um pequeno número de permissões do tipo rede/Bluetooth/configurações de áudio; o manifesto da biblioteca não inclui permissões de microfone ou câmera. O fluxo de vídeo é apenas para reprodução por assinatura, e o SDK não envia áudio real para o lado remoto.
O host deve declarar por conta própria: Quando o seu targetSdk for 33 ou superior, você deve declarar a permissão de notificação no AndroidManifest.xml do host (o mecanismo de comunicação em tempo real inclui um serviço em primeiro plano):
sendCommand) — declarar a permissão do microfone é recomendado: Os comandos de controle em tempo real do modo aventura trafegam em um uplink carregado por um fluxo de áudio silencioso que estabelece a "identidade do publicador" local; o SDK não grava ou faz upload do seu áudio real. RECORD_AUDIO não é um pré-requisito rígido para o DataChannel — mesmo sem ele, o fluxo silencioso ainda atua como publicador e o uplink normalmente está disponível. Ainda assim, para estabilidade entre dispositivos, nós recomendamos que, se o seu aplicativo usar sendCommand, você declare a permissão no AndroidManifest.xml do host e a solicite em tempo de execução antes de chamar.
105004: 105004 significa que o canal em tempo real não está pronto / um envio falhou (por exemplo, uma interrupção do DataChannel ou uma anomalia no canal em tempo real). Não é uma consequência necessária de uma permissão ausente — não é acionado diretamente por RECORD_AUDIO não ter sido concedida. O modo de direção (sendInstruct) e a reprodução de vídeo não são afetados. Se o seu aplicativo não usar o modo aventura, essa permissão não é necessária.
Para remover permissões mescladas, use tools:node="remove".
3. Modelo de autenticação
O SDK não obtém nem atualiza tokens, mantendo-o leve. A autenticação possui duas camadas:
- 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 atualiza, e após a alteração da Key, você a reinjeta. O gateway exige que todas as requisições do SDK, incluindostartTravel, usem este Bearer. Quando a Bearer Key expira ou é inválida, o SDK lançaSDKError(101002); neste caso, você deve obter e reinjetar a Bearer Key (updateToken) em vez de trocar por um novo ticket. Durante o desenvolvimento / Demo, você pode usar sua API Key principal do Bailian (百炼) diretamente como o Bearer (updateToken) para fazer o fluxo funcionar. Em produção, sempre mude para um token de curta duração emitido pelo seu servidor, e nunca inclua uma API Key de longa duração em um aplicativo distribuído. - Credencial de experiência de uso único
ticket: Trocada pelo seu servidor através da plataforma aberta e entregue ao cliente; usada apenas para uma únicastartTravel. Ela se torna inválida após o término da experiência (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 (por exemplo,401010= ticket inválido / expirado,401011= ticket já utilizado), os quais o SDK repassa literalmente.
SDKConfig.apiHost (no formato llm-xxxx.ap-southeast-1.maas.aliyuncs.com, copiado do campo "API Host" na página API Key do console Bailian (百炼)) e passar o SDKConfig.model obrigatório e sem padrão (happyoyster-1.0-directing / happyoyster-1.0-acting / happyoyster-1.0-adventure, correspondendo à entrada da Open API). O SDK completa a URL da requisição como https://{apiHost}/api/v2/apps/{model}/openapi/v1/{endpoint}, portanto, você não precisa montá-la manualmente.
Omitir model ao construir SDKConfig é um erro de tempo de compilação. Se model estiver em branco, initialize lança sincronicamente SDKError(100002) (raw = "SDKConfig.model must not be blank"), não cria nem substitui nenhum runtime e não faz nenhuma requisição de rede. O API Host, o modelo e a API Key injetada devem corresponder à conta, região e autorização de modelo necessárias, caso contrário, o gateway normalmente retorna AccessDenied (em tempo de execução, isso é lançado como SDKError(106003), com o corpo original do AccessDenied disponível em SDKError.raw; consulte a linha 106003 da tabela de códigos de erro da Referência da API para uma lista de verificação de solução de problemas). Por segurança, recomendamos fortemente que o cliente injete um token de curta duração emitido pelo seu servidor como o Bearer, em vez de incluir uma API Key de longa duração no aplicativo ou confirmá-la em um repositório de código.
4. Início Rápido
5. Assinatura de eventos e tratamento de erros
Use onStatusChanged para conduzir a máquina de estados do host e controlar as capacidades de interação; use onError para receber erros de tempo de execução de forma uniforme. Para a interface de eventos e os códigos de erro completos, consulte a Referência da API do SDK Android do Happy Oyster.
Obrigatório
- Registre o listener imediatamente após
HappyOyster.initialize(...)retornar com sucesso;addListener/removeListenerdevem ser chamados apósinitialize(chamá-los antes da inicialização lançaSDKError(100001)). - Controle por
onStatusChanged(Running)—chamadas de interação são permitidas apenas apósrunning; osendCommanddo modo aventura é válido apenas emrunning. - Trate
onErrortambém; não capture apenasstartTravel. Erros fatais também encerram a experiência (veja a seção de códigos de erro da Referência da API).
- Chame
removeListenerem um ponto apropriado do ciclo de vida (comoonDestroy) para evitar vazamentos de memória.
- Registrar listeners repetidamente sem chamar removeListener.
6. Enviando instruções: sendInstruct e sendCommand
sendInstruct (direção / atuação)
sendInstruct é usado na direção e atuação para enviar instruções de texto que conduzem a imagem; ele pode ser chamado no estado running ou paused. No estado pausado, o SDK não retoma automaticamente — o host decide se deve chamar resumeTravel primeiro e depois enviar a instrução (para detalhes do contrato, como limitação de taxa e validação de estado, consulte a Referência da API). O creationModel de um mundo de atuação é sempre Simple, portanto, a restrição ScriptList se aplica apenas à direção.
sendCommand (modo aventura)
sendCommand é usado no modo aventura (adventure) para enviar comandos de controle de direção/ponto de vista/ação; é válido apenas em running. O SDK possui um limitador integrado de "o último vence" de 42 ms (24 fps), então o host pode chamá-lo na taxa de quadros do jogo e o SDK faz a mesclagem automaticamente; nenhuma limitação de taxa manual é necessária. Chame uma vez para uma ação única. Para uma ação mantida, continue chamando a cada quadro enquanto mantida e envie explicitamente uma redefinição None quando liberada (para o contrato detalhado de limitação de taxa e superfície de falhas, consulte a Referência da API).
Prática recomendada: Na UI de interação do modo aventura do host, forneça três pontos de entrada de comando independentes (direção de movimento + direção do ponto de vista + interação de ação), mantenha o valor atualmente retido para cada grupo e envie um snapshot completo de três campos a cada chamada. Use "None" apenas para dimensões inativas. Quando entradas de diferentes dimensões forem mantidas simultaneamente, preserve e envie todos os valores ativos em vez de redefinir as outras dimensões para "None".
7. Pausar / Retomar / Retroceder
Modos aplicáveis: pausar / retomar se aplicam a direção e atuação, e se comportam de forma idêntica em ambos (incluindo a barreira de 3 segundos abaixo); retroceder é apenas para direção. Chamar pauseTravel / resumeTravel / rewindTravel no modo aventura é rejeitado pelo SDK com 103003. Além disso, a version relatada pelo servidor deve ser o token v2 que seu modo exige (storyV2 para direção, actingV2 para atuação); caso contrário, pausar / retomar retorna 103002.
A pausa é assíncrona: O retorno do método pauseTravel significa apenas que ela foi aceita; a pausa real é determinada por onStatusChanged(Paused). Entre "chamar pauseTravel" e "receber o callback Paused", o host pode marcar seu estado de experiência local como pausing; somente após receber Paused você deve permitir a chamada de resumeTravel ou do rewindTravel dependente do estado de pausa.
Barreira interna de pausa→reabertura do SDK: assim que Paused for recebido, o host pode chamar resumeTravel / rewindTravel de acordo com o contrato. Se a chamada ocorrer dentro da janela de estabilização de 3 segundos após a confirmação da pausa, o método de suspensão do SDK aguarda o tempo restante antes de enviar a solicitação que reabre a sala em tempo real. O host não precisa de um atraso extra de pausa→retomada, e nenhum atraso é adicionado depois que 3 segundos tiverem decorrido naturalmente.
Tempo de espera para chamadas no lado do host (recomendado): Recomenda-se que o host espere para emitir outro pauseTravel dentro de 3 s após resumeTravel retornar com sucesso, para evitar trocas muito frequentes. O próprio SDK não impõe esse tempo de espera.
Retroceder: rewindTravel está disponível apenas no estado paused; após retroceder, o servidor retoma automaticamente e o SDK reconecta o RTC automaticamente, sem necessidade de intervenção do host. Sequência típica: pause → wait:paused → rewindTravel(sec). Os segundos de retrocesso rewindToSec devem ser um múltiplo de 4 (por exemplo, 4, 8, 12); não múltiplos são arredondados para baixo pelo servidor (por exemplo, 7→4), e os segundos efetivos reais são determinados pelo resumedAtSec retornado. Retroceder é apenas para direção: chamar rewindTravel no modo atuação ou aventura é rejeitado pelo SDK localmente com 103003, sem emitir nenhuma solicitação HTTP; o host deve ocultar a entrada de retrocesso em vez de apenas desativar o botão.
Para detalhes do contrato, como semântica assíncrona e backoff de repetição de 3× (backoff do resumeTravel de 1 s / 2 s / 3 s), consulte a Referência da API do SDK Android do Happy Oyster.
8. Registro de logs
Tag Logcat do SDK: HappyOysterSDK. O SDK fornece dois caminhos de saída de log independentes:
- Logcat integrado (desativado por padrão): o SDK grava no Logcat apenas quando
SDKConfig.logcatEnabled = true(padrãofalse, totalmente silencioso).SDKConfig.logLevelfiltra seu nível mínimo; o padrãoINFOjá carrega as âncoras de ciclo de vida necessárias para reconstruir uma sessão (inicialização, início da Travel / transições de status / fim, entrada no RTC / primeiro quadro). Reduza paraWARNpara apenas erros, ou aumente paraDEBUG/VERBOSEpara um diagnóstico mais profundo.logLevelnão afetalogHandler. - Callback do host
logHandler(recomendado): recebe cadaLogRecorddo SDK (o fluxo completo), totalmente independente delogLevel/logcatEnabled, e pode encaminhar para o próprio sistema de log do host (Logcat, arquivos, plataformas de crash, etc.). O callback deve ser rápido e não bloqueante e não deve fazer chamadas de volta ao SDK; as exceções que ele lança são capturadas silenciosamente;LogRecord.messageé ocultado e não contém token Bearer,ticketou token RTC em texto simples.
travelId (ou seja, encryptedTravelId) nos logs do SDK é emitido em sua totalidade e é a chave de sessão enviada ao servidor — inclua-o ao investigar uma sessão ou abrir um chamado para alinhar os logs do cliente e do servidor. Cada linha de resposta HTTP também carrega o requestId do servidor (o campo reqId=, mostrado como - quando ausente) para identificar uma única solicitação; este ID aparece apenas nos logs e nunca é exposto em nenhum valor de retorno público.
9. Ciclo de vida e memória
- Chame
initializeemApplication.onCreate, uma vez globalmente. - Reinicialização em estado ocioso (por exemplo, para alternar a região da API ou
model) fecha o tempo de execução ocioso anterior e redefine os listeners registrados e o estado do feature-gate; registre novamente os listeners após o seu retorno. A reinicialização é rejeitada com103004enquanto uma Travel estiver iniciando, ativa ou terminando: sempre aguardeendTravel()primeiro. O SDK nunca descarta uma Travel ativa como efeito colateral deinitialize. - A experiência está vinculada ao ciclo de vida do host: chame
endTravelnoonDestroydaActivity/Fragment(ou noonCleareddo ViewModel) para garantir que a conexão em tempo real e os recursos sejam liberados. - Remova a View retornada por
attachVideo()do layout ao encerrar (container.removeAllViews()) e chameremoveListener. - O SDK mantém apenas o contexto da aplicação; da mesma forma, não passe uma Activity para o SDK.
10. Corrotinas e threads
- Os métodos de negócio são
suspend; chame-os emlifecycleScope/viewModelScopea partir de qualquer contexto de corrotina. O SDK coordena o estado e o trabalho RTC em seu dispatcher principal, enquanto o HTTP permanece fora da thread principal. - Se a corrotina chamadora for cancelada, o SDK cancela a solicitação HTTP em andamento dessa chamada, se houver, e propaga
CancellationExceptioninalterado em vez de convertê-lo paraSDKError; não o capture ou ignore como uma falha operacional. O cancelamento não reverte uma solicitação que o servidor já aceitou. - Chame
attachVideo()esendCommand()na thread principal; uma chamada fora da thread principal lança sincronicamenteIllegalStateException.
11. Gerenciamento de tokens
- A Bearer API Key tem um período de validade limitado; recomenda-se garantir que o token esteja atualizado antes de entrar em uma experiência. Ao receber
onError(101002)(token expirado), obtenha novamente a Bearer Key e chameupdateToken—não há necessidade de trocar por um novo ticket.
12. Recuperação de erros
- Para erros fatais: limpe o estado atual da experiência (incluindo a remoção da View de vídeo), notifique o usuário e permita o reinício.
- Para instabilidade de rede (
106001) e anomalias temporárias do serviço upstream (106003): um número limitado de tentativas pode ser realizado. - Um
100002síncrono da inicialização significa quemodelestá em branco; forneça o nome e a versão completos do modelo e inicialize novamente. Se ummodelnão vazio tiver o nome ou versão errados, tiver sido descontinuado, ainda não tiver sido publicado ou não estiver autorizado, o gateway normalmente retorna AccessDenied, mapeado para106003; useSDKError.rawe verifique se omodel, API Host, API Key, conta e região correspondem.
13. Adaptação de modo
- Use o
moderetornado porstartTravelpara decidir quais capacidades de interação expor: direção e atuação usam a instrução de textosendInstruct(a atuação também usaaspectRatiopara a orientação do jogador e oculta o retrocesso); o modo aventura usa o comando de controlesendCommand. - No modo aventura, você pode usar a sobrecarga
startTravel(ticket, maxExperienceTimeSec)para limitar a duração máxima desta experiência (segundos; a sessão termina automaticamente quando atingida). Os valores permitidos são configurados pelo servidor (atualmente60/90/120, padrão60); direção e atuação ignoram o valor (o servidor o ignora e ecoanull). Passar um valor não suportado faz com que o servidor retorne400000e esta inicialização falhe. Consulte a Referência da API para detalhes dos parâmetros.
atuação: Definindo a orientação do jogador a partir de aspectRatio
StartTravelData.aspectRatio é não-null apenas para atuação: "9:16" (retrato, o padrão do lado do servidor quando o mundo é criado) ou "16:9" (paisagem); é null para aventura e direção. A tela é fixada quando o mundo é criado (especificado pelo seu servidor através da Open API), portanto, para o cliente, é um resultado somente leitura. O SDK preserva valores não reconhecidos literalmente, então o host deve tratar qualquer valor que não reconheça como null e retornar à sua própria orientação padrão.
Temporização: decida a orientação do contêiner de reprodução após startTravel() retornar e antes de chamar attachVideo() e montar o SurfaceView retornado em seu layout. O SDK só começa a vincular e renderizar o fluxo remoto depois que a visualização do host é anexada, portanto, decidir a orientação nesse ponto ainda precede o primeiro quadro renderizado. O valor é entregue com o valor de retorno de startTravel() e não há garantia de que chegará antes do SDK entrar no canal de comunicação em tempo real — ele só precisa ser aplicado antes de attachVideo().
Consequência: a visualização remota é vinculada com um modo de renderização clip-to-fill — um contêiner cuja orientação discorda de aspectRatio corta a imagem (por exemplo, um fluxo em retrato 9:16 colocado em um contêiner 16:9 perde a maior parte de sua parte superior e inferior) em vez de aplicar letterboxing.
startTravel falha com 403007 (rejeitado antes que o Travel seja criado), que o SDK repassa literalmente. Não tente novamente este código como capacidade cheia; em vez disso, solicite a habilitação.14. Exemplo completo (trecho de ViewModel + Activity)
15. Guia de solução de problemas de DevOps
Quando algo dá errado durante a integração (não é possível entrar em um Travel, tela preta sem vídeo, queda de fluxo no meio da sessão, anomalias de pausa/retomada, ...), abrir os logs do SDK é a maneira mais rápida de localizar o problema. Este capítulo apresenta um fluxo padrão de solução de problemas — útil tanto para sua própria verificação quanto para nos fornecer informações suficientes em uma única interação.
15.1 Habilitando logs
Escolha uma saída de log conforme necessário durante a solução de problemas (consulte §8 Logging): para uma verificação rápida, defina logcatEnabled = true e leia-o com adb logcat, aumentando logLevel para DEBUG ou VERBOSE ao diagnosticar (o padrão INFO já carrega a linha do tempo completa do ciclo de vida; reduza para WARN para apenas erros); para alimentar seu próprio sistema, use logHandler para receber cada LogRecord (não afetado por logLevel) e grave-o em seu arquivo ou plataforma de crash.
15.2 ID de correlação da sessão: travelId
O travelId (ou seja, StartTravelData.encryptedTravelId) nos logs do SDK é emitido por completo. É o identificador único que percorre uma sessão e a chave da sessão enviada ao servidor. É a chave para alinhar os logs do cliente com os registros de sessão do lado do servidor — sempre inclua o travelId da sessão com falha ao relatar um problema.
15.3 Coletando logs
Ao reproduzir o problema, persista os logs do SDK em um arquivo:
15.4 O que incluir ao relatar um problema
Para evitar múltiplas interações, anexe o seguinte:
Item | Notas |
|---|---|
Versão do SDK |
|
Sessão | o |
Hora da ocorrência | a hora aproximada (nível de minuto é suficiente) |
Código de erro | o |
Etapas de reprodução | caminho da ação + resultado esperado + resultado real |
Ambiente | modelo do dispositivo, versão do Android, rede (Wi-Fi/celular) |
Arquivo de log | o log |
15.5 Sobre a ocultação de dados e o compartilhamento de logs
Os logs do SDK são projetados para serem seguros para compartilhamento: credenciais (token Bearer, ticket de Travel, token RTC), identificadores internos do RTC e URLs de mídia são ocultados antes de serem gravados, portanto, nunca aparecem em texto simples; travelId é um identificador de sessão (não uma credencial) e é mantido por completo apenas para correlação. Mesmo assim, recomendamos a transferência de arquivos de log por um canal confiável em vez de colá-los publicamente em plataformas não controladas.