Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

HappyOyster Referência da API do SDK da Web

HappyOysterEngine configura o host e o modelo da plataforma aberta, atualiza o QwenCloud token de chave de API temporário e cria sessões de viagem. Travel é o objeto de sessão retornado por createTravel(); a sessão é inserida e iniciada somente após chamar travel.start(). Suporta os modos de aventura, direção e atuação.

HappyOysterEngine configura o host Open Platform, atualiza o QwenCloud token de chave de API temporário e cria sessões de viagem.

Travel é o objeto de sessão retornado por createTravel(). A sessão é inserida e iniciada somente após travel.start() é chamado.

Terminologia Básica

<table><colgroup><col style={{ width: "20%" }} /><col style={{ width: "60%" }} /><col style={{ width: "20%" }} /></colgroup><thead><tr><th> Prazo </th><th> Significado </th><th> Notas </th></tr></thead><tbody><tr><td> ficha </td><td> QwenCloud token de chave de API temporário: ao ligar QwenCloud serviços de ambientes não confiáveis, como navegadores ou aplicativos móveis, geram uma chave de API temporária por meio de um back-end seguro para evitar a exposição de uma chave de API permanente. O SDK envia esse token para a Open Platform como uma credencial HTTP Bearer. </td><td> Obter credenciais de autenticação </td></tr><tr><td> bilhete </td><td> HappyOyster credencial de viagem mundial: seu back-end chama a API de credenciais usando autenticação AK (cabeçalho do gateway) para obter uma credencial de viagem de curta duração (<code>bilhete</code>) que o cliente usa para entrar em uma sala. A API verifica a propriedade mundial, mas não cria um registro de viagem real. </td><td> Obter credenciais de autenticação </td></tr></tbody></table>

Visão geral

O SDK fornece os seguintes objetos primários:

HappyOysterEngine

<table><colgroup><col style={{ width: "33.333333%" }} /><col style={{ width: "66.666667%" }} /></colgroup><thead><tr><th> API </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>novo HappyOysterEngine(configuração)</code> </td><td> Cria uma instância do mecanismo. </td></tr><tr><td> <code>atualizarToken(token)</code> </td><td> Atualiza o QwenCloud token de chave de API temporário usado por solicitações subsequentes de API de plataforma aberta. </td></tr><tr><td> <code>criarViagem(config)</code> </td><td> Cria uma sessão de viagem. </td></tr><tr><td> <code>HappyOysterEngine.version</code> </td><td> A versão atual do SDK. </td></tr><tr><td> <code>HappyOysterEngine.metadata</code> </td><td> O nome, a versão e o canal do pacote do SDK atual. </td></tr></tbody></table>

Viagem

<table><colgroup><col style={{ width: "33.333333%" }} /><col style={{ width: "66.666667%" }} /></colgroup><thead><tr><th> API </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>início()</code> </td><td> Inicia a sessão de viagem atual. </td></tr><tr><td> <code>on("statusChanged", manipulador)</code> </td><td> Assina alterações de status da sessão. </td></tr><tr><td> <code>on("firstFrameGenerated", manipulador)</code> </td><td> Assina notificações de URL do primeiro quadro. </td></tr><tr><td> <code>on("travelInfoReady", manipulador)</code> </td><td> Assina os metadados da sessão disponíveis imediatamente após a entrada-viagem. </td></tr><tr><td> <code>onError(manipulador)</code> </td><td> Assina erros de tempo de execução da sessão. </td></tr><tr><td> <code>pode (ação)</code> </td><td> Verifica se a ação especificada pode ser chamada atualmente. </td></tr><tr><td> <code>obterInfo()</code> </td><td> Obtém metadados de sessão disponíveis; retorna <code>nulo</code> antes de estar disponível. </td></tr><tr><td> <code>enviarCommand(parâmetros)</code> </td><td> Envia um comando de controle em tempo real. </td></tr><tr><td> <code>enviarInstruct(parâmetros)</code> </td><td> Envia instruções de direção ou conteúdo imediato. </td></tr><tr><td> <code>pausa()</code> </td><td> Pausa a sessão atual. </td></tr><tr><td> <code>currículo()</code> </td><td> Retoma uma sessão pausada. </td></tr><tr><td> <code>retroceder (parâmetros)</code> </td><td> Retrocede uma sessão do Directing até o horário especificado. </td></tr><tr><td> <code>fim()</code> </td><td> Encerra a sessão atual e libera seus recursos. </td></tr></tbody></table>

Outras exportações

<table><colgroup><col style={{ width: "33.333333%" }} /><col style={{ width: "66.666667%" }} /></colgroup><thead><tr><th> Exportar </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>Código de erro</code> </td><td> O objeto constante de código de erro exportado pelo SDK. </td></tr><tr><td> <code>isSdkError(erro)</code> </td><td> Verifica se um erro desconhecido é um erro padrão do SDK. </td></tr><tr><td> Tipos </td><td> Tipos públicos como <code>SDKConfig</code>, <code>Viajar</code>, <code>InícioTravelResult</code>e <code>Comando de Aventura</code>. </td></tr></tbody></table>

Exemplo

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
  token: 'temporary-api-key-token',
  logLevel: 'warn',
  streamReadyTimeout: 15_000,
})

const videoElement = document.getElementById('player') as HTMLVideoElement
const travel = engine.createTravel({
  ticket: 'travel-ticket',
  videoElement,
  maxExperienceTimeSec: 90,
})

const unsubscribeStatus = travel.on('statusChanged', (status) => {
  console.log('Travel status:', status)
})

