Skip to main content

Guia de integração do HappyOyster Web SDK

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.

Este documento se destina a desenvolvedores frontend e full-stack. Ele explica como integrar o SDK de forma confiável em produção. Para obter detalhes de cada API, consulte a Referência da API.

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:
import { HappyOysterEngine, isSdkError } from "@happy-oyster/js-sdk";

const engine = new HappyOysterEngine({
  APIHost: "open-platform.example.com",
  model: "happyoyster-1.0-adventure", // Required; Adventure model shown as an example
  logLevel: "warn",
});

engine.updateToken(token);

const videoElement = document.querySelector("video") as HTMLVideoElement;
const travel = engine.createTravel({
  ticket,
  videoElement,
  maxExperienceTimeSec: 90, // Optional, Adventure only: 60 / 90 / 120
});

const offStatus = travel.on("statusChanged", (status) => {
  // Use status to drive loading states, disabled buttons, and player UI.
});

const offError = travel.onError((error) => {
  // Usually log, show a toast, and refresh the token if it has expired.
  if (isSdkError(error)) console.error(error.code, error.message);
});

try {
  await travel.start();
  // Enable controls or Directing input with travel.can(action) after the session is running.
} finally {
  offStatus();
  offError();
  await travel.end();
}
Este trecho cobre apenas o lado do SDK. A criação do mundo, a espera até que esteja pronto, a solicitação do 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, <video>, orquestração de sessões e chamadas ao SDK

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.

happy-oyster-overview.png

1.2 Fluxo da experiência

Etapa

Responsável

Ação

Descrição

① Criar um mundo

Backend da aplicação → HappyOyster OpenAPI

POST /openapi/v1/worlds

Retorna encryptedWorldId, status e firstFrame

② Aguardar até estar pronto

Backend da aplicação → HappyOyster OpenAPI

GET /openapi/v1/worlds/build-status

Consulte periodicamente até status === ready (ignore esta etapa se o mundo já estiver pronto na criação)

③ Obter uma credencial Travel

Backend da aplicação → HappyOyster OpenAPI

POST /openapi/v1/worlds/get-travel-credential

Retorna um ticket de uso único para enter-travel

④ Solicitar um token de chave de API temporária

Backend da aplicação → HappyOyster OpenAPI

POST /api/v1/tokens?expire_in_seconds=1800

Retorna um token de chave de API temporária. Não defina um prazo de validade muito curto, pois o token pode expirar antes do fim da experiência e exigir atualizações frequentes.

⑤ 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 token e ticket, ele inicia o fluxo do SDK

⑥ Entrar na experiência

Frontend da aplicação → HappyOyster SDK

Consulte “Subfluxo de inicialização do SDK” a seguir

new HappyOysterEngine/updateToken → createTravel → start()

1.3 Subfluxo de interação do SDK (detalhes da etapa ⑥)

1.3.1 Iniciar um Travel

travel-start-flow.png
Requisitos principais da ordem de chamadas

Passo

API

Descrição

1

new HappyOysterEngine()

Reutilize um Engine para o mesmo APIHost + model

2

updateToken()

Conclua antes de start()

3

createTravel()

videoElement é obrigatório

4

travel.on(...)

Registre os listeners antes de start()

5

await travel.start()

Entra em running após iniciar com sucesso

1.3.2 Jogar no modo Adventure

adventure-command-flow.png

1.3.3 Jogar no modo Directing / Acting

adventure-control-flow.png
A tabela a seguir resume as diferenças entre Adventure, Directing e Acting:

Modo

APIs principais

Uso típico

Pontos de atenção

Adventure (1)

sendCommand()

Controle em tempo real com teclado, joystick e botões

Envie somente após running; maxExperienceTimeSec se aplica apenas a este modo

Directing (2)

sendInstruct(), pause(), resume(), rewind()

Direção por linguagem natural e controle de reprodução

Pausar, retomar e retroceder dependem dos recursos da sessão; verifique travel.can(action) primeiro

Acting (3)

sendInstruct(), pause(), resume()

Experiências voltadas à atuação e configuração da proporção

Pausar e retomar dependem dos recursos da sessão; rewind() não está disponível e scriptlist não pode usar sendInstruct()

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 token de 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 APIHost do SDK deve conter apenas o host, como open-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

HappyOysterEngine

Configura APIHost e model, gerencia o token de chave de API temporária do Model Studio (updateToken) e cria sessões Travel

Travel

Representa uma sessão: start conecta ao RTC; sendCommand, sendInstruct e os métodos do ciclo de vida controlam a sessão

Estados da sessão (statusChanged):
idle ──start()──► prepare ──video playable──► running ⇄ paused ──end()──► idle
Três restrições (explicadas adiante):
  • Cada Engine pode ter apenas um Travel ativo por vez.
  • videoElement deve ser fornecido a createTravel.
  • 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 APIHost somente com o host da Open Platform, sem https://, esquema ou caminho, como open-platform.example.com.
  • Reutilize um HappyOysterEngine para o mesmo APIHost + model. Antes de trocar o host ou o modelo, encerre o Travel ativo e use um Engine configurado para o novo destino.
