Referencia de la API del Web SDK de HappyOyster - Alibaba Cloud Model Studio

HappyOysterEngine configura el host y el modelo de Open Platform, actualiza el token de clave de API temporal de Model Studio y crea sesiones de Travel. Travel es el objeto de sesión devuelto por createTravel(); la sesión se ingresa e inicia solo después de llamar a travel.start(). Admite los modos de aventura, dirección y actuación.

HappyOysterEngine configura el host de Open Platform, actualiza el token de clave de API temporal de Model Studio y crea sesiones de Travel.

Travel es el objeto de sesión devuelto por createTravel(). La sesión se ingresa e inicia solo después de llamar a travel.start().

Terminología principal

Término	Significado	Notas
token	Token de clave de API temporal de Model Studio: al llamar a los servicios de Model Studio desde entornos no confiables como navegadores o aplicaciones móviles, genere una clave de API temporal a través de un backend seguro para evitar exponer una clave de API permanente. El SDK envía este token a Open Platform como una credencial HTTP Bearer.	Obtener credenciales de autenticación
ticket	Credencial de Travel del mundo HappyOyster: su backend llama a la API de credenciales utilizando autenticación AK (encabezado de gateway) para obtener una credencial de Travel de corta duración (`ticket`) que el cliente utiliza para ingresar a una sala. La API verifica la propiedad del mundo pero no crea un registro de Travel real.	Obtener credenciales de autenticación

Visión general

El SDK proporciona los siguientes objetos principales:

HappyOysterEngine

API	Descripción
`new HappyOysterEngine(config)`	Crea una instancia de Engine.
`updateToken(token)`	Actualiza el token de clave API temporal de Model Studio utilizado por las solicitudes posteriores de la API de Open Platform.
`createTravel(config)`	Crea una sesión de Travel.
`HappyOysterEngine.version`	La versión actual del SDK.
`HappyOysterEngine.metadata`	El nombre del paquete, la versión y el canal del paquete actuales del SDK.

Viaje

API	Descripción
`start()`	Inicia la sesión de Travel actual.
`on("statusChanged", handler)`	Se suscribe a los cambios de estado de la sesión.
`on("firstFrameGenerated", handler)`	Se suscribe a las notificaciones de URL del primer fotograma.
`on("travelInfoReady", handler)`	Se suscribe a los metadatos de sesión disponibles inmediatamente después de ingresar al travel.
`onError(handler)`	Se suscribe a los errores de tiempo de ejecución de la sesión.
`can(action)`	Verifica si la acción especificada se puede llamar actualmente.
`getInfo()`	Obtiene los metadatos de sesión disponibles; devuelve `null` antes de que estén disponibles.
`sendCommand(params)`	Envía un comando de control en tiempo real.
`sendInstruct(params)`	Envía instrucciones de dirección o contenido de prompt.
`pause()`	Pausa la sesión actual.
`resume()`	Reanuda una sesión pausada.
`rewind(params)`	Rebobina una sesión de dirección al tiempo especificado.
`end()`	Finaliza la sesión actual y libera sus recursos.

Otras exportaciones

Exportación	Descripción
`ErrorCode`	El objeto constante de códigos de error exportado por el SDK.
`isSdkError(error)`	Verifica si un error desconocido es un error estándar del SDK.
Tipos	Tipos públicos como `SDKConfig`, `Travel`, `StartTravelResult` y `AdventureCommand`.

Ejemplo

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: 'bailian-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-bailian-temporary-api-key-token')

`HappyOysterEngine`

HappyOysterEngine es el punto de entrada del Web SDK. Configura el host de Open Platform, administra el token de clave de API temporal de Model Studio utilizado por las solicitudes subsiguientes y crea sesiones de Travel.

NotaUna instancia de Engine actualmente gestiona solo un Travel activo a la vez. Finalice el Travel actual antes de iniciar una nueva sesión.

Después de establecer un token, ya sea en el constructor o mediante updateToken(), el SDK obtiene internamente la configuración de Feature Gate. Esto permite a la plataforma deshabilitar remotamente el SDK o requerir que las versiones anteriores se actualicen. Si la solicitud falla, el SDK opera en modo abierto y no bloquea la experiencia normal.

