HappyOysterEngine configura o host e o modelo da Open Platform, atualiza o token temporário de chave de API do Model Studio e cria sessões Travel. Travel é o objeto de sessão retornado por createTravel(); a sessão é acessada e iniciada somente após chamar travel.start(). Suporta os modos adventure, directing e acting.
HappyOysterEngine configura o host da Open Platform, atualiza o token temporário de chave de API do Model Studio e cria sessões Travel.
Travel é o objeto de sessão retornado por createTravel(). A sessão é acessada e iniciada somente após travel.start() ser chamado.
Terminologia Principal
Termo | Significado | Observações |
|---|---|---|
token | Token temporário de chave de API do Model Studio: ao chamar serviços do Model Studio a partir de ambientes não confiáveis, como navegadores ou aplicativos móveis, gere uma chave de API temporária por meio de um backend seguro para evitar a exposição de uma chave de API permanente. O SDK envia este token para a Open Platform como uma credencial HTTP Bearer. | |
ticket | Credencial de Travel do mundo HappyOyster: seu backend chama a API de credenciais usando autenticação AK (cabeçalho do gateway) para obter uma credencial de Travel de curta duração ( |
Visão geral
O SDK fornece os seguintes objetos principais:
HappyOysterEngine
API | Descrição |
|---|---|
| Cria uma instância do Engine. |
| Atualiza o token de chave de API temporária do Model Studio usado pelas solicitações subsequentes à API da Open Platform. |
| Cria uma sessão Travel. |
| A versão atual do SDK. |
| O nome do pacote SDK atual, versão e canal do pacote. |
Viagem
API | Descrição |
|---|---|
| Inicia a sessão Travel atual. |
| Inscreve-se nas alterações de status da sessão. |
| Inscreve-se nas notificações de URL do primeiro quadro. |
| Inscreve-se nos metadados da sessão disponíveis imediatamente após entrar no travel. |
| Inscreve-se nos erros de tempo de execução da sessão. |
| Verifica se a ação especificada pode ser chamada atualmente. |
| Obtém metadados da sessão disponíveis; retorna |
| Envia um comando de controle em tempo real. |
| Envia instruções de Direção ou conteúdo de prompt. |
| Pausa a sessão atual. |
| Retoma uma sessão pausada. |
| Retrocede uma sessão de Direção para o tempo especificado. |
| Encerra a sessão atual e libera seus recursos. |
Outras Exportações
Exportação | Descrição |
|---|---|
| O objeto constante de códigos de erro exportado pelo SDK. |
| Verifica se um erro desconhecido é um erro padrão do SDK. |
Tipos | Tipos públicos como |
Exemplo
HappyOysterEngine
HappyOysterEngine é o ponto de entrada do Web SDK. Ele configura o host da Open Platform, gerencia o token temporário de chave de API do Model Studio usado pelas solicitações subsequentes e cria sessões Travel.
Travel ativo por vez. Encerre o Travel atual antes de iniciar uma nova sessão.Depois que um token é definido no construtor ou por meio de updateToken(), o SDK busca internamente a configuração do Feature Gate. Isso permite que a plataforma desative remotamente o SDK ou exija que versões mais antigas sejam atualizadas. Se a solicitação falhar, o SDK falha de forma aberta e não bloqueia a experiência normal.API | Descrição |
|---|---|
| Cria uma instância de Engine com o host de API e o modelo obrigatórios, além de token e nível de log opcionais. |
| Atualiza o token de chave de API temporária do Model Studio usado pelas solicitações subsequentes à Open Platform. |
| Cria uma sessão Travel que ainda não foi iniciada. |
new HappyOysterEngine
Cria uma instância de HappyOysterEngine.
Assinatura
Parâmetros
SDKConfig
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Host da API da Open Platform. Deve ser um host simples, como |
|
| Sim | Identificador do modelo da Open Platform a ser usado. Obrigatório, sem valor padrão. Fixo para este Engine e compartilhado por todos os seus Travels. |
|
| Não | Token temporário de chave de API do Model Studio definido durante a construção. Também pode ser definido posteriormente com |
|
| Não | Nível de log do SDK. O padrão é |
|
| Não | Tempo limite para aguardar |
model como um identificador de modelo, como happyoyster-1.0-adventure, um modelo Adventure. Use o identificador de modelo para o ambiente de serviço de destino. O SDK não escolhe um modelo a partir do mode da experiência nem o infere a partir do ticket.
Um Engine possui um APIHost + model fixo. Reutilize-o para Travels sucessivos direcionados ao mesmo serviço e modelo. Antes de alternar qualquer um dos valores, encerre o Travel ativo e use um Engine configurado para o novo alvo. Crie o mundo e emita seu ticket para o mesmo alvo de serviço.
Retornos
Retorna uma instância de HappyOysterEngine.
Erros
Se config estiver ausente, ou se APIHost, model, token, logLevel ou streamReadyTimeout tiver um tipo ou valor inválido, um SdkError com código ErrorCode.INVALID_ARGUMENT (10010001) será lançado sincronamente. Passar uma URL completa, uma string vazia ou um valor com caminho como APIHost é inválido.
model é obrigatório e deve ser uma string não vazia após remoção de espaços; null, valores não string e strings contendo apenas espaços em branco são inválidos. Omiti-lo ou passar undefined também gera um erro de argumento; o SDK não possui modelo padrão.
HappyOysterEngine.updateToken
Atualiza o token de chave de API temporária do Model Studio usado pelas solicitações subsequentes à API da Open Platform.
Assinatura
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Token de chave de API temporária do Model Studio. Passar uma string em branco limpa o token atual. |
Retornos
Não retorna nada.
Erros
Se token não for uma string, um SdkError com código ErrorCode.INVALID_ARGUMENT (10010001) será lançado sincronamente.
HappyOysterEngine.createTravel
Cria uma instância de sessão Travel sem iniciá-la.
Assinatura
Parâmetros
CreateTravelConfig
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Ticket usado para iniciar o Travel posteriormente. |
|
| Sim | O elemento |
|
| Não | Duração máxima da experiência Adventure, em segundos. As sessões Directing e Acting ignoram este campo. Quando omitido, o servidor aplica seu valor padrão. |
Retornos
Retorna uma sessão Travel criada, mas ainda não iniciada. O chamador deve então executar await travel.start() para entrar na sessão e aguardar até que o vídeo se torne reproduzível.
Cada instância de HappyOysterEngine pode ter apenas um Travel ativo por vez. Chame await travel.end() antes de criar outro Travel.
Erros
createTravel() lança um SdkError sincronamente nos seguintes casos:
ErrorCode | Descrição |
|---|---|
|
|
| Um Travel já está ativo; chame |
travel.start().
Travel
Travel representa uma sessão criada por HappyOysterEngine.createTravel(). Ela está inicialmente inativa. Após travel.start() ser chamado, o SDK entra na sessão e aguarda até que o vídeo se torne reproduzível.
Travel suporta iniciar, pausar, retomar, retroceder e encerrar uma sessão; enviar controles e prompts em tempo real; e inscrever-se em alterações de status e erros de tempo de execução.
Métodos
Método | Descrição |
|---|---|
| Inicia a sessão Travel atual. |
| Inscreve-se nas alterações de status da sessão. |
| Inscreve-se nas notificações de URL do primeiro quadro. |
| Inscreve-se nos metadados da sessão disponíveis imediatamente após entrar no travel. |
| Inscreve-se nos erros de tempo de execução da sessão. |
| Verifica se a ação especificada pode ser chamada atualmente. |
| Obtém metadados da sessão disponíveis; retorna |
| Envia um comando de controle em tempo real. |
| Envia instruções de Direção ou conteúdo de prompt. |
| Pausa a sessão atual. |
| Retoma uma sessão pausada. |
| Retrocede a sessão atual para o tempo especificado. |
| Encerra a sessão atual e libera seus recursos. |
Status
Status | Descrição |
|---|---|
| A sessão não foi iniciada. |
| A sessão está iniciando e aguardando o vídeo ficar reproduzível. |
| A sessão está em execução. |
| A sessão está pausada e pode ser retomada ou retrocedida. |
| A sessão terminou normalmente e seus recursos foram liberados. |
Eventos
Inscreva-se em eventos com travel.on(event, handler). O método retorna uma função de cancelamento de inscrição.
Evento | Callback | Descrição |
|---|---|---|
|
| O status da sessão foi alterado. |
|
| Emitido durante |
|
| Emitido após o retorno de enter-travel e antes da conexão RTC. |
|
| Um erro de runtime da sessão. |
Travel.can
Verifica se uma ação está disponível para o status atual e capacidade da sessão.
Assinatura
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Ação a verificar: |
Retornos
Retorna um boolean. true significa que a ação está disponível no momento; false significa que o status atual, modo ou capacidade da sessão não atende às suas pré-condições.
Disponibilidade
action | Disponibilidade |
|---|---|
| Travel ainda está |
|
|
|
|
|
|
|
|
|
|
| A Travel não foi fechada. |
Erros
Este método não lança erros de negócio. Ações desconhecidas retornam false.
Travel.start
Inicia a sessão Travel atual.
Assinatura
Parâmetros
Sem parâmetros.
Retornos
Retorna um Promise<StartTravelResult>, que é resolvido após o início da sessão e quando o vídeo se torna reproduzível.
Após o retorno de enter-travel, o SDK emite travelInfoReady antes de conectar o RTC. Assinantes tardios podem chamar travel.getInfo(); ele retorna null antes que os metadados estejam disponíveis. Se a resposta incluir um firstFrame não vazio, firstFrameGenerated ainda será emitido.
StartTravelResult
Campo | Tipo | Descrição |
|---|---|---|
|
| ID da sessão Travel atual. |
|
| Modo de sessão: |
|
| Modelo de criação de Mundo; valores comuns são |
|
| URL da imagem do primeiro quadro; |
|
| Duração máxima da experiência Adventure, em segundos. |
|
| Proporção de aspecto da Atuação; |
Erros
start() é rejeitado e emite um evento error nos seguintes casos. Use isSdkError(err) para verificar o erro e ler err.code e err.message.
ErrorCode | Descrição |
|---|---|
| Recurso do SDK está desabilitado ( |
| Não foi possível iniciar: o status atual não permite, a Open Platform não está configurada ou a entrada na sessão falhou |
| Não foi possível iniciar: a configuração da sessão retornada pelo servidor está incompleta |
| Não foi possível iniciar: falha na conexão do fluxo de vídeo ou falha na solicitação de sinalizador de recurso do SDK |
| Não foi possível iniciar: tempo limite esgotado ao aguardar o stream de vídeo (usa o maior valor entre |
| Não foi possível iniciar: tempo limite esgotado ao aguardar o vídeo tornar-se reproduzível (controlado por |
| Erro de parâmetro, recurso ou servidor da Open Platform |
Travel.on("statusChanged")
Inscreve-se nas alterações de status da sessão.
Assinatura
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Callback invocado quando o status é alterado. |
Retornos
Retorna uma função de cancelamento de inscrição. TravelStatus é um dos seguintes: idle / prepare / running / paused / completed.
Erros
Este método não lança erros de negócio.
Travel.on("firstFrameGenerated")
Inscreve-se nas notificações de URL do primeiro quadro.
Assinatura
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Callback invocado quando a URL do primeiro quadro está disponível. |
Retornos
Retorna uma função de cancelamento de inscrição.
Comportamento
Emitido apenas durante travel.start(). Depois que o SDK chama o enter-travel da Open Platform e recebe um firstFrame não vazio, ele emite o evento imediatamente — geralmente após statusChanged("prepare"), mas antes de start() ser resolvido e o vídeo tornar-se reproduzível. O evento não é emitido se a resposta não contiver uma URL de primeiro quadro.
Erros
Este método não lança erros de negócio.
Travel.onError
Inscreve-se nos erros de tempo de execução da sessão.
Assinatura
Parâmetros
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Callback invocado quando ocorre um erro de tempo de execução. |
Retornos
Retorna uma função de cancelamento de inscrição. Use isSdkError para restringir o objeto de erro a SdkError.
Erros
Este método não lança erros de negócio.
Travel.sendCommand
Envia um comando de controle em tempo real.
Assinatura
Parâmetros
AdventureCommand
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Não | Direção do movimento. O padrão é |
|
| Não | Rotação da visualização. O padrão é |
|
| Não | Ação de interação. O padrão é |
Referência de Comandos de Controle
translation — Direção de Movimento
Descreve o movimento do personagem, suportando oito direções e combinações.
Valor | Direção |
|---|---|
| Frente |
| Para trás |
| Esquerda |
| Direita |
| Frente-esquerda |
| Frente-direita |
| Trás-esquerda |
| Trás-direita |
| Parado |
rotation — Rotação da Visualização
Simula a rotação da visualização baseada no mouse em oito direções.
Valor | Direção |
|---|---|
| Cima |
| Baixo |
| Esquerda |
| Direita |
| Cima-esquerda |
| Cima-direita |
| Baixo-esquerda |
| Baixo-direita |
| None |
interaction — Ação de Interação
Valor | Ação |
|---|---|
| Pular |
| Atacar |
| Agachar |
| Correr |
| None |
Retornos
Retorna um Promise<void> que é resolvido após o envio do comando.
Erros
sendCommand() é rejeitado nos seguintes casos:
ErrorCode | Descrição |
|---|---|
|
|
| O status atual ou o modo da sessão não permite comandos, ou o comando do fluxo de vídeo falhou |
Travel.sendInstruct
Envia instruções de Direção ou conteúdo de prompt.
Assinatura
Parâmetros
InstructData
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Conteúdo do prompt a ser enviado. |
Retornos
Retorna um Promise<void> que é resolvido após a Open Platform receber e processar a instrução.
Erros
sendInstruct() é rejeitado e emite um evento error nos seguintes casos:
ErrorCode | Descrição |
|---|---|
| A sessão não foi iniciada |
| Falha ao enviar a instrução de Direção |
| Erro de parâmetro, recurso ou servidor da Open Platform |
Travel.pause
Pausa a sessão atual.
Assinatura
Parâmetros
Sem parâmetros.
Retornos
Retorna um Promise<void> que é resolvido após a parada da reprodução do vídeo.
Erros
pause() é rejeitado nos seguintes casos:
ErrorCode | Descrição |
|---|---|
| O status atual, o modo de sessão ou a capacidade da sessão não permite pausar, ou a solicitação de pausa falhou |
| Tempo esgotado ao aguardar o backend relatar o fluxo de vídeo como pausado (15 segundos) |
| Erro de parâmetro, recurso ou servidor da Open Platform |
Travel.resume
Retoma uma sessão pausada.
Assinatura
Parâmetros
Sem parâmetros.
Retornos
Retorna um Promise<void> que é resolvido após o vídeo ficar reproduzível novamente.
Erros
resume() é rejeitado nos seguintes casos:
ErrorCode | Descrição |
|---|---|
| O status atual, o modo de sessão ou a capacidade da sessão não permite retomar, ou a solicitação de retomada falhou |
| Tempo esgotado ao aguardar o vídeo ficar reproduzível novamente (15 segundos) |
| Erro de parâmetro, recurso ou servidor da Open Platform |
Travel.rewind
Retrocede a sessão atual para o tempo especificado.
Assinatura
Parâmetros
RewindTravelParams
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | Tempo alvo em segundos. Apenas múltiplos de 4 são suportados (por exemplo, |
Retornos
Retorna um Promise<RewindTravelResult> que é resolvido após a conclusão do retrocesso e a retomada da reprodução.
RewindTravelResult
Campo | Tipo | Descrição |
|---|---|---|
|
| O tempo real em segundos em que o servidor retomou a reprodução. |
Erros
rewind() é rejeitado e emite um evento error nos seguintes casos:
ErrorCode | Descrição |
|---|---|
| A sessão não foi iniciada |
| Não foi possível retroceder: a sessão deve primeiro ser pausada e a reprodução do vídeo interrompida, ou a solicitação de retrocesso ou reconexão RTC falhou |
| Tempo esgotado ao aguardar a retomada do vídeo após retrocesso (15 segundos) |
| Erro de parâmetro, recurso ou servidor da Open Platform |
Travel.end
Encerra a sessão atual e libera seus recursos.
Assinatura
Parâmetros
Sem parâmetros.
Retornos
Retorna um Promise<void> que é resolvido após a conclusão da limpeza.
Erros
Erros de limpeza não são lançados para o chamador; end() faz o melhor esforço para liberar recursos.
Tratamento de Erros
O SDK expõe erros de tempo de execução por meio de rejeições de Promise ou eventos error. Os erros são objetos SdkError; use isSdkError(err) e leia err.code e err.message.
Erros reconhecidos da Open Platform mapeiam para o intervalo 10000001–10000012, e err.message contém a mensagem da plataforma. Consulte a seção Erros de cada API Travel para obter códigos específicos do método.
Referência de ErrorCode
Intervalos de códigos de erro:
100000xx: Erros mapeados da Open Platform1001xxxx: Erros do cliente Engine1002xxxx: Erros do cliente Travel
code | name | Descrição |
|---|---|---|
|
| Parâmetros de solicitação inválidos (retornados pela Open Platform) |
|
| Recurso não encontrado (Travel ausente, não possuído, em outro workspace ou artefato não pronto) |
|
| O Mundo não existe, foi excluído ou não pertence ao desenvolvedor atual |
|
| Erro do sistema |
|
| O ticket é inválido ou expirou |
|
| O ticket já foi usado (credencial de uso único) |
|
| O Mundo não está pronto e não pode ser acessado |
|
| Falha na alocação de recursos de inferência (capacidade insuficiente, falha na criação de stream, falha na inicialização da sessão, etc.) |
|
| Esta API aceita apenas a chave de API primária (chaves de API temporárias não são suportadas) |
|
| Entrada rejeitada pela moderação de conteúdo |
|
| A imagem de entrada viola direitos autorais ou política de propriedade intelectual |
|
| A solicitação entra em conflito com o estado atual do recurso |
|
| Falha na validação de argumento do cliente SDK (não mapeado da Open Platform) |
|
| Recurso do SDK está desativado |
|
| Uma Travel já está ativa |
|
| Fluxo de vídeo desconectado durante a reprodução |
|
| Falha na solicitação de início da sessão |
|
| Configuração do fluxo de vídeo ausente durante a inicialização |
|
| Falha na conexão do fluxo de vídeo |
|
| Tempo esgotado ao aguardar o fluxo de vídeo |
|
| Tempo esgotado ao aguardar o vídeo ficar reproduzível |
|
| Falha na solicitação de pausa |
|
| Tempo esgotado ao aguardar a pausa do vídeo |
|
| Falha na solicitação de retomada |
|
| Tempo esgotado ao aguardar a retomada do vídeo |
|
| Falha na solicitação de retrocesso |
|
| Tempo esgotado ao aguardar a retomada do vídeo após retrocesso |
|
| Falha ao enviar o comando de controle em tempo real |
|
| Falha ao enviar a instrução de Direção |
|
| Falha na solicitação de encerramento da sessão |
Outras Exportações
Exportações de runtime
Exportação | Tipo | Descrição |
|---|---|---|
|
| Cliente SDK que configura a Open Platform, atualiza o token e cria sessões Travel. |
|
| A versão atual do SDK. |
|
| O nome do pacote SDK atual, versão e canal do pacote. |
|
| O objeto constante de códigos de erro exportado pelo SDK. |
|
| Verifica se um erro desconhecido é um erro padrão do SDK. |
ErrorCode
O objeto constante de códigos de erro exportado pelo SDK. Compare-o com SdkError.code em vez de espalhar literais numéricos pelo código da aplicação.
isSdkError
Verifica se um erro desconhecido é um erro padrão do SDK. Quando retorna true, o TypeScript restringe o erro a SdkError, permitindo acesso seguro a code e message.
Tipos Públicos
Os seguintes tipos são exportados do ponto de entrada do pacote e podem ser importados diretamente de @happy-oyster/js-sdk. Eles existem apenas no tempo de compilação do TypeScript e não produzem código de tempo de execução.
Tipo | Descrição |
|---|---|
| Tipo de parâmetro do construtor |
| Níveis de log do SDK: |
| Metadados do pacote SDK: |
| Canais de pacote SDK: |
| Tipo de parâmetro de |
| Metadados da sessão |
| Metadados da sessão usados por |
| Proporção de aspecto da Atuação: |
| Contrato de sessão pública |
| Estados locais da sessão SDK: |
| Nomes de ação suportados por |
| Tipo de parâmetro de |
| Tipo de parâmetro de |
| Tipo de parâmetro de |
| Dados de |
| Estrutura de erro do SDK contendo |
| Tipo de erro combinando |
| União de todos os valores de código de erro no objeto |