const unsubscribeFirstFrame = travel.on('firstFrameGenerated', (firstFrame) => {
  console.log('First frame URL:', firstFrame)
})

const unsubscribeInfo = travel.on('travelInfoReady', (info) => {
  console.log('Travel info is ready before RTC playback:', info)
})

const unsubscribeError = travel.onError((error) => {
  console.error('Travel error:', error)
})

try {
  const { encryptedTravelId, mode, creationModel, firstFrame, maxExperienceTimeSec, aspectRatio } = await travel.start()

  // Adventure (mode 1)
  await travel.sendCommand({
    translation: 'Front',
    rotation: 'Mouse_Left',
    interaction: 'Jump',
  })

  // Directing (mode 2) or Acting (mode 3; not scriptlist)
  await travel.sendInstruct({ content: 'Turn the camera toward the castle and have the protagonist start running' })

  await travel.pause()
  await travel.resume()
} catch (err) {
  if (isSdkError(err)) {
    console.error('SDK error:', err.code, err.message)
  } else {
    console.error('Unexpected error:', err)
  }
} finally {
  unsubscribeStatus()
  unsubscribeFirstFrame()
  unsubscribeInfo()
  unsubscribeError()
  await travel.end()
}

engine.updateToken('new-temporary-api-key-token')

`HappyOysterEngine`

HappyOysterEngine é o ponto de entrada do Web SDK. Ele configura o host Open Platform, gerencia o QwenCloud token de chave de API temporário usado por solicitações subsequentes e cria Travel sessões.

Uma instância do Engine gerencia atualmente apenas um ativo Travel de cada vez. Acabar com a corrente Travel antes de iniciar uma nova sessão.

Depois que um token é definido no construtor ou por meio updateToken(), o SDK busca internamente a configuração do Feature Gate. Isso permite que a plataforma desative remotamente o SDK ou exija a atualização de versões mais antigas. Se a solicitação falhar, o SDK falhará ao abrir e não bloqueará a experiência normal.

<table><colgroup><col style={{ width: "33.333333%" }} /><col style={{ width: "66.666667%" }} /></colgroup><thead><tr><th> API </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>novo HappyOysterEngine(configuração)</code> </td><td> Cria uma instância do Engine com o host e modelo de API necessários e token e nível de log opcionais. </td></tr><tr><td> <code>atualizarToken(token)</code> </td><td> Atualiza o QwenCloud token de chave de API temporário usado por solicitações subsequentes da Open Platform. </td></tr><tr><td> <code>criarViagem(config)</code> </td><td> Cria uma sessão de viagem que ainda não foi iniciada. </td></tr></tbody></table>

`new HappyOysterEngine`

Cria um HappyOysterEngine instância.

Assinatura

new HappyOysterEngine(config: SDKConfig)

Parâmetros

`SDKConfig`

<table><colgroup><col style={{ width: "18.518519%" }} /><col style={{ width: "18.518519%" }} /><col style={{ width: "13.888889%" }} /><col style={{ width: "49.074074%" }} /></colgroup><thead><tr><th> Campo </th><th> Tipo </th><th> Obrigatório </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>HostAPI</code> </td><td> <code>corda</code> </td><td> Sim </td><td> Host de API de plataforma aberta. Deve ser um host simples, como <code>plataforma aberta.exemplo.com</code>, sem <code>https://</code>, um esquema ou um caminho. </td></tr><tr><td> <code>modelo</code> </td><td> <code>corda</code> </td><td> Sim </td><td> Identificador do modelo de Plataforma Aberta a ser usado. Obrigatório, sem padrão. Corrigido para este motor e compartilhado por todas as suas viagens. </td></tr><tr><td> <code>ficha</code> </td><td> <code>corda</code> </td><td> Não </td><td> QwenCloud token de chave de API temporário definido durante a construção. Também pode ser definido posteriormente com <code>atualizarToken()</code>. </td></tr><tr><td> <code>nível de registro</code> </td><td> <code>Nível de registro</code> </td><td> Não </td><td> Nível de log do SDK. O padrão é <code>nenhum</code>. </td></tr><tr><td> <code>streamReadyTimeout</code> </td><td> <code>número</code> </td><td> Não </td><td> Tempo limite de espera <code><video></code> para se tornar jogável, parar ou retomar, em milissegundos. O padrão é <code>15000</code>. </td></tr></tbody></table>

Definir model para um identificador de modelo, como happyoyster-1.0-adventure, um modelo de aventura. Use o identificador de modelo para seu ambiente de serviço de destino. O SDK não escolhe um modelo da experiência mode ou deduza do ticket.

Um motor tem um fixo APIHost + model. Reutilize-o em Viagens sucessivas visando o mesmo serviço e modelo. Antes de mudar qualquer valor, encerre o deslocamento ativo e use um mecanismo configurado para o novo alvo. Crie o mundo e emita seu ticket para o mesmo alvo de serviço.

Devoluções

Retorna um HappyOysterEngine instância.

Erros

Se config está faltando, ou se APIHost, model, token, logLevel, ou streamReadyTimeout tem um tipo ou valor inválido, um SdkError com código ErrorCode.INVALID_ARGUMENT (10010001) é lançado de forma síncrona. Passar um URL completo, uma string vazia ou um valor com um caminho como APIHost é inválido.

model é obrigatório e deve ser uma string não vazia após o corte; null, valores que não sejam de string e strings somente com espaços em branco são inválidos. Omitindo ou passando undefined também gera um erro de argumento; o SDK não possui modelo padrão.