API	Descripción
`new HappyOysterEngine(config)`	Crea una instancia de Engine con el host de API y modelo requeridos, y token y nivel de registro opcionales.
`updateToken(token)`	Actualiza el token de clave API temporal de Model Studio utilizado por las solicitudes posteriores de Open Platform.
`createTravel(config)`	Crea una sesión de Travel que aún no ha iniciado.

`new HappyOysterEngine`

Crea una instancia de HappyOysterEngine.

Signature

new HappyOysterEngine(config: SDKConfig)

Parámetros

`SDKConfig`

Campo	Tipo	Obligatorio	Descripción
`APIHost`	`string`	Sí	Host de la API de Open Platform. Debe ser un host simple, como `open-platform.example.com`, sin `https://`, esquema ni ruta.
`model`	`string`	Sí	Identificador del modelo de Open Platform a utilizar. Obligatorio, sin valor predeterminado. Fijo para este Engine y compartido por todos sus Travels.
`token`	`string`	No	Token de clave de API temporal de Model Studio establecido durante la construcción. También se puede establecer posteriormente con `updateToken()`.
`logLevel`	`LogLevel`	No	Nivel de registro del SDK. El valor predeterminado es `none`.
`streamReadyTimeout`	`number`	No	Tiempo de espera para que `<video>` esté listo para reproducirse, se detenga o se reanude, en milisegundos. El valor predeterminado es `15000`.

Establezca model en un identificador de modelo, como happyoyster-1.0-adventure, un modelo de Aventura. Utilice el identificador de modelo correspondiente a su entorno de servicio objetivo. El SDK no elige un modelo basándose en el mode de la experiencia ni lo infiere del ticket.

Un Engine tiene un APIHost + model fijo. Reutilícelo para Travels sucesivos dirigidos al mismo servicio y modelo. Antes de cambiar cualquiera de estos valores, finalice el Travel activo y utilice un Engine configurado para el nuevo objetivo. Cree el mundo y emita su ticket contra el mismo servicio objetivo.

Valores devueltos

Devuelve una instancia de HappyOysterEngine.

Errores

Si falta config, o si APIHost, model, token, logLevel o streamReadyTimeout tiene un tipo o valor no válido, se lanza sincrónicamente un SdkError con el código ErrorCode.INVALID_ARGUMENT (10010001). Pasar una URL completa, una cadena vacía o un valor con ruta como APIHost no es válido.

model es obligatorio y debe ser una cadena no vacía después de recortar espacios; null, los valores que no sean cadenas y las cadenas con solo espacios en blanco no son válidos. Omitirlo o pasar undefined también genera un error de argumento; el SDK no tiene un modelo predeterminado.

`HappyOysterEngine.updateToken`

Actualiza el token de clave API temporal de Model Studio utilizado por las solicitudes posteriores de la API de Open Platform.

Signature

updateToken(token: string): void

Parámetros

Campo	Tipo	Obligatorio	Descripción
`token`	`string`	Sí	Token de clave API temporal de Model Studio. Pasar una cadena vacía borra el token actual.

Valores devueltos

No devuelve nada.

Errores

Si token no es una cadena, se lanza sincrónicamente un SdkError con el código ErrorCode.INVALID_ARGUMENT (10010001).

`HappyOysterEngine.createTravel`

Crea una instancia de sesión de Travel sin iniciarla.

Signature

createTravel(config: CreateTravelConfig): Travel

Parámetros

`CreateTravelConfig`

Campo	Tipo	Obligatorio	Descripción
`ticket`	`string`	Sí	Ticket utilizado para iniciar el Travel posteriormente.
`videoElement`	`HTMLVideoElement`	Sí	El elemento `<video>` utilizado para renderizar el video de la sesión. Debe proporcionarse al crear el Travel.
`maxExperienceTimeSec`	`60 \| 90 \| 120`	No	Duración máxima de la experiencia de Aventura, en segundos. Las sesiones de Dirección y Actuación ignoran este campo. Si se omite, el servidor aplica su valor predeterminado.

