Este documento se destina a desenvolvedores frontend e full-stack e explica como integrar o HappyOyster Web SDK de forma confiável em produção nos modos Adventure, Directing e Acting.
0. Exemplo mínimo de integração
Se o backend já retornou um token de chave de API temporária do Model Studio e um ticket de Travel, o fluxo do SDK no frontend é o seguinte:
ticket e a solicitação do token de chave de API temporária do Model Studio devem ocorrer no backend da aplicação ou por meio dele.
1. Visão geral do fluxo completo
Uma experiência completa envolve principalmente os componentes a seguir.
1.1 Componentes
Componente | Responsabilidade |
|---|---|
Frontend da aplicação | UI, |
Backend da aplicação | Armazena a chave de API principal, chama as APIs de mundo da Open Platform em nome do cliente e emite credenciais temporárias do Model Studio |
HappyOyster OpenAPI | Disponibiliza as APIs necessárias para o modelo de mundo HappyOyster. |
HappyOyster SDK | SDK usado pelo frontend da aplicação. Ele gerencia principalmente as sessões Travel e o acesso ao fluxo de vídeo no cliente. |

1.2 Fluxo da experiência
Etapa | Responsável | Ação | Descrição |
|---|---|---|---|
① Criar um mundo | Backend da aplicação → HappyOyster OpenAPI |
| Retorna |
② Aguardar até estar pronto | Backend da aplicação → HappyOyster OpenAPI |
| Consulte periodicamente até |
③ Obter uma credencial Travel | Backend da aplicação → HappyOyster OpenAPI |
| Retorna um |
④ Solicitar um token de chave de API temporária | Backend da aplicação → HappyOyster OpenAPI |
| Retorna um |
⑤ Entregar o token de chave de API temporária e a credencial Travel | Frontend da aplicação → backend da aplicação → frontend da aplicação | Solicitar uma chave de API temporária e uma credencial Travel | Depois que o frontend recebe |
⑥ Entrar na experiência | Frontend da aplicação → HappyOyster SDK | Consulte “Subfluxo de inicialização do SDK” a seguir |
|
1.3 Subfluxo de interação do SDK (detalhes da etapa ⑥)
1.3.1 Iniciar um Travel

Passo | API | Descrição |
|---|---|---|
1 |
| Reutilize um Engine para o mesmo |
2 |
| Conclua antes de |
3 |
|
|
4 |
| Registre os listeners antes de |
5 |
| Entra em |
1.3.2 Jogar no modo Adventure

1.3.3 Jogar no modo Directing / Acting