`HappyOysterEngine.updateToken`

Atualiza o QwenCloud token de chave de API temporário usado por solicitações subsequentes de API de plataforma aberta.

Assinatura

updateToken(token: string): void

Parâmetros

Devoluções

Não retorna nada.

Erros

Se token não é uma string, uma SdkError com código ErrorCode.INVALID_ARGUMENT (10010001) é lançado de forma síncrona.

`HappyOysterEngine.createTravel`

Cria uma instância de sessão de viagem sem iniciá-la.

Assinatura

createTravel(config: CreateTravelConfig): Travel

Parâmetros

`CreateTravelConfig`

Devoluções

Retorna um criado, mas ainda não iniciado Travel sessão. O chamador deve então executar await travel.start() para entrar na sessão e esperar que o vídeo fique reproduzível.

Cada HappyOysterEngine instância pode ter apenas um ativo Travel de cada vez. Ligar await travel.end() antes de criar outra viagem.

Erros

createTravel() lança um SdkError de forma síncrona nos seguintes casos:

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Código de erro </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>10010001</code> </td><td> <code>configuração</code>, <code>bilhete</code>, <code>elemento de vídeo</code>, ou <code>maxExperienceTimeSec</code> é inválido </td></tr><tr><td> <code>10010101</code> </td><td> Uma viagem já está ativa; ligar <code>viagem.fim()</code> primeiro </td></tr></tbody></table>

Erros de inicialização são expostos por travel.start().

`Travel`

Travel representa uma sessão criada por HappyOysterEngine.createTravel(). Está inicialmente inativo. Depois travel.start() é chamado, o SDK entra na sessão e aguarda que o vídeo se torne reproduzível.

O Travel oferece suporte para iniciar, pausar, retomar, retroceder e encerrar uma sessão; envio de controles e avisos em tempo real; e subscrever alterações de status e erros de tempo de execução.

Métodos

<table><colgroup><col style={{ width: "33.333333%" }} /><col style={{ width: "66.666667%" }} /></colgroup><thead><tr><th> Método </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>início()</code> </td><td> Inicia a sessão de viagem atual. </td></tr><tr><td> <code>on("statusChanged", manipulador)</code> </td><td> Assina alterações de status da sessão. </td></tr><tr><td> <code>on("firstFrameGenerated", manipulador)</code> </td><td> Assina notificações de URL do primeiro quadro. </td></tr><tr><td> <code>on("travelInfoReady", manipulador)</code> </td><td> Assina os metadados da sessão disponíveis imediatamente após a entrada-viagem. </td></tr><tr><td> <code>onError(manipulador)</code> </td><td> Assina erros de tempo de execução da sessão. </td></tr><tr><td> <code>pode (ação)</code> </td><td> Verifica se a ação especificada pode ser chamada atualmente. </td></tr><tr><td> <code>obterInfo()</code> </td><td> Obtém metadados de sessão disponíveis; retorna <code>nulo</code> antes de estar disponível. </td></tr><tr><td> <code>enviarCommand(parâmetros)</code> </td><td> Envia um comando de controle em tempo real. </td></tr><tr><td> <code>enviarInstruct(parâmetros)</code> </td><td> Envia instruções de direção ou conteúdo imediato. </td></tr><tr><td> <code>pausa()</code> </td><td> Pausa a sessão atual. </td></tr><tr><td> <code>currículo()</code> </td><td> Retoma uma sessão pausada. </td></tr><tr><td> <code>retroceder (parâmetros)</code> </td><td> Retrocede a sessão atual até o horário especificado. </td></tr><tr><td> <code>fim()</code> </td><td> Encerra a sessão atual e libera seus recursos. </td></tr></tbody></table>

Estado

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Estado </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>ocioso</code> </td><td> A sessão não foi iniciada. </td></tr><tr><td> <code>preparar</code> </td><td> A sessão está iniciando e aguardando que o vídeo possa ser reproduzido. </td></tr><tr><td> <code>correndo</code> </td><td> A sessão está em execução. </td></tr><tr><td> <code>pausado</code> </td><td> A sessão é pausada e pode ser retomada ou rebobinada. </td></tr><tr><td> <code>concluído</code> </td><td> A sessão terminou normalmente e seus recursos foram liberados. </td></tr></tbody></table>

Eventos

Inscreva-se em eventos com travel.on(event, handler). O método retorna uma função de cancelamento de assinatura.

<table><colgroup><col style={{ width: "20.061728%" }} /><col style={{ width: "30.092593%" }} /><col style={{ width: "49.845679%" }} /></colgroup><thead><tr><th> Evento </th><th> Retorno de chamada </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>status alterado</code> </td><td> <code>(status: TravelStatus) => nulo</code> </td><td> O status da sessão mudou. </td></tr><tr><td> <code>primeiroFrameGenerated</code> </td><td> <code>(firstFrame: string) => vazio</code> </td><td> Emitido durante <code>início()</code> quando Open Platform retorna um URL de primeiro quadro não vazio; antes <code>início()</code> resolve e o vídeo se torna reproduzível. </td></tr><tr><td> <code>travelInfoReady</code> </td><td> <code>(informações: TravelInfo) => nulo</code> </td><td> Emitido após o retorno da viagem e antes da conexão do RTC. <code>obterInfo()</code> retorna os mesmos dados; se existir um primeiro quadro, <code>primeiroFrameGenerated</code> segue. </td></tr><tr><td> <code>erro</code> </td><td> <code>(erro: desconhecido) => nulo</code> </td><td> Um erro de tempo de execução da sessão. </td></tr></tbody></table>