Valores devueltos

Devuelve una sesión Travel creada pero aún no iniciada. El invocador debe ejecutar entonces await travel.start() para ingresar a la sesión y esperar a que el video esté listo para reproducirse.

Cada instancia de HappyOysterEngine puede tener solo un Travel activo a la vez. Llame a await travel.end() antes de crear otro Travel.

Errores

createTravel() genera un SdkError sincrónicamente en los siguientes casos:

ErrorCode	Descripción
`10010001`	`config`, `ticket`, `videoElement` o `maxExperienceTimeSec` no es válido
`10010101`	Ya hay un Travel activo; llame primero a `travel.end()`

Los errores de inicio son expuestos por travel.start().

`Travel`

Travel representa una sesión creada por HappyOysterEngine.createTravel(). Inicialmente está inactiva. Después de llamar a travel.start(), el SDK ingresa a la sesión y espera a que el video esté listo para reproducirse.

Travel permite iniciar, pausar, reanudar, rebobinar y finalizar una sesión; enviar controles e indicaciones en tiempo real; y suscribirse a cambios de estado y errores de tiempo de ejecución.

Métodos

Método	Descripción
`start()`	Inicia la sesión de Travel actual.
`on("statusChanged", handler)`	Se suscribe a los cambios de estado de la sesión.
`on("firstFrameGenerated", handler)`	Se suscribe a las notificaciones de URL del primer fotograma.
`on("travelInfoReady", handler)`	Se suscribe a los metadatos de sesión disponibles inmediatamente después de ingresar al travel.
`onError(handler)`	Se suscribe a los errores de tiempo de ejecución de la sesión.
`can(action)`	Verifica si la acción especificada se puede llamar actualmente.
`getInfo()`	Obtiene los metadatos de sesión disponibles; devuelve `null` antes de que estén disponibles.
`sendCommand(params)`	Envía un comando de control en tiempo real.
`sendInstruct(params)`	Envía instrucciones de dirección o contenido de prompt.
`pause()`	Pausa la sesión actual.
`resume()`	Reanuda una sesión pausada.
`rewind(params)`	Rebobina la sesión actual al tiempo especificado.
`end()`	Finaliza la sesión actual y libera sus recursos.

Status

Status	Descripción
`idle`	La sesión no ha iniciado.
`prepare`	La sesión se está iniciando y esperando que el video esté disponible para reproducción.
`running`	La sesión se está ejecutando.
`paused`	La sesión está en pausa y se puede reanudar o rebobinar.
`completed`	La sesión ha finalizado normalmente y sus recursos han sido liberados.

Eventos

Suscríbase a eventos con travel.on(event, handler). El método devuelve una función de cancelación de suscripción.

Evento	Callback	Descripción
`statusChanged`	`(status: TravelStatus) => void`	El estado de la sesión cambió.
`firstFrameGenerated`	`(firstFrame: string) => void`	Emitido durante `start()` cuando Open Platform devuelve una URL de primer fotograma no vacía; antes de que `start()` se resuelva y el video esté listo para reproducirse.
`travelInfoReady`	`(info: TravelInfo) => void`	Emitido después de que regresa enter-travel y antes de que se conecte RTC. `getInfo()` devuelve los mismos datos; si existe un primer fotograma, le sigue `firstFrameGenerated`.
`error`	`(error: unknown) => void`	Un error de tiempo de ejecución de la sesión.

`Travel.can`

Verifica si una acción está disponible para el estado actual y la capacidad de la sesión.

Signature

can(action: TravelAction): boolean

Parámetros

Campo	Tipo	Obligatorio	Descripción
`action`	`TravelAction`	Sí	Acción a verificar: `start` / `sendCommand` / `sendInstruct` / `pause` / `resume` / `rewind` / `end`.

Valores devueltos

Devuelve un boolean. true significa que la acción está disponible actualmente; false significa que el estado actual, el modo o la capacidad de la sesión no cumplen sus condiciones previas.

Disponibilidad