Recomendado
  • 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.
A tabela a seguir resume os campos de configuração comuns:

Campo

Obrigatório

Orientação

APIHost

Sim

Passe apenas o host, como open-platform.example.com; não inclua https:// nem um caminho

model

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 mode nem do ticket

token

Não

Você pode passá-lo no construtor ou defini-lo depois com updateToken(token); atualize tokens expirados também com updateToken

logLevel

Não

Use debug em desenvolvimento e warn ou none em produção

streamReadyTimeout

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

Evite
  • 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 informar APIHost.

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

sdk.updateToken(token)

Autentica as solicitações do SDK à Open Platform

Ticket Travel

Credencial Travel solicitada pelo backend da aplicação

createTravel({ ticket })

Credencial de uso único para uma sessão Travel

Obrigatório
  • Prepare as duas credenciais antes de travel.start().
  • O SDK não persiste nem atualiza automaticamente o token.
Recomendado
  • Se o token expirar ou um erro de heartbeat for recebido por onError, solicite um novo token pelo backend da aplicação e chame updateToken.
Evite
  • 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, e videoElement é fornecido nesse momento.
  • Registre statusChanged e onError antes de await travel.start() para observar todos os erros e as mudanças de estado.
Recomendado
  • Mostre uma interface de conexão durante prepare para evitar cliques duplicados. Use travelInfoReady para ler os metadados da sessão antecipadamente e firstFrameGenerated como imagem inicial provisória, quando disponível.
Evite
  • Criar um Travel antes de o elemento DOM estar pronto.

4.2 Durante a execução

  • Atualize a interface com base em statusChanged: prepare indica espera pelo vídeo, enquanto running indica que a interação está disponível.
  • Observe os casos de uso e as condições de pause, resume e rewind (dependem dos recursos da sessão; rewind também exige que a sessão esteja paused e 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.
Recomendado
  • 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.
Evite
  • Chamar createTravel uma 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 playsInline em <video> (obrigatório no iOS).
  • Entenda como as políticas de reprodução automática do navegador afetam autoPlay e muted.
Recomendado
  • Durante prepare, mostre a imagem do primeiro quadro como sobreposição; oculte-a quando a sessão entrar em running.
  • Configure streamReadyTimeout conforme 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.
Evite
  • 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á paused ou 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 a HappyOysterEngine.
  • Salve as funções de cancelamento de assinatura retornadas por travel.on(...) e travel.onError(...).
Recomendado
  • Centralize o registro e a limpeza dos listeners. Remova os listeners antigos antes de trocar de sessão Travel.

Evento

Finalidade

statusChanged

Exibe o estado, detecta se o vídeo está pronto (running) e habilita ou desabilita botões

travelInfoReady

Lê encryptedTravelId, modo, primeiro quadro, duração da experiência e proporção do Acting antes da conexão RTC; travel.getInfo() retorna os mesmos dados

firstFrameGenerated

Quando existe um primeiro quadro não vazio, ocorre após travelInfoReady; use-o como imagem provisória durante prepare

error (via onError)

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.
Evite
  • Capturar apenas erros de start() sem escutar onError.
  • 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:
await travel.sendCommand({ interaction: "Jump" });
Ações contínuas Continue chamando 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:
// Keep calling while the control is pressed
void travel.sendCommand({ translation: "Front" });

// Stop moving on release
void travel.sendCommand({ translation: "None" });
Evite
  • Enviar muitos comandos durante prepare.
  • Usar sendCommand para 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 seja scriptlist; chame await travel.sendInstruct({ content }).
Recomendado
  • Verifique se content nã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

APIHost foi passado como URL completa, por exemplo com https:// ou um caminho

Passe apenas o host, como open-platform.example.com

travel.start() falha porque o ticket é inválido ou já foi usado

ticket é de uso único; pode ter expirado, sido reutilizado ou emitido antes de o mundo estar pronto

Solicite um novo ticket ao backend; verifique se o mundo está pronto antes de entrar

onError informa um erro de autenticação após a sessão estar em execução

O token de chave de API temporária do Model Studio expirou

Solicite um novo token ao backend e chame engine.updateToken(newToken)

O player continua carregando ou start() excede o tempo limite

O fluxo remoto não está pronto, a rede está lenta ou streamReadyTimeout é muito curto

Ofereça uma ação para tentar novamente; aumente streamReadyTimeout se necessário; verifique os logs do backend e do RTC

Uma segunda chamada a createTravel() falha porque já existe um Travel ativo

O Travel anterior não foi encerrado

Chame await travel.end() e limpe os listeners ao sair, tentar novamente ou trocar de sessão

Os controles ou as instruções não têm efeito

A sessão não está running ou a API usada não corresponde ao modo atual Adventure, Directing ou Acting

Controle a disponibilidade dos botões com base em statusChanged; chame travel.can(action) antes de ações que dependem do modo

Ao depurar, registre três informações em conjunto: o 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.