`Travel.can`

Verifica se uma ação está disponível para o status atual e a capacidade da sessão.

Assinatura

can(action: TravelAction): boolean

Parâmetros

Devoluções

Retorna um boolean. true significa que a ação está disponível no momento; false significa que o status, modo ou capacidade de sessão atual não atende às suas pré-condições.

Disponibilidade

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> ação </th><th> Disponibilidade </th></tr></thead><tbody><tr><td> <code>começar</code> </td><td> A viagem ainda é <code>ocioso</code>, não foi fechado e nunca foi iniciado. </td></tr><tr><td> <code>enviarComando</code> </td><td> <code>correndo</code>, com o modo Viagem definido como Aventura (<code>1</code>). </td></tr><tr><td> <code>enviarInstruir</code> </td><td> <code>correndo</code> ou <code>pausado</code>, com o modo definido como Direção (<code>2</code>) ou Atuação (<code>3</code>) e não <code>lista de scripts</code>. </td></tr><tr><td> <code>pausar</code> </td><td> <code>correndo</code>e a sessão atual suporta pausa. </td></tr><tr><td> <code>currículo</code> </td><td> <code>pausado</code>, e a sessão atual suporta a retomada. </td></tr><tr><td> <code>retroceder</code> </td><td> <code>pausado</code> em uma sessão de Direção que suporta retrocesso; Atuar não suporta isso. </td></tr><tr><td> <code>fim</code> </td><td> As viagens não foram fechadas. </td></tr></tbody></table>

Erros

Este método não gera erros de negócios. Ações desconhecidas retornam false.

Viajar. Começar.

Inicia a sessão de viagem atual.

Assinatura

start(): Promise<StartTravelResult>

Parâmetros

Sem parâmetros.

Devoluções

Retorna um Promise<StartTravelResult>, que é resolvido após o início da sessão e o vídeo pode ser reproduzido.

Após o retorno da viagem, o SDK emite travelInfoReady antes de conectar o RTC. Assinantes atrasados podem ligar travel.getInfo(); ele retorna null antes que os metadados estejam disponíveis. Se a resposta incluir um valor não vazio firstFrame, firstFrameGenerated ainda segue.

`StartTravelResult`

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "25%" }} /><col style={{ width: "50%" }} /></colgroup><thead><tr><th> Campo </th><th> Tipo </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>ID de viagem criptografado</code> </td><td> <code>corda</code> </td><td> ID da sessão de viagem atual. </td></tr><tr><td> <code>modo</code> </td><td> <code>número</code> </td><td> Modo de sessão: <code>1</code> = Aventura (exploração do mundo), <code>2</code> = Direção (direção em tempo real), <code>3</code> = Atuação. </td></tr><tr><td> <code>criaçãoModelo</code> </td><td> <code>corda</code> </td><td> Modelo de criação mundial; valores comuns são <code>simples</code> e <code>lista de scripts</code>. </td></tr><tr><td> <code>primeiroQuadro</code> </td><td> <code>corda | nulo</code> </td><td> URL da imagem do primeiro quadro; <code>nulo</code> se o servidor não retornar um. </td></tr><tr><td> <code>maxExperienceTimeSec</code> </td><td> <code>60 | 90 | 120 | nulo</code> </td><td> Duração máxima da experiência de aventura, em segundos. <code>nulo</code> para sessões de Direção e Atuação ou quando o servidor não retorna este campo. </td></tr><tr><td> <code>proporção de aspecto</code> </td><td> <code>"9:16" | "16:9" | nulo</code> </td><td> Proporção de atuação; <code>nulo</code> para outros modos ou quando o servidor não o retorna. </td></tr></tbody></table>

Erros

start() rejeita e emite um error evento nos seguintes casos. Usar isSdkError(err) para verificar o erro e ler err.code e err.message.

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Código de erro </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>10010002</code> </td><td> O recurso SDK está desativado (<code>SDK_FEATURE_DISABLED</code>) </td></tr><tr><td> <code>10020101</code> </td><td> Não é possível iniciar: o status atual não permite, a plataforma aberta não está configurada ou a entrada na sessão falhou </td></tr><tr><td> <code>10020102</code> </td><td> Não foi possível iniciar: a configuração da sessão retornada pelo servidor está incompleta </td></tr><tr><td> <code>10020103</code> </td><td> Não foi possível iniciar: falha na conexão do stream de vídeo ou falha na solicitação de sinalização de recurso do SDK </td></tr><tr><td> <code>10020104</code> </td><td> Não é possível iniciar: tempo limite de espera pelo fluxo de vídeo (usa o maior entre <code>streamReadyTimeout</code> e o servidor <code>noStreamAutoEndTimeoutSec</code>) </td></tr><tr><td> <code>10020105</code> </td><td> Não é possível iniciar: o tempo limite expirou aguardando que o vídeo se tornasse reproduzível (controlado por <code>streamReadyTimeout</code>; padrão: 15 segundos) </td></tr><tr><td> <code>10000001</code>–<code>10000012</code> </td><td> Parâmetro de plataforma aberta, recurso ou erro de servidor </td></tr></tbody></table>

`Travel.on("statusChanged")`

Assina alterações de status da sessão.

Assinatura

on("statusChanged", handler: (status: TravelStatus) => void): () => void

Parâmetros

Devoluções

Retorna uma função de cancelamento de assinatura. TravelStatus é um dos idle / prepare / running / paused / completed.

Erros

Este método não gera erros de negócios.