acción	Disponibilidad
`start`	Travel todavía está `idle`, no se ha cerrado y nunca se ha iniciado.
`sendCommand`	`running`, con el modo Travel configurado como Adventure (`1`).
`sendInstruct`	`running` o `paused`, con el modo establecido en Dirección (`2`) o Actuación (`3`), y no `scriptlist`.
`pause`	`running`, y la sesión actual admite pausas.
`resume`	`paused`, y la sesión actual admite reanudación.
`rewind`	`paused` en una sesión de dirección que admite rebobinado; Actuación no lo admite.
`end`	Travel no se ha cerrado.

Errores

Este método no genera errores de negocio. Las acciones desconocidas devuelven false.

`Travel.start`

Inicia la sesión de Travel actual.

Signature

start(): Promise<StartTravelResult>

Parámetros

Sin parámetros.

Valores devueltos

Devuelve un Promise<StartTravelResult>, que se resuelve después de que inicia la sesión y el video está disponible para reproducción.

Después de que regresa enter-travel, el SDK emite travelInfoReady antes de conectar RTC. Los suscriptores tardíos pueden llamar a travel.getInfo(); esta devuelve null antes de que los metadatos estén disponibles. Si la respuesta incluye un firstFrame no vacío, firstFrameGenerated se emitirá de todos modos.

`StartTravelResult`

Campo	Tipo	Descripción
`encryptedTravelId`	`string`	ID de la sesión de Travel actual.
`mode`	`number`	Modo de sesión: `1` = Aventura (exploración del mundo), `2` = Dirección (dirección en tiempo real), `3` = Actuación.
`creationModel`	`string`	Modelo de creación de mundo; los valores comunes son `simple` y `scriptlist`.
`firstFrame`	`string \| null`	URL de la imagen del primer fotograma; `null` si el servidor no devuelve ninguna.
`maxExperienceTimeSec`	`60 \| 90 \| 120 \| null`	Duración máxima de la experiencia de Aventura, en segundos. `null` para sesiones de Dirección y Actuación o cuando el servidor no devuelve este campo.
`aspectRatio`	`"9:16" \| "16:9" \| null`	Relación de aspecto de actuación; `null` para otros modos o cuando el servidor no la devuelve.

Errores

start() rechaza la promesa y emite un evento error en los siguientes casos. Utilice isSdkError(err) para verificar el error y leer err.code y err.message.

ErrorCode	Descripción
`10010002`	La función del SDK está deshabilitada (`SDK_FEATURE_DISABLED`)
`10020101`	No se puede iniciar: el estado actual no lo permite, Open Platform no está configurada o falló el ingreso a la sesión
`10020102`	No se puede iniciar: la configuración de sesión devuelta por el servidor está incompleta
`10020103`	No se puede iniciar: falló la conexión de la transmisión de video o la solicitud de bandera de función del SDK
`10020104`	No se puede iniciar: se agotó el tiempo de espera para el stream de video (utiliza el mayor entre `streamReadyTimeout` y el `noStreamAutoEndTimeoutSec` del servidor)
`10020105`	No se puede iniciar: se agotó el tiempo de espera para que el video estuviera listo para reproducirse (controlado por `streamReadyTimeout`; predeterminado: 15 segundos)
`10000001`–`10000012`	Error de parámetro, recurso o servidor de Open Platform

`Travel.on("statusChanged")`

Se suscribe a los cambios de estado de la sesión.

Signature

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

Parámetros

Campo	Tipo	Obligatorio	Descripción
`handler`	`(status: TravelStatus) => void`	Sí	Callback invocado cuando cambia el estado.

Valores devueltos

Devuelve una función de cancelación de suscripción. TravelStatus es uno de idle / prepare / running / paused / completed.

Errores

Este método no genera errores de negocio.

`Travel.on("firstFrameGenerated")`

Se suscribe a las notificaciones de URL del primer fotograma.

Signature

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

Parámetros

Campo	Tipo	Obligatorio	Descripción
`handler`	`(firstFrame: string) => void`	Sí	Callback invocado cuando la URL del primer fotograma está disponible.

Valores devueltos

Devuelve una función para cancelar la suscripción.

Comportamiento