Modo | APIs principais | Uso típico | Pontos de atenção |
|---|---|---|---|
Adventure ( |
| Controle em tempo real com teclado, joystick e botões | Envie somente após |
Directing ( |
| Direção por linguagem natural e controle de reprodução | Pausar, retomar e retroceder dependem dos recursos da sessão; verifique |
Acting ( |
| Experiências voltadas à atuação e configuração da proporção | Pausar e retomar dependem dos recursos da sessão; |
1.4 Práticas do backend da aplicação (resumo)
No backend, siga rigorosamente estas regras:
- Mantenha a chave de API principal somente no backend da aplicação. O navegador deve receber apenas um
tokende curta duração (demo:POST /server-api/temp-api-key). - Solicite as credenciais Travel pelo backend. Autorize o mundo e o usuário antes de emitir o
ticket; não o fixe no código nem o mantenha em cache de longo prazo no frontend. - Não emita uma credencial antes de o mundo estar
ready. Caso contrário, enter-travel pode falhar ou oferecer uma experiência incompleta. - Aponte o backend da aplicação e o SDK para o mesmo ambiente Open Platform. O backend pode usar uma URL OpenAPI completa; o
APIHostdo SDK deve conter apenas o host, comoopen-platform.example.com.
2. Conceitos principais do SDK
No fluxo descrito na seção 1, o SDK é responsável apenas por “entrar no Travel → reproduzir → controlar → encerrar”. Há dois objetos principais:
Objeto | Finalidade |
|---|---|
| Configura |
| Representa uma sessão: |
statusChanged):
- Cada Engine pode ter apenas um Travel ativo por vez.
videoElementdeve ser fornecido acreateTravel.- O token de chave de API temporária do Model Studio e o ticket Travel têm finalidades diferentes (consulte as etapas ④–⑤ da seção 1.2 e a seção 3.2).
3. Inicialização e gerenciamento de tokens
3.1 Instanciação do Engine
Obrigatório
- Configure
APIHostsomente com o host da Open Platform, semhttps://, esquema ou caminho, comoopen-platform.example.com. - Reutilize um
HappyOysterEnginepara o mesmoAPIHost + model. Antes de trocar o host ou o modelo, encerre o Travel ativo e use um Engine configurado para o novo destino.
- Use
logLevel: 'debug'em desenvolvimento e'warn'ou'none'em produção. - Crie o Engine na camada de orquestração de sessões, em vez de construir um novo a cada início.
Campo | Obrigatório | Orientação |
|---|---|---|
| Sim | Passe apenas o host, como |
| Sim | Obrigatório, sem valor padrão; mantenha-o alinhado ao modelo do backend usado para criar o mundo e emitir seu ticket. É fixo para o Engine e não é inferido de |
| Não | Você pode passá-lo no construtor ou defini-lo depois com |
| Não | Use |
| Não | Aumente o valor se a rede ou a preparação da renderização estiver lenta; ofereça uma forma de tentar novamente após o timeout |
- Chamar
new HappyOysterEngine()repetidamente durante a renderização ou em um trecho de execução frequente. - Passar uma URL completa, por exemplo com
https://, ou chamar APIs de backend do SDK sem informarAPIHost.
3.2 Modelo de duas credenciais
Corresponde às etapas ③–⑤ da seção 1.2:
Credencial | Origem | Como configurar | Finalidade |
|---|---|---|---|
Token de chave de API temporária do Model Studio | Chave de curta duração emitida pelo backend da aplicação |
| Autentica as solicitações do SDK à Open Platform |
Ticket Travel | Credencial Travel solicitada pelo backend da aplicação |
| Credencial de uso único para uma sessão Travel |
- Prepare as duas credenciais antes de
travel.start(). - O SDK não persiste nem atualiza automaticamente o token.
- Se o token expirar ou um erro de heartbeat for recebido por
onError, solicite um novo token pelo backend da aplicação e chameupdateToken.
- Confundir as duas credenciais.
- Expor a chave de API principal no frontend da aplicação.
4. Ciclo de vida do Travel
4.1 Criar e iniciar
Obrigatório
- Chame
createTravel({ ticket, videoElement });ticketé a credencial Travel de uso único, evideoElementé fornecido nesse momento. - Registre
statusChangedeonErrorantes deawait travel.start()para observar todos os erros e as mudanças de estado.
- Mostre uma interface de conexão durante
preparepara evitar cliques duplicados. UsetravelInfoReadypara ler os metadados da sessão antecipadamente efirstFrameGeneratedcomo imagem inicial provisória, quando disponível.
- Criar um Travel antes de o elemento DOM estar pronto.
4.2 Durante a execução
- Atualize a interface com base em
statusChanged:prepareindica espera pelo vídeo, enquantorunningindica que a interação está disponível. - Observe os casos de uso e as condições de
pause,resumeerewind(dependem dos recursos da sessão;rewindtambém exige que a sessão estejapausede que o fluxo tenha parado).
4.3 Encerrar e recriar
Obrigatório
- Encerre a sessão com
await travel.end(). - Verifique se o Travel anterior terminou antes de criar um novo.
- Chame
travel.end()durante a limpeza ao descarregar a página ou mudar de rota.
- Após uma falha, siga “encerrar → remover listeners → tentar novamente a partir da etapa ③ ou ⑤ da seção 1.2”.
- Solicite uma nova credencial Travel ao tentar novamente se a credencial for de uso único.
- Chamar
createTraveluma segunda vez sem encerrar o primeiro Travel; isso lança uma exceção de forma síncrona. - Sair da página sem limpeza, causando vazamento de recursos RTC.
5. Elemento de vídeo e políticas do navegador
Obrigatório
- Defina
playsInlineem<video>(obrigatório no iOS). - Entenda como as políticas de reprodução automática do navegador afetam
autoPlayemuted.
- Durante
prepare, mostre a imagem do primeiro quadro como sobreposição; oculte-a quando a sessão entrar emrunning. - Configure
streamReadyTimeoutconforme necessário (padrão: 15.000 ms) e ofereça uma ação para tentar novamente após o timeout. - Reserve uma proporção fixa para o contêiner do player.
- Passar uma referência ao elemento de vídeo antes de ele ser anexado ao DOM.
- Manter a interface interativa enquanto a sessão está
pausedou o fluxo está desconectado.
6. Assinaturas de eventos e tratamento de erros
6.1 Assinaturas de eventos
Obrigatório
- Os eventos pertencem a
Travel, não aHappyOysterEngine. - Salve as funções de cancelamento de assinatura retornadas por
travel.on(...)etravel.onError(...).
- Centralize o registro e a limpeza dos listeners. Remova os listeners antigos antes de trocar de sessão Travel.
Evento | Finalidade |
|---|---|
| Exibe o estado, detecta se o vídeo está pronto ( |
| Lê |
| Quando existe um primeiro quadro não vazio, ocorre após |
| Registro de logs, notificações toast e acionamento da atualização do token |
6.2 Camadas de erros
- Falhas na inicialização:
travel.start()é rejeitado (enter-travel / RTC / timeout). - Erros em tempo de execução: informados por
travel.onError(erros RTC, falhas de autenticação de heartbeat e outros). - Erros do backend da aplicação e da Open Platform nas etapas ①–④ da seção 1.2 são tratados pela camada da aplicação e não chegam ao SDK.
- Capturar apenas erros de
start()sem escutaronError. - Registrar listeners repetidamente sem cancelar as assinaturas.
7. Envio de instruções: Command e Instruct
7.1 sendCommand (controle em tempo real)
sendCommand() oferece controle em tempo real no modo Adventure (1). Envia comandos pelo RTC DataChannel e está disponível apenas enquanto a sessão está running.
O SDK envia no máximo um comando aproximadamente a cada 42 ms (cerca de 24 FPS). Se um ciclo já passou desde o envio anterior, o novo comando é enviado imediatamente. Se sendCommand() for chamado várias vezes no mesmo ciclo, apenas o comando completo da última chamada é enviado. translation, rotation e interaction são dimensões de controle independentes. Campos omitidos são enviados como None; o SDK não mescla campos entre chamadas, não repete periodicamente o comando anterior e não envia None automaticamente.
Ações pontuais
Chame sendCommand() uma vez para ações pontuais, como pular ou atacar:
sendCommand() enquanto o controle de movimento ou de rotação contínua da visão estiver pressionado. A aplicação frontend não precisa limitar as chamadas a 42 ms; o SDK agrupa chamadas de alta frequência em uma taxa de saída de cerca de 24 FPS. Ao soltar o controle, envie None explicitamente para redefini-lo:
- Enviar muitos comandos durante
prepare. - Usar
sendCommandpara instruções de Directing em linguagem natural.
7.2 sendInstruct (instruções de direção)
Obrigatório
- Use uma sessão Directing (
2) ou uma sessão Acting (3) que não sejascriptlist; chameawait travel.sendInstruct({ content }).
- Verifique se
contentnão está vazio antes de enviar e impeça envios duplicados. - Forneça feedback ao usuário com base em campos retornados, como
accepted.
8. Solução de problemas
Sintoma | Causa comum | O que fazer |
|---|---|---|
A inicialização do SDK falha com um erro de argumento |
| Passe apenas o host, como |
|
| Solicite um novo |
| O | Solicite um novo token ao backend e chame |
O player continua carregando ou | O fluxo remoto não está pronto, a rede está lenta ou | Ofereça uma ação para tentar novamente; aumente |
Uma segunda chamada a | O Travel anterior não foi encerrado | Chame |
Os controles ou as instruções não têm efeito | A sessão não está | Controle a disponibilidade dos botões com base em |
ErrorCode do SDK, o TravelStatus atual e os logs de solicitações do backend. Isso normalmente indica se o problema está relacionado a credenciais, estado, rede ou renderização.