`Travel.on("firstFrameGenerated")`

Assina notificações de URL do primeiro quadro.

Assinatura

on("firstFrameGenerated", handler: (firstFrame: string) => void): () => void

Parâmetros

Devoluções

Retorna uma função de cancelamento de assinatura.

Comportamento

Emitido apenas durante travel.start(). Depois que o SDK chama o Open Platform enter-travel e recebe um valor não vazio firstFrame, ele emite o evento imediatamente - geralmente após statusChanged("prepare") mas antes start() resolve e o vídeo se torna reproduzível. O evento não será emitido se a resposta não contiver URL de primeiro quadro.

Erros

Este método não gera erros de negócios.

`Travel.onError`

Assina erros de tempo de execução da sessão.

Assinatura

onError(handler: (error: unknown) => void): () => void

Parâmetros

Devoluções

Retorna uma função de cancelamento de assinatura. Usar isSdkError para restringir o objeto de erro para SdkError.

Erros

Este método não gera erros de negócios.

`Travel.sendCommand`

Envia um comando de controle em tempo real.

Assinatura

sendCommand(params: AdventureCommand): Promise<void>

Parâmetros

`AdventureCommand`

Referência de comando de controle

`translation` - Direção do Movimento

Descreve o movimento do personagem, suportando oito direções e combinações.

<table><colgroup><col style={{ width: "50%" }} /><col style={{ width: "50%" }} /></colgroup><thead><tr><th> Valor </th><th> Direção </th></tr></thead><tbody><tr><td> <code>"Frente"</code> </td><td> Avançar </td></tr><tr><td> <code>"Voltar"</code> </td><td> Para trás </td></tr><tr><td> <code>"Esquerda"</code> </td><td> Esquerda </td></tr><tr><td> <code>"Certo"</code> </td><td> Certo </td></tr><tr><td> <code>"Frente_Esquerda"</code> </td><td> Avançado-esquerdo </td></tr><tr><td> <code>"Frente_Direita"</code> </td><td> Avançar-direita </td></tr><tr><td> <code>"Voltar_Esquerda"</code> </td><td> Para trás-esquerda </td></tr><tr><td> <code>"Voltar_Direita"</code> </td><td> Para trás-direita </td></tr><tr><td> <code>"Nenhum"</code> </td><td> Estacionário </td></tr></tbody></table>

`rotation` - Ver Rotação

Simula a rotação da vista baseada no mouse em oito direções.

<table><colgroup><col style={{ width: "50%" }} /><col style={{ width: "50%" }} /></colgroup><thead><tr><th> Valor </th><th> Direção </th></tr></thead><tbody><tr><td> <code>"Mouse_Up"</code> </td><td> Acima </td></tr><tr><td> <code>"Mouse_Para baixo"</code> </td><td> Para baixo </td></tr><tr><td> <code>"Rato_Esquerda"</code> </td><td> Esquerda </td></tr><tr><td> <code>"Rato_Direito"</code> </td><td> Certo </td></tr><tr><td> <code>"Mouse_Cima_Esquerda"</code> </td><td> Acima à esquerda </td></tr><tr><td> <code>"Mouse_Up_Right"</code> </td><td> Acima à direita </td></tr><tr><td> <code>"Mouse_Baixo_Esquerda"</code> </td><td> Abaixo à esquerda </td></tr><tr><td> <code>"Mouse_Baixo_Direita"</code> </td><td> Abaixo à direita </td></tr><tr><td> <code>"Nenhum"</code> </td><td> Nenhum </td></tr></tbody></table>

`interaction` — Ação de interação

<table><colgroup><col style={{ width: "50%" }} /><col style={{ width: "50%" }} /></colgroup><thead><tr><th> Valor </th><th> Ação </th></tr></thead><tbody><tr><td> <code>"Pular"</code> </td><td> Salte </td></tr><tr><td> <code>"Ataque"</code> </td><td> Ataque </td></tr><tr><td> <code>"Agachar"</code> </td><td> Agachar </td></tr><tr><td> <code>"Corrida"</code> </td><td> Corrida </td></tr><tr><td> <code>"Nenhum"</code> </td><td> Nenhum </td></tr></tbody></table>

Devoluções

Retorna um Promise<void> que é resolvido após o comando ser enviado.

Erros

sendCommand() rejeita nos seguintes casos:

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Código de erro </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>10010001</code> </td><td> <code>parâmetros</code> ou um parâmetro de movimento, rotação ou interação é inválido </td></tr><tr><td> <code>10020501</code> </td><td> O status atual ou modo de sessão não permite comandos ou o comando video-stream falhou </td></tr></tbody></table>

`Travel.sendInstruct`

Envia instruções de direção ou conteúdo imediato.

Assinatura

sendInstruct(params: InstructData): Promise<void>

Parâmetros

`InstructData`

Devoluções

Retorna um Promise<void> que é resolvido após a Open Platform receber e processar a instrução.

Erros

sendInstruct() rejeita e emite um error evento nos seguintes casos:

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Código de erro </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>10020101</code> </td><td> A sessão não começou </td></tr><tr><td> <code>10020601</code> </td><td> Falha ao enviar a instrução de direção </td></tr><tr><td> <code>10000001</code>–<code>10000012</code> </td><td> Parâmetro de plataforma aberta, recurso ou erro de servidor </td></tr></tbody></table>

`Travel.pause`

Pausa a sessão atual.

Assinatura

pause(): Promise<void>

Parâmetros

Sem parâmetros.

Devoluções