Se emite solo durante travel.start(). Después de que el SDK llama a enter-travel de Open Platform y recibe un firstFrame no vacío, emite el evento inmediatamente, generalmente después de statusChanged("prepare") pero antes de que start() se resuelva y el video esté listo para reproducirse. El evento no se emite si la respuesta no contiene una URL de primer fotograma.

Errores

Este método no genera errores de negocio.

`Travel.onError`

Se suscribe a los errores de tiempo de ejecución de la sesión.

Signature

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

Parámetros

Campo	Tipo	Obligatorio	Descripción
`handler`	`(error: unknown) => void`	Sí	Callback invocado cuando ocurre un error de tiempo de ejecución.

Valores devueltos

Devuelve una función de cancelación de suscripción. Use isSdkError para restringir el objeto de error a SdkError.

Errores

Este método no genera errores de negocio.

`Travel.sendCommand`

Envía un comando de control en tiempo real.

Signature

sendCommand(params: AdventureCommand): Promise<void>

Parámetros

`AdventureCommand`

Campo	Tipo	Obligatorio	Descripción
`translation`	`string`	No	Dirección de movimiento. El valor predeterminado es `None` cuando se omite.
`rotation`	`string`	No	Rotación de vista. El valor predeterminado es `None` cuando se omite.
`interaction`	`string`	No	Acción de interacción. El valor predeterminado es `None` cuando se omite.

Referencia de comandos de control

`translation` — Dirección de movimiento

Describe el movimiento del personaje, admitiendo ocho direcciones y combinaciones.

Valor	Dirección
`"Front"`	Adelante
`"Back"`	Atrás
`"Left"`	Izquierda
`"Right"`	Derecha
`"Front_Left"`	Adelante-izquierda
`"Front_Right"`	Adelante-derecha
`"Back_Left"`	Atrás-izquierda
`"Back_Right"`	Atrás-derecha
`"None"`	Estacionario

`rotation` — Rotación de vista

Simula la rotación de vista basada en mouse en ocho direcciones.

Valor	Dirección
`"Mouse_Up"`	Arriba
`"Mouse_Down"`	Abajo
`"Mouse_Left"`	Izquierda
`"Mouse_Right"`	Derecha
`"Mouse_Up_Left"`	Arriba-izquierda
`"Mouse_Up_Right"`	Arriba-derecha
`"Mouse_Down_Left"`	Abajo-izquierda
`"Mouse_Down_Right"`	Abajo-derecha
`"None"`	None

`interaction` — Acción de interacción

Valor	Acción
`"Jump"`	Saltar
`"Attack"`	Atacar
`"Crouch"`	Agacharse
`"Sprint"`	Correr
`"None"`	None

Valores devueltos

Devuelve un Promise<void> que se resuelve después de enviar el comando.

Errores

sendCommand() se rechaza en los siguientes casos:

ErrorCode	Descripción
`10010001`	`params` o un parámetro de movimiento, rotación o interacción no es válido
`10020501`	El estado actual o el modo de sesión no permite comandos, o falló el comando de transmisión de video

`Travel.sendInstruct`

Envía instrucciones de dirección o contenido de prompt.

Signature

sendInstruct(params: InstructData): Promise<void>

Parámetros

`InstructData`

Campo	Tipo	Obligatorio	Descripción
`content`	`string`	Sí	Contenido del prompt a enviar.

Valores devueltos

Devuelve un Promise<void> que se resuelve después de que Open Platform recibe y procesa la instrucción.

Errores

sendInstruct() se rechaza y emite un evento error en los siguientes casos:

ErrorCode	Descripción
`10020101`	La sesión no ha iniciado
`10020601`	Error al enviar la instrucción de Directing
`10000001`–`10000012`	Error de parámetro, recurso o servidor de Open Platform

`Travel.pause`

Pausa la sesión actual.

Signature

pause(): Promise<void>

Parámetros

Sin parámetros.

Valores devueltos

Devuelve un Promise<void> que se resuelve después de que se detiene la reproducción de video.

Errores

pause() se rechaza en los siguientes casos:

ErrorCode	Descripción
`10020201`	El estado actual, el modo de sesión o la capacidad de sesión no permiten pausar, o falló la solicitud de pausa
`10020202`	Tiempo de espera agotado esperando que el backend reporte la transmisión de video como pausada (15 segundos)
`10000001`–`10000012`	Error de parámetro, recurso o servidor de Open Platform

`Travel.resume`

Reanuda una sesión pausada.

Signature

resume(): Promise<void>

Parámetros

Sin parámetros.

Valores devueltos

Devuelve un Promise<void> que se resuelve después de que el video vuelve a estar disponible para reproducción.

Errores

resume() se rechaza en los siguientes casos:

ErrorCode	Descripción
`10020301`	El estado actual, el modo de sesión o la capacidad de sesión no permiten reanudar, o falló la solicitud de reanudación
`10020302`	Tiempo de espera agotado esperando que el video esté disponible para reproducción nuevamente (15 segundos)
`10000001`–`10000012`	Error de parámetro, recurso o servidor de Open Platform

`Travel.rewind`

Rebobina la sesión actual al tiempo especificado.

Signature

rewind(params: RewindTravelParams): Promise<RewindTravelResult>

Parámetros

`RewindTravelParams`

Campo	Tipo	Obligatorio	Descripción
`rewindToSec`	`number`	Sí	Tiempo objetivo en segundos. Solo se admiten múltiplos de 4 (por ejemplo, `4`, `8` o `12`). El servidor redondea otros valores hacia abajo (por ejemplo, `7` se convierte en `4`).

Valores devueltos

Devuelve un Promise<RewindTravelResult> que se resuelve después de completar el rebobinado y reanudar la reproducción.

`RewindTravelResult`

Campo	Tipo	Descripción
`resumedAtSec`	`number`	El tiempo real en segundos en el que el servidor reanudó la reproducción.

Errores

rewind() se rechaza y emite un evento error en los siguientes casos:

ErrorCode	Descripción
`10020101`	La sesión no ha iniciado
`10020401`	No se puede rebobinar: primero se debe pausar la sesión y detener la reproducción de video, o bien falló la solicitud de rebobinado o la reconexión RTC
`10020402`	Tiempo de espera agotado esperando que el video se reanude después de rebobinar (15 segundos)
`10000001`–`10000012`	Error de parámetro, recurso o servidor de Open Platform

`Travel.end`

Finaliza la sesión actual y libera sus recursos.

Signature

end(): Promise<void>

Parámetros

Sin parámetros.

Valores devueltos

Devuelve un Promise<void> que se resuelve después de finalizar la limpieza.

Errores

Los errores de limpieza no se lanzan al llamador; end() hace todo lo posible por liberar recursos.

Manejo de errores

El SDK expone errores de tiempo de ejecución mediante rechazos de Promise o eventos error. Los errores son objetos SdkError; utilice isSdkError(err) y lea err.code y err.message.

Los errores reconocidos de Open Platform se asignan al rango 10000001–10000012, y err.message contiene el mensaje de la plataforma. Consulte la sección de Errores de cada API de Travel para ver los códigos específicos de cada método.

Referencia de ErrorCode

Rangos de códigos de error:

100000xx: Errores mapeados de Open Platform
1001xxxx: Errores del cliente Engine
1002xxxx: Errores del cliente Travel