Retorna um Promise<void> isso é resolvido depois que a reprodução do vídeo é interrompida.

Erros

pause() rejeita nos seguintes casos:

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Código de erro </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>10020201</code> </td><td> O status atual, modo de sessão ou capacidade de sessão não permite pausa ou a solicitação de pausa falhou </td></tr><tr><td> <code>10020202</code> </td><td> Tempo limite esgotado ao aguardar que o back-end reporte o stream de vídeo como pausado (15 segundos) </td></tr><tr><td> <code>10000001</code>–<code>10000012</code> </td><td> Parâmetro de plataforma aberta, recurso ou erro de servidor </td></tr></tbody></table>

`Travel.resume`

Retoma uma sessão pausada.

Assinatura

resume(): Promise<void>

Parâmetros

Sem parâmetros.

Devoluções

Retorna um Promise<void> isso é resolvido depois que o vídeo se torna reproduzível novamente.

Erros

resume() rejeita nos seguintes casos:

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Código de erro </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>10020301</code> </td><td> O status atual, modo de sessão ou capacidade de sessão não permite a retomada ou a solicitação de retomada falhou </td></tr><tr><td> <code>10020302</code> </td><td> Tempo limite de espera para que o vídeo possa ser reproduzido novamente (15 segundos) </td></tr><tr><td> <code>10000001</code>–<code>10000012</code> </td><td> Parâmetro de plataforma aberta, recurso ou erro de servidor </td></tr></tbody></table>

`Travel.rewind`

Retrocede a sessão atual até o horário especificado.

Assinatura

rewind(params: RewindTravelParams): Promise<RewindTravelResult>

Parâmetros

`RewindTravelParams`

Devoluções

Retorna um Promise<RewindTravelResult> que é resolvido após a conclusão do retrocesso e a reprodução ser retomada.

`RewindTravelResult`

Erros

rewind() rejeita e emite um error evento nos seguintes casos:

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Código de erro </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>10020101</code> </td><td> A sessão não começou </td></tr><tr><td> <code>10020401</code> </td><td> Não é 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 a reconexão do RTC falhou </td></tr><tr><td> <code>10020402</code> </td><td> Tempo limite esgotado ao aguardar a retomada do vídeo após retroceder (15 segundos) </td></tr><tr><td> <code>10000001</code>–<code>10000012</code> </td><td> Parâmetro de plataforma aberta, recurso ou erro de servidor </td></tr></tbody></table>

`Travel.end`

Encerra a sessão atual e libera seus recursos.

Assinatura

end(): Promise<void>

Parâmetros

Sem parâmetros.

Devoluções

Retorna um Promise<void> isso é resolvido após o término 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 promessas ou error eventos. Erros são SdkError objetos; usar isSdkError(err) e leia err.code e err.message.

Erros reconhecidos da Plataforma Aberta são mapeados para o 10000001–10000012 alcance, e err.message contém a mensagem da plataforma. Consulte a seção Erros de cada API de viagem para obter códigos específicos do método.

Referência de código de erro

Intervalos de códigos de erro:

100000xx: Erros de plataforma aberta mapeados
1001xxxx: Erros do cliente do mecanismo
1002xxxx: Erros do cliente de viagem

<table><colgroup><col style={{ width: "20.061728%" }} /><col style={{ width: "30.092593%" }} /><col style={{ width: "49.845679%" }} /></colgroup><thead><tr><th> código </th><th> nome </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>10000001</code> </td><td> <code>ABRIR_PLATFORM_PARAM_INVALID</code> </td><td> Parâmetros de solicitação inválidos (retornados pela Open Platform) </td></tr><tr><td> <code>10000002</code> </td><td> <code>ABRIR_PLATFORM_RESOURCE_NOT_FOUND</code> </td><td> Recurso não encontrado (viagem ausente, sem propriedade, em outro espaço de trabalho ou artefato não pronto) </td></tr><tr><td> <code>10000003</code> </td><td> <code>ABERTO_PLATFORM_WORLD_NOT_OWNED</code> </td><td> O mundo não existe, foi excluído ou não pertence ao desenvolvedor atual </td></tr><tr><td> <code>10000004</code> </td><td> <code>ABRIR_PLATFORM_SYSTEM_ERROR</code> </td><td> Erro do sistema </td></tr><tr><td> <code>10000005</code> </td><td> <code>ABRIR_PLATFORM_TICKET_INVÁLIDO</code> </td><td> O ingresso é inválido ou expirou </td></tr><tr><td> <code>10000006</code> </td><td> <code>ABRIR_PLATAFORMA_TICKET_USED</code> </td><td> O ticket já foi usado (credencial única) </td></tr><tr><td> <code>10000007</code> </td><td> <code>ABRIR_PLATFORM_WORLD_NOT_READY</code> </td><td> O mundo não está pronto e não pode ser acessado </td></tr><tr><td> <code>10000008</code> </td><td> <code>ABRIR_PLATFORM_INFERENCE_ALLOCATE_FAILED</code> </td><td> Falha na alocação de recursos de inferência (capacidade insuficiente, falha na criação de fluxo, falha na inicialização da sessão, etc.) </td></tr><tr><td> <code>10000009</code> </td><td> <code>ABRIR_PLATFORM_MAIN_API_KEY_REQUIRED</code> </td><td> Esta API aceita apenas a chave de API primária (chaves de API temporárias não são suportadas) </td></tr><tr><td> <code>10000010</code> </td><td> <code>ABRIR_PLATFORM_CONTENT_MODERATION</code> </td><td> Entrada rejeitada pela moderação de conteúdo </td></tr><tr><td> <code>10000011</code> </td><td> <code>ABRIR_PLATFORM_CONTENT_COPYRIGHT</code> </td><td> A imagem de entrada viola direitos autorais ou política de IP </td></tr><tr><td> <code>10000012</code> </td><td> <code>ABRIR_PLATFORM_STATE_CONFLICT</code> </td><td> Solicitar conflitos com o estado atual do recurso </td></tr><tr><td> <code>10010001</code> </td><td> <code>INVÁLIDO_ARGUMENTO</code> </td><td> Falha na validação do argumento do cliente SDK (não mapeado da plataforma aberta) </td></tr><tr><td> <code>10010002</code> </td><td> <code>SDK_FEATURE_DISABLED</code> </td><td> O recurso SDK está desativado </td></tr><tr><td> <code>10010101</code> </td><td> <code>ATIVO_TRAVEL_EXISTE</code> </td><td> Uma viagem já está ativa </td></tr><tr><td> <code>10020001</code> </td><td> <code>TRANSMISSÃO_DESCONECTADO_ENQUANTO_JOGANDO</code> </td><td> Stream de vídeo desconectado durante a reprodução </td></tr><tr><td> <code>10020101</code> </td><td> <code>INICIAR_PEDIDO_FALHA</code> </td><td> Falha na solicitação de início de sessão </td></tr><tr><td> <code>10020102</code> </td><td> <code>START_RTC_CONFIG_MISSING</code> </td><td> Configuração de stream de vídeo ausente durante a inicialização </td></tr><tr><td> <code>10020103</code> </td><td> <code>START_JOIN_CHANNEL_FAILED</code> </td><td> Falha na conexão do stream de vídeo </td></tr><tr><td> <code>10020104</code> </td><td> <code>START_REMOTE_USER_TIMEOUT</code> </td><td> Tempo limite esgotado aguardando a transmissão do vídeo </td></tr><tr><td> <code>10020105</code> </td><td> <code>START_STREAM_TIMEOUT</code> </td><td> Tempo limite esgotado aguardando que o vídeo se torne reproduzível </td></tr><tr><td> <code>10020201</code> </td><td> <code>PAUSA_REQUEST_FAILED</code> </td><td> Falha na solicitação de pausa </td></tr><tr><td> <code>10020202</code> </td><td> <code>PAUSAR_STREAM_TIMEOUT</code> </td><td> Tempo limite esgotado aguardando a pausa do vídeo </td></tr><tr><td> <code>10020301</code> </td><td> <code>RETOMAR_PEDIDO_FALHA</code> </td><td> Falha na solicitação de retomada </td></tr><tr><td> <code>10020302</code> </td><td> <code>RETOMAR_STREAM_TIMEOUT</code> </td><td> Tempo limite esgotado aguardando a retomada do vídeo </td></tr><tr><td> <code>10020401</code> </td><td> <code>REBOBINAR_REQUEST_FAILED</code> </td><td> Falha na solicitação de retrocesso </td></tr><tr><td> <code>10020402</code> </td><td> <code>REBOBINAR_STREAM_TIMEOUT</code> </td><td> Tempo limite esgotado aguardando a retomada do vídeo após retroceder </td></tr><tr><td> <code>10020501</code> </td><td> <code>ENVIAR_COMMAND_FAILED</code> </td><td> Falha ao enviar o comando de controle em tempo real </td></tr><tr><td> <code>10020601</code> </td><td> <code>INSTRUÇÃO_REQUEST_FAILED</code> </td><td> Falha ao enviar a instrução de direção </td></tr><tr><td> <code>10020701</code> </td><td> <code>FIM_REQUEST_FAILED</code> </td><td> Falha na solicitação de encerramento da sessão </td></tr></tbody></table>

Outras exportações

Exportações em tempo de execução

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "25%" }} /><col style={{ width: "50%" }} /></colgroup><thead><tr><th> Exportar </th><th> Tipo </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>HappyOysterEngine</code> </td><td> <code>aula</code> </td><td> Cliente SDK que configura Open Platform, atualiza o token e cria sessões de viagem. </td></tr><tr><td> <code>HappyOysterEngine.version</code> </td><td> <code>corda</code> </td><td> A versão atual do SDK. </td></tr><tr><td> <code>HappyOysterEngine.metadata</code> </td><td> <code>SDKMetadados</code> </td><td> O nome, a versão e o canal do pacote do SDK atual. </td></tr><tr><td> <code>Código de erro</code> </td><td> <code>const</code> </td><td> O objeto constante de código de erro exportado pelo SDK. </td></tr><tr><td> <code>isSdkError</code> </td><td> <code>função</code> </td><td> Verifica se um erro desconhecido é um erro padrão do SDK. </td></tr></tbody></table>

`ErrorCode`

O objeto constante de código de erro exportado pelo SDK. Compare com SdkError.code em vez de espalhar literais numéricos pelo código do aplicativo.

import { ErrorCode } from '@happy-oyster/js-sdk'

`isSdkError`

Verifica se um erro desconhecido é um erro padrão do SDK. Quando retornar true, o TypeScript restringe o erro para SdkError, permitindo acesso seguro a code e message.

isSdkError(error: unknown): error is SdkError

try {
  await travel.start()
} catch (err) {
  if (isSdkError(err) && err.code === ErrorCode.OPEN_PLATFORM_TICKET_INVALID) {
    // Request a new Travel ticket, then create a new Travel.
  }
}

Tipos públicos