code	name	Descripción
`10000001`	`OPEN_PLATFORM_PARAM_INVALID`	Parámetros de solicitud no válidos (devueltos por Open Platform)
`10000002`	`OPEN_PLATFORM_RESOURCE_NOT_FOUND`	Recurso no encontrado (Travel faltante, no propio, en otro espacio de trabajo o artefacto no listo)
`10000003`	`OPEN_PLATFORM_WORLD_NOT_OWNED`	El mundo no existe, fue eliminado o no pertenece al desarrollador actual
`10000004`	`OPEN_PLATFORM_SYSTEM_ERROR`	Error del sistema
`10000005`	`OPEN_PLATFORM_TICKET_INVALID`	El ticket es inválido o ha expirado
`10000006`	`OPEN_PLATFORM_TICKET_USED`	El ticket ya ha sido utilizado (credencial de un solo uso)
`10000007`	`OPEN_PLATFORM_WORLD_NOT_READY`	El mundo no está listo y no se puede ingresar
`10000008`	`OPEN_PLATFORM_INFERENCE_ALLOCATE_FAILED`	Falló la asignación de recursos de inferencia (capacidad insuficiente, fallo en la creación del stream, fallo en la inicialización de la sesión, etc.)
`10000009`	`OPEN_PLATFORM_MAIN_API_KEY_REQUIRED`	Esta API acepta solo la clave API principal (las claves API temporales no son compatibles)
`10000010`	`OPEN_PLATFORM_CONTENT_MODERATION`	Entrada rechazada por moderación de contenido
`10000011`	`OPEN_PLATFORM_CONTENT_COPYRIGHT`	La imagen de entrada infringe la política de derechos de autor o propiedad intelectual
`10000012`	`OPEN_PLATFORM_STATE_CONFLICT`	La solicitud entra en conflicto con el estado actual del recurso
`10010001`	`INVALID_ARGUMENT`	Falló la validación de argumentos del cliente SDK (no mapeado desde Open Platform)
`10010002`	`SDK_FEATURE_DISABLED`	La función del SDK está deshabilitada
`10010101`	`ACTIVE_TRAVEL_EXISTS`	Ya hay un Travel activo
`10020001`	`STREAM_DISCONNECTED_WHILE_PLAYING`	Transmisión de video desconectada durante la reproducción
`10020101`	`START_REQUEST_FAILED`	Error en la solicitud de inicio de sesión
`10020102`	`START_RTC_CONFIG_MISSING`	Falta la configuración de la transmisión de video durante el inicio
`10020103`	`START_JOIN_CHANNEL_FAILED`	Error en la conexión del flujo de video
`10020104`	`START_REMOTE_USER_TIMEOUT`	Tiempo de espera agotado al esperar el flujo de video
`10020105`	`START_STREAM_TIMEOUT`	Tiempo de espera agotado esperando que el video esté disponible para reproducción
`10020201`	`PAUSE_REQUEST_FAILED`	Error en la solicitud de pausa
`10020202`	`PAUSE_STREAM_TIMEOUT`	Tiempo de espera agotado al esperar que el video se pause
`10020301`	`RESUME_REQUEST_FAILED`	Error en la solicitud de reanudación
`10020302`	`RESUME_STREAM_TIMEOUT`	Tiempo de espera agotado al esperar que el video se reanude
`10020401`	`REWIND_REQUEST_FAILED`	Error en la solicitud de rebobinado
`10020402`	`REWIND_STREAM_TIMEOUT`	Tiempo de espera agotado esperando que el video se reanude después de rebobinar
`10020501`	`SEND_COMMAND_FAILED`	Error al enviar el comando de control en tiempo real
`10020601`	`INSTRUCT_REQUEST_FAILED`	Error al enviar la instrucción de Directing
`10020701`	`END_REQUEST_FAILED`	Error en la solicitud de finalización de sesión

Otras exportaciones

Exportaciones de tiempo de ejecución

Exportación	Tipo	Descripción
`HappyOysterEngine`	`class`	Cliente SDK que configura Open Platform, actualiza el token y crea sesiones de Travel.
`HappyOysterEngine.version`	`string`	La versión actual del SDK.
`HappyOysterEngine.metadata`	`SDKMetadata`	El nombre del paquete, la versión y el canal del paquete actuales del SDK.
`ErrorCode`	`const`	El objeto constante de códigos de error exportado por el SDK.
`isSdkError`	`function`	Verifica si un error desconocido es un error estándar del SDK.

`ErrorCode`

El objeto constante de códigos de error exportado por el SDK. Compárelo con SdkError.code en lugar de dispersar literales numéricos en el código de la aplicación.

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

`isSdkError`

Verifica si un error desconocido es un error estándar del SDK. Cuando devuelve true, TypeScript restringe el error a SdkError, lo que permite acceder de forma segura a code y 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