Os seguintes tipos são exportados do ponto de entrada do pacote e podem ser importados diretamente do @happy-oyster/js-sdk. Eles existem apenas em tempo de compilação do TypeScript e não produzem código de tempo de execução.

<table><colgroup><col style={{ width: "33.333333%" }} /><col style={{ width: "66.666667%" }} /></colgroup><thead><tr><th> Tipo </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>SDKConfig</code> </td><td> <code>HappyOysterEngine</code> tipo de parâmetro do construtor. </td></tr><tr><td> <code>Nível de registro</code> </td><td> Níveis de log do SDK: <code>detalhado</code> / <code>depurar</code> / <code>informações</code> / <code>avisar</code> / <code>erro</code> / <code>nenhum</code>. </td></tr><tr><td> <code>SDKMetadados</code> </td><td> Metadados do pacote SDK: <code>versão</code>, <code>nomedopacote</code>, <code>pacoteCanal</code>. </td></tr><tr><td> <code>SDKPackageChannel</code> </td><td> Canais do pacote SDK: <code>interno</code> / <code>público</code> / <code>desconhecido</code>. </td></tr><tr><td> <code>CriarTravelConfig</code> </td><td> <code>criarViagem(config)</code> tipo de parâmetro. </td></tr><tr><td> <code>InícioTravelResult</code> </td><td> <code>início()</code> metadados da sessão retornados quando a promessa é resolvida. </td></tr><tr><td> <code>Informações de viagem</code> </td><td> Metadados de sessão usados por <code>travelInfoReady</code>, <code>obterInfo()</code>e <code>InícioTravelResult</code>. </td></tr><tr><td> <code>Taxa de aspecto de viagem</code> </td><td> Proporção de atuação: <code>"9:16"</code> / <code>"16:9"</code>. </td></tr><tr><td> <code>Viajar</code> </td><td> <code>criarViagem()</code> contrato de sessão pública retornado pelo método. </td></tr><tr><td> <code>Status de viagem</code> </td><td> Estados da sessão do SDK local: <code>ocioso</code> / <code>preparar</code> / <code>correndo</code> / <code>pausado</code> / <code>concluído</code>. </td></tr><tr><td> <code>ViagemAção</code> </td><td> <code>pode (ação)</code> nomes de ação suportados. </td></tr><tr><td> <code>Comando de Aventura</code> </td><td> <code>enviarCommand(parâmetros)</code> tipo de parâmetro. </td></tr><tr><td> <code>Instruir Dados</code> </td><td> <code>enviarInstruct(parâmetros)</code> tipo de parâmetro. </td></tr><tr><td> <code>RebobinarTravelParams</code> </td><td> <code>retroceder (parâmetros)</code> tipo de parâmetro. </td></tr><tr><td> <code>RewindTravelResult</code> </td><td> <code>retroceder (parâmetros)</code> dados retornados quando a promessa é resolvida. </td></tr><tr><td> <code>Erro SDK</code> </td><td> Formato de erro do SDK contendo <code>código</code> e <code>mensagem</code>. </td></tr><tr><td> <code>SdkError</code> </td><td> Tipo de erro ao combinar o tempo de execução <code>Erro</code> e <code>Erro SDK</code>. </td></tr><tr><td> <code>ErrorCodeValue</code> </td><td> União de todos os valores de código de erro no <code>Código de erro</code> objeto. </td></tr></tbody></table>

HappyOyster Referência da API do SDK da Web

Terminologia Básica

Visão geral

HappyOysterEngine

Viagem

Outras exportações

Exemplo

HappyOysterEngine

new HappyOysterEngine

Assinatura

Parâmetros

SDKConfig

Devoluções

Erros

HappyOysterEngine.updateToken

Assinatura

Parâmetros

Devoluções

Erros

HappyOysterEngine.createTravel

Assinatura

Parâmetros

CreateTravelConfig

Devoluções

Erros

Travel

Métodos

Estado

Eventos

Travel.can

Assinatura

Parâmetros

Devoluções

Disponibilidade

Erros

Viajar. Começar.

Assinatura

Parâmetros

Devoluções

StartTravelResult

Erros

Travel.on("statusChanged")

Assinatura

Parâmetros

Devoluções

Erros

Travel.on("firstFrameGenerated")

Assinatura

Parâmetros

Devoluções

Comportamento

Erros

Travel.onError

Assinatura

Parâmetros

Devoluções

Erros

Travel.sendCommand

Assinatura

Parâmetros

AdventureCommand

Referência de comando de controle

translation - Direção do Movimento

rotation - Ver Rotação

interaction — Ação de interação

Devoluções

Erros

Travel.sendInstruct

Assinatura

Parâmetros

InstructData

Devoluções

Erros

Travel.pause

Assinatura

Parâmetros

Devoluções

Erros

Travel.resume

Assinatura

`HappyOysterEngine`

`new HappyOysterEngine`

`SDKConfig`

`HappyOysterEngine.updateToken`

`HappyOysterEngine.createTravel`

`CreateTravelConfig`

`Travel`

`Travel.can`

`StartTravelResult`

`Travel.on("statusChanged")`

`Travel.on("firstFrameGenerated")`

`Travel.onError`

`Travel.sendCommand`

`AdventureCommand`

`translation` - Direção do Movimento

`rotation` - Ver Rotação

`interaction` — Ação de interação

`Travel.sendInstruct`

`InstructData`

`Travel.pause`

`Travel.resume`

`Travel.rewind`

`RewindTravelParams`

`RewindTravelResult`

`Travel.end`

`ErrorCode`

`isSdkError`