Los siguientes tipos se exportan desde el punto de entrada del paquete y se pueden importar directamente desde @happy-oyster/js-sdk. Existen solo en tiempo de compilación de TypeScript y no generan código en tiempo de ejecución.

Tipo	Descripción
`SDKConfig`	Tipo de parámetro del constructor de `HappyOysterEngine`.
`LogLevel`	Niveles de registro del SDK: `verbose` / `debug` / `info` / `warn` / `error` / `none`.
`SDKMetadata`	Metadatos del paquete SDK: `version`, `packageName`, `packageChannel`.
`SDKPackageChannel`	Canales de paquete del SDK: `internal` / `public` / `unknown`.
`CreateTravelConfig`	Tipo de parámetro de `createTravel(config)`.
`StartTravelResult`	Metadatos de sesión de `start()` devueltos cuando se resuelve la promesa.
`TravelInfo`	Metadatos de sesión utilizados por `travelInfoReady`, `getInfo()` y `StartTravelResult`.
`TravelAspectRatio`	Relación de aspecto de actuación: `"9:16"` / `"16:9"`.
`Travel`	Contrato de sesión pública de `createTravel()` devuelto por el método.
`TravelStatus`	Estados de sesión locales del SDK: `idle` / `prepare` / `running` / `paused` / `completed`.
`TravelAction`	Nombres de acción compatibles con `can(action)`.
`AdventureCommand`	Tipo de parámetro de `sendCommand(params)`.
`InstructData`	Tipo de parámetro de `sendInstruct(params)`.
`RewindTravelParams`	Tipo de parámetro de `rewind(params)`.
`RewindTravelResult`	Datos de `rewind(params)` devueltos cuando se resuelve la promesa.
`SDKError`	Estructura de error del SDK que contiene `code` y `message`.
`SdkError`	Tipo de error que combina `Error` de tiempo de ejecución y `SDKError`.
`ErrorCodeValue`	Unión de todos los valores de código de error en el objeto `ErrorCode`.

Terminología principal

Visión general

HappyOysterEngine

Viaje

Otras exportaciones

Ejemplo

HappyOysterEngine

new HappyOysterEngine

Signature

Parámetros

SDKConfig

Valores devueltos

Errores

HappyOysterEngine.updateToken

Signature

Parámetros

Valores devueltos

Errores

HappyOysterEngine.createTravel

Signature

Parámetros

CreateTravelConfig

Valores devueltos

Errores

Travel

Métodos

Status

Eventos

Travel.can

Signature

Parámetros

Valores devueltos

Disponibilidad

Errores

Travel.start

Signature

Parámetros

Valores devueltos

StartTravelResult

Errores

Travel.on("statusChanged")

Signature

Parámetros

Valores devueltos

Errores

Travel.on("firstFrameGenerated")

Signature

Parámetros

Valores devueltos

Comportamiento

Errores

Travel.onError

Signature

Parámetros

Valores devueltos

Errores

Travel.sendCommand

Signature

Parámetros

AdventureCommand

Referencia de comandos de control

translation — Dirección de movimiento

rotation — Rotación de vista

interaction — Acción de interacción

Valores devueltos

Errores

Travel.sendInstruct

Signature

Parámetros

InstructData

Valores devueltos

Errores

Travel.pause

Signature

Parámetros

Valores devueltos

Errores

Travel.resume

Signature

Parámetros

`HappyOysterEngine`

`new HappyOysterEngine`

`SDKConfig`

`HappyOysterEngine.updateToken`

`HappyOysterEngine.createTravel`

`CreateTravelConfig`

`Travel`

`Travel.can`

`Travel.start`

`StartTravelResult`

`Travel.on("statusChanged")`

`Travel.on("firstFrameGenerated")`

`Travel.onError`

`Travel.sendCommand`

`AdventureCommand`

`translation` — Dirección de movimiento

`rotation` — Rotación de vista

`interaction` — Acción de interacción

`Travel.sendInstruct`

`InstructData`

`Travel.pause`

`Travel.resume`

`Travel.rewind`

`RewindTravelParams`

`RewindTravelResult`

`Travel.end`

`ErrorCode`

`isSdkError`