Referensi API Web SDK HappyOyster - Alibaba Cloud Model Studio

HappyOysterEngine mengonfigurasi host Open Platform, memperbarui token kunci API sementara Model Studio, dan membuat sesi Travel. Travel adalah objek sesi yang dikembalikan oleh createTravel(). Sesi dimasuki dan dimulai hanya setelah travel.start() dipanggil.

Terminologi Inti

Istilah	Arti	Catatan
token	Token kunci API sementara Model Studio: saat memanggil layanan Model Studio dari lingkungan yang tidak tepercaya seperti browser atau aplikasi seluler, hasilkan Kunci API sementara melalui backend yang aman untuk menghindari paparan Kunci API permanen. SDK mengirimkan token ini ke Open Platform sebagai kredensial HTTP Bearer.	Mendapatkan kredensial autentikasi
ticket	Kredensial Travel dunia HappyOyster: backend Anda memanggil API kredensial menggunakan autentikasi AK (header gateway) untuk mendapatkan kredensial Travel berumur pendek (`ticket`) yang digunakan klien untuk memasuki ruangan. API memverifikasi kepemilikan dunia tetapi tidak membuat catatan Travel yang sebenarnya.	Mendapatkan kredensial autentikasi

Ikhtisar

SDK menyediakan objek utama berikut:

HappyOysterEngine

API	Deskripsi
`new HappyOysterEngine(config)`	Membuat instance Engine.
`updateToken(token)`	Memperbarui token API-key sementara Model Studio yang digunakan oleh permintaan API Open Platform berikutnya.
`createTravel(config)`	Membuat sesi Travel.
`HappyOysterEngine.version`	Versi SDK saat ini.
`HappyOysterEngine.metadata`	Nama paket SDK, versi, dan saluran paket saat ini.

Travel

API	Deskripsi
`start()`	Memulai sesi Travel saat ini.
`on("statusChanged", handler)`	Berlangganan perubahan status sesi.
`on("firstFrameGenerated", handler)`	Berlangganan notifikasi URL frame pertama.
`on("travelInfoReady", handler)`	Berlangganan metadata sesi yang tersedia segera setelah enter-travel.
`onError(handler)`	Berlangganan kesalahan runtime sesi.
`can(action)`	Memeriksa apakah tindakan yang ditentukan saat ini dapat dipanggil.
`getInfo()`	Mendapatkan metadata sesi yang tersedia; mengembalikan `null` sebelum tersedia.
`sendCommand(params)`	Mengirim perintah kontrol real-time.
`sendInstruct(params)`	Mengirim instruksi Directing atau konten prompt.
`pause()`	Menjeda sesi saat ini.
`resume()`	Melanjutkan sesi yang dijeda.
`rewind(params)`	Memutar mundur sesi Directing ke waktu yang ditentukan.
`end()`	Mengakhiri sesi saat ini dan melepaskan sumber dayanya.

Ekspor Lainnya

Ekspor	Deskripsi
`ErrorCode`	Objek konstanta kode kesalahan yang diekspor oleh SDK.
`isSdkError(error)`	Memeriksa apakah kesalahan yang tidak diketahui merupakan kesalahan SDK standar.
Tipe	Tipe publik seperti `SDKConfig`, `Travel`, `StartTravelResult`, dan `AdventureCommand`.

Contoh

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 adalah titik masuk Web SDK. Ini mengonfigurasi host Open Platform, mengelola token kunci API sementara Model Studio yang digunakan oleh permintaan selanjutnya, dan membuat sesi Travel.

Instance Engine saat ini hanya mengelola satu Travel aktif pada satu waktu. Akhiri Travel saat ini sebelum memulai sesi baru.Setelah token ditetapkan baik dalam konstruktor maupun melalui updateToken(), SDK secara internal mengambil konfigurasi Feature Gate. Hal ini memungkinkan platform untuk menonaktifkan SDK dari jarak jauh atau mewajibkan versi lama untuk melakukan peningkatan. Jika permintaan gagal, SDK tetap beroperasi dan tidak memblokir pengalaman normal.

API	Deskripsi
`new HappyOysterEngine(config)`	Membuat instance Engine dengan host API dan model yang wajib diisi, serta token dan level log opsional.
`updateToken(token)`	Memperbarui token API-key sementara Model Studio yang digunakan oleh permintaan Open Platform berikutnya.
`createTravel(config)`	Membuat sesi Travel yang belum dimulai.

`new HappyOysterEngine`

Membuat instance HappyOysterEngine.

Signature

new HappyOysterEngine(config: SDKConfig)

Parameter

`SDKConfig`

Bidang	Tipe	Wajib	Deskripsi
`APIHost`	`string`	Ya	Host API Open Platform. Harus berupa host murni, seperti `open-platform.example.com`, tanpa `https://`, skema, atau jalur.
`model`	`string`	Ya	Pengidentifikasi model Open Platform yang akan digunakan. Wajib diisi, tanpa nilai default. Tetap untuk Engine ini dan dibagikan oleh semua Travel-nya.
`token`	`string`	Tidak	Token kunci API sementara Model Studio yang ditetapkan selama konstruksi. Token ini juga dapat ditetapkan nanti dengan `updateToken()`.
`logLevel`	`LogLevel`	Tidak	Level log SDK. Defaultnya adalah `none`.
`streamReadyTimeout`	`number`	Tidak	Batas waktu tunggu agar `<video>` dapat diputar, berhenti, atau dilanjutkan, dalam milidetik. Defaultnya adalah `15000`.

Tetapkan model ke pengidentifikasi model, seperti happyoyster-1.0-adventure, sebuah model Adventure. Gunakan pengidentifikasi model untuk lingkungan layanan target Anda. SDK tidak memilih model dari pengalaman mode atau menyimpulkannya dari tiket. Engine memiliki APIHost + model yang tetap. Gunakan kembali untuk Travel berturut-turut yang menargetkan layanan dan model yang sama. Sebelum mengganti salah satu nilai, akhiri Travel yang aktif dan gunakan Engine yang dikonfigurasi untuk target baru. Buat dunia dan terbitkan tiketnya terhadap target layanan yang sama.

Return

Mengembalikan instance HappyOysterEngine.

Error

Jika config hilang, atau jika APIHost, model, token, logLevel, atau streamReadyTimeout memiliki tipe atau nilai yang tidak valid, sebuah SdkError dengan kode ErrorCode.INVALID_ARGUMENT (10010001) dilempar secara sinkron. Meneruskan URL lengkap, string kosong, atau nilai dengan jalur sebagai APIHost adalah tidak valid. model wajib diisi dan harus berupa string yang tidak kosong setelah pemangkasan; null, nilai bukan string, dan string yang hanya berisi spasi tidak valid. Mengabaikannya atau meneruskan undefined juga menimbulkan error argumen; SDK tidak memiliki model default.

`HappyOysterEngine.updateToken`

Memperbarui token API-key sementara Model Studio yang digunakan oleh permintaan API Open Platform berikutnya.

Signature

updateToken(token: string): void

Parameter

Bidang	Tipe	Wajib	Deskripsi
`token`	`string`	Ya	Token API-key sementara Model Studio. Meneruskan string kosong akan menghapus token saat ini.

Return

Tidak mengembalikan nilai apa pun.

Error

Jika token bukan string, sebuah SdkError dengan kode ErrorCode.INVALID_ARGUMENT (10010001) dilempar secara sinkron.

`HappyOysterEngine.createTravel`

Membuat instance sesi Travel tanpa memulainya.

Signature

createTravel(config: CreateTravelConfig): Travel

Parameter

`CreateTravelConfig`

Bidang	Tipe	Wajib	Deskripsi
`ticket`	`string`	Ya	Tiket yang digunakan untuk memulai Travel nanti.
`videoElement`	`HTMLVideoElement`	Ya	Elemen `<video>` yang digunakan untuk merender video sesi. Elemen ini harus disediakan saat membuat Travel.
`maxExperienceTimeSec`	`60 \| 90 \| 120`	Tidak	Durasi pengalaman Adventure maksimum, dalam detik. Sesi Directing dan Acting mengabaikan bidang ini. Jika dihilangkan, server menerapkan nilai defaultnya.

Return

Mengembalikan sesi Travel yang telah dibuat namun belum dimulai. Pemanggil kemudian harus menjalankan await travel.start() untuk memasuki sesi dan menunggu hingga video dapat diputar. Setiap instance HappyOysterEngine hanya boleh memiliki satu Travel aktif pada satu waktu. Panggil await travel.end() sebelum membuat Travel lain.

Error

createTravel() melempar SdkError secara sinkron dalam kasus berikut:

ErrorCode	Deskripsi
`10010001`	`config`, `ticket`, `videoElement`, atau `maxExperienceTimeSec` tidak valid
`10010101`	Travel sudah aktif; panggil `travel.end()` terlebih dahulu

Kesalahan startup diekspos oleh travel.start().

`Travel`

Travel merepresentasikan sesi yang dibuat oleh HappyOysterEngine.createTravel(). Awalnya tidak aktif. Setelah travel.start() dipanggil, SDK memasuki sesi dan menunggu hingga video dapat diputar. Travel mendukung memulai, menjeda, melanjutkan, memundurkan, dan mengakhiri sesi; mengirim kontrol dan prompt real-time; serta berlangganan perubahan status dan error runtime.

Metode

Metode	Deskripsi
`start()`	Memulai sesi Travel saat ini.
`on("statusChanged", handler)`	Berlangganan perubahan status sesi.
`on("firstFrameGenerated", handler)`	Berlangganan notifikasi URL frame pertama.
`on("travelInfoReady", handler)`	Berlangganan metadata sesi yang tersedia segera setelah enter-travel.
`onError(handler)`	Berlangganan kesalahan runtime sesi.
`can(action)`	Memeriksa apakah tindakan yang ditentukan saat ini dapat dipanggil.
`getInfo()`	Mendapatkan metadata sesi yang tersedia; mengembalikan `null` sebelum tersedia.
`sendCommand(params)`	Mengirim perintah kontrol real-time.
`sendInstruct(params)`	Mengirim instruksi Directing atau konten prompt.
`pause()`	Menjeda sesi saat ini.
`resume()`	Melanjutkan sesi yang dijeda.
`rewind(params)`	Memutar mundur sesi saat ini ke waktu yang ditentukan.
`end()`	Mengakhiri sesi saat ini dan melepaskan sumber dayanya.

Status

Status	Deskripsi
`idle`	Sesi belum dimulai.
`prepare`	Sesi sedang dimulai dan menunggu video dapat diputar.
`running`	Sesi sedang berjalan.
`paused`	Sesi dijeda dan dapat dilanjutkan atau diputar mundur.
`completed`	Sesi telah berakhir secara normal dan sumber dayanya telah dilepaskan.

Event

Berlangganan event dengan travel.on(event, handler). Metode ini mengembalikan fungsi unsubscribe.

Peristiwa	Callback	Deskripsi
`statusChanged`	`(status: TravelStatus) => void`	Status sesi berubah.
`firstFrameGenerated`	`(firstFrame: string) => void`	Dipancarkan selama `start()` ketika Open Platform mengembalikan URL frame pertama yang tidak kosong; sebelum `start()` terselesaikan dan video dapat diputar.
`travelInfoReady`	`(info: TravelInfo) => void`	Dipancarkan setelah enter-travel kembali dan sebelum RTC terhubung. `getInfo()` mengembalikan data yang sama; jika frame pertama ada, `firstFrameGenerated` menyusul.
`error`	`(error: unknown) => void`	Error runtime sesi.

`Travel.can`

Memeriksa apakah suatu tindakan tersedia untuk status dan kapabilitas sesi saat ini.

Signature

can(action: TravelAction): boolean

Parameter

Bidang	Tipe	Wajib	Deskripsi
`action`	`TravelAction`	Ya	Tindakan yang akan diperiksa: `start` / `sendCommand` / `sendInstruct` / `pause` / `resume` / `rewind` / `end`.

Return

Mengembalikan boolean. true berarti tindakan saat ini tersedia; false berarti status, mode, atau kapabilitas sesi saat ini tidak memenuhi prasyaratnya.

Ketersediaan

action	Ketersediaan
`start`	Travel masih `idle`, belum ditutup, dan belum pernah dimulai.
`sendCommand`	`running`, dengan mode Travel diatur ke Adventure (`1`).
`sendInstruct`	`running` atau `paused`, dengan mode diatur ke Directing (`2`) atau Acting (`3`), dan bukan `scriptlist`.
`pause`	`running`, dan sesi saat ini mendukung penjedaan.
`resume`	`paused`, dan sesi saat ini mendukung kelanjutan.
`rewind`	`paused` dalam sesi Directing yang mendukung pemutaran mundur; Acting tidak mendukungnya.
`end`	Travel belum ditutup.

Error

Metode ini tidak melempar kesalahan bisnis. Tindakan yang tidak dikenal mengembalikan false.

`Travel.start`

Memulai sesi Travel saat ini.

Signature

start(): Promise<StartTravelResult>

Parameter

Tidak ada parameter.

Return

Mengembalikan Promise<StartTravelResult>, yang terselesaikan setelah sesi dimulai dan video dapat diputar. Setelah enter-travel kembali, SDK memancarkan travelInfoReady sebelum menghubungkan RTC. Pelanggan yang terlambat dapat memanggil travel.getInfo(); ini mengembalikan null sebelum metadata tersedia. Jika respons menyertakan firstFrame yang tidak kosong, firstFrameGenerated tetap menyusul.

`StartTravelResult`

Bidang	Tipe	Deskripsi
`encryptedTravelId`	`string`	ID sesi Travel saat ini.
`mode`	`number`	Mode sesi: `1` = Adventure (eksplorasi dunia), `2` = Directing (pengarahan real-time), `3` = Acting.
`creationModel`	`string`	Model pembuatan World; nilai umum adalah `simple` dan `scriptlist`.
`firstFrame`	`string \| null`	URL gambar frame pertama; `null` jika server tidak mengembalikannya.
`maxExperienceTimeSec`	`60 \| 90 \| 120 \| null`	Durasi pengalaman Adventure maksimum, dalam detik. `null` untuk sesi Directing dan Acting atau ketika server tidak mengembalikan bidang ini.
`aspectRatio`	`"9:16" \| "16:9" \| null`	Rasio aspek Acting; `null` untuk mode lain atau saat server tidak mengembalikannya.

Error

start() ditolak dan memancarkan event error dalam kasus berikut. Gunakan isSdkError(err) untuk memeriksa error serta membaca err.code dan err.message.

ErrorCode	Deskripsi
`10010002`	Fitur SDK dinonaktifkan (`SDK_FEATURE_DISABLED`)
`10020101`	Tidak dapat memulai: status saat ini tidak mengizinkan, Open Platform belum dikonfigurasi, atau gagal memasuki sesi
`10020102`	Tidak dapat memulai: konfigurasi sesi yang dikembalikan oleh server tidak lengkap
`10020103`	Tidak dapat memulai: koneksi stream video gagal atau permintaan feature-flag SDK gagal
`10020104`	Tidak dapat memulai: batas waktu habis saat menunggu stream video (menggunakan nilai yang lebih besar antara `streamReadyTimeout` dan `noStreamAutoEndTimeoutSec` dari server)
`10020105`	Tidak dapat memulai: batas waktu habis saat menunggu video dapat diputar (dikontrol oleh `streamReadyTimeout`; default: 15 detik)
`10000001`–`10000012`	Kesalahan parameter, sumber daya, atau server Open Platform

`Travel.on("statusChanged")`

Berlangganan perubahan status sesi.

Signature

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

Parameter

Bidang	Tipe	Wajib	Deskripsi
`handler`	`(status: TravelStatus) => void`	Ya	Callback yang dipanggil saat status berubah.

Return

Mengembalikan fungsi berhenti berlangganan. TravelStatus adalah salah satu dari idle / prepare / running / paused / completed.

Error

Metode ini tidak melempar kesalahan bisnis.

`Travel.on("firstFrameGenerated")`

Berlangganan notifikasi URL frame pertama.

Signature

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

Parameter

Bidang	Tipe	Wajib	Deskripsi
`handler`	`(firstFrame: string) => void`	Ya	Callback yang dipanggil saat URL frame pertama tersedia.

Return

Mengembalikan fungsi unsubscribe.

Perilaku

Hanya dipancarkan selama travel.start(). Setelah SDK memanggil enter-travel Open Platform dan menerima firstFrame yang tidak kosong, SDK segera memancarkan event tersebut—biasanya setelah statusChanged("prepare") tetapi sebelum start() terselesaikan dan video dapat diputar. Event tidak dipancarkan jika respons tidak berisi URL frame pertama.

Error

Metode ini tidak melempar kesalahan bisnis.

`Travel.onError`

Berlangganan kesalahan runtime sesi.

Signature

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

Parameter

Bidang	Tipe	Wajib	Deskripsi
`handler`	`(error: unknown) => void`	Ya	Callback yang dipanggil saat terjadi kesalahan runtime.

Return

Mengembalikan fungsi unsubscribe. Gunakan isSdkError untuk mempersempit objek kesalahan menjadi SdkError.

Error

Metode ini tidak melempar kesalahan bisnis.

`Travel.sendCommand`

Mengirim perintah kontrol real-time.

Signature

sendCommand(params: AdventureCommand): Promise<void>

Parameter

`AdventureCommand`

Bidang	Tipe	Wajib	Deskripsi
`translation`	`string`	Tidak	Arah pergerakan. Defaultnya adalah `None` jika dihilangkan.
`rotation`	`string`	Tidak	Rotasi tampilan. Defaultnya adalah `None` jika dihilangkan.
`interaction`	`string`	Tidak	Tindakan interaksi. Defaultnya adalah `None` jika dihilangkan.

Referensi Perintah Kontrol

`translation` — Arah Pergerakan

Mendeskripsikan pergerakan karakter, mendukung delapan arah dan kombinasinya.

Nilai	Arah
`"Front"`	Maju
`"Back"`	Mundur
`"Left"`	Kiri
`"Right"`	Kanan
`"Front_Left"`	Maju-kiri
`"Front_Right"`	Maju-kanan
`"Back_Left"`	Mundur-kiri
`"Back_Right"`	Mundur-kanan
`"None"`	Diam

`rotation` — Rotasi Tampilan

Mensimulasikan rotasi tampilan berbasis mouse dalam delapan arah.

Nilai	Arah
`"Mouse_Up"`	Atas
`"Mouse_Down"`	Bawah
`"Mouse_Left"`	Kiri
`"Mouse_Right"`	Kanan
`"Mouse_Up_Left"`	Atas-kiri
`"Mouse_Up_Right"`	Atas-kanan
`"Mouse_Down_Left"`	Bawah-kiri
`"Mouse_Down_Right"`	Bawah-kanan
`"None"`	None

`interaction` — Aksi Interaksi

Nilai	Tindakan
`"Jump"`	Lompat
`"Attack"`	Serang
`"Crouch"`	Membungkuk
`"Sprint"`	Lari
`"None"`	None

Return

Mengembalikan Promise<void> yang terselesaikan setelah perintah dikirimkan.

Error

sendCommand() ditolak dalam kasus berikut:

ErrorCode	Deskripsi
`10010001`	`params` atau parameter pergerakan, rotasi, atau interaksi tidak valid
`10020501`	Status atau mode sesi saat ini tidak mengizinkan perintah, atau perintah stream video gagal

`Travel.sendInstruct`

Mengirim instruksi Directing atau konten prompt.

Signature

sendInstruct(params: InstructData): Promise<void>

Parameter

`InstructData`

Bidang	Tipe	Wajib	Deskripsi
`content`	`string`	Ya	Konten prompt yang akan dikirim.

Return

Mengembalikan Promise<void> yang terselesaikan setelah Open Platform menerima dan memproses instruksi.

Error

sendInstruct() ditolak dan memancarkan event error dalam kasus berikut:

ErrorCode	Deskripsi
`10020101`	Sesi belum dimulai
`10020601`	Gagal mengirim instruksi Directing
`10000001`–`10000012`	Kesalahan parameter, sumber daya, atau server Open Platform

`Travel.pause`

Menjeda sesi saat ini.

Signature

pause(): Promise<void>

Parameter

Tidak ada parameter.

Return

Mengembalikan Promise<void> yang terselesaikan setelah pemutaran video berhenti.

Error

pause() ditolak dalam kasus berikut:

ErrorCode	Deskripsi
`10020201`	Status saat ini, mode sesi, atau kapabilitas sesi tidak mengizinkan jeda, atau permintaan jeda gagal
`10020202`	Waktu habis saat menunggu backend melaporkan stream video sebagai dijeda (15 detik)
`10000001`–`10000012`	Kesalahan parameter, sumber daya, atau server Open Platform

`Travel.resume`

Melanjutkan sesi yang dijeda.

Signature

resume(): Promise<void>

Parameter

Tidak ada parameter.

Return

Mengembalikan Promise<void> yang terselesaikan setelah video dapat diputar kembali.

Error

resume() ditolak dalam kasus berikut:

ErrorCode	Deskripsi
`10020301`	Status saat ini, mode sesi, atau kapabilitas sesi tidak mengizinkan kelanjutan, atau permintaan lanjut gagal
`10020302`	Waktu habis saat menunggu video dapat diputar kembali (15 detik)
`10000001`–`10000012`	Kesalahan parameter, sumber daya, atau server Open Platform

`Travel.rewind`

Memutar mundur sesi saat ini ke waktu yang ditentukan.

Signature

rewind(params: RewindTravelParams): Promise<RewindTravelResult>

Parameter

`RewindTravelParams`

Bidang	Tipe	Wajib	Deskripsi
`rewindToSec`	`number`	Ya	Waktu target dalam detik. Hanya kelipatan 4 yang didukung (misalnya, `4`, `8`, atau `12`). Server membulatkan nilai lain ke bawah (misalnya, `7` menjadi `4`).

Return

Mengembalikan Promise<RewindTravelResult> yang terselesaikan setelah mundur selesai dan pemutaran dilanjutkan.

`RewindTravelResult`

Bidang	Tipe	Deskripsi
`resumedAtSec`	`number`	Waktu aktual dalam detik saat server melanjutkan pemutaran.

Error

rewind() ditolak dan memancarkan event error dalam kasus berikut:

ErrorCode	Deskripsi
`10020101`	Sesi belum dimulai
`10020401`	Tidak dapat mundur: sesi harus dijeda terlebih dahulu dan pemutaran video dihentikan, atau permintaan mundur maupun penyambungan ulang RTC gagal
`10020402`	Waktu habis saat menunggu video dilanjutkan setelah pemutaran mundur (15 detik)
`10000001`–`10000012`	Kesalahan parameter, sumber daya, atau server Open Platform

`Travel.end`

Mengakhiri sesi saat ini dan melepaskan sumber dayanya.

Signature

end(): Promise<void>

Parameter

Tidak ada parameter.

Return

Mengembalikan Promise<void> yang terselesaikan setelah pembersihan selesai.

Error

Kesalahan pembersihan tidak dilempar ke pemanggil; end() melakukan upaya terbaik untuk melepaskan sumber daya.

Penanganan Kesalahan

SDK mengekspos error runtime melalui penolakan Promise atau event error. Error merupakan objek SdkError; gunakan isSdkError(err) dan baca err.code serta err.message. Error Open Platform yang dikenali dipetakan ke rentang 10000001–10000012, dan err.message berisi pesan platform. Lihat bagian Errors pada setiap API Travel untuk kode spesifik metode.

Referensi ErrorCode

Rentang kode error:

100000xx: Kesalahan Open Platform yang dipetakan
1001xxxx: Error klien Engine
1002xxxx: Error klien Travel

code	name	Deskripsi
`10000001`	`OPEN_PLATFORM_PARAM_INVALID`	Parameter permintaan tidak valid (dikembalikan oleh Open Platform)
`10000002`	`OPEN_PLATFORM_RESOURCE_NOT_FOUND`	Sumber daya tidak ditemukan (Travel hilang, bukan milik sendiri, berada di workspace lain, atau artefak belum siap)
`10000003`	`OPEN_PLATFORM_WORLD_NOT_OWNED`	World tidak ada, telah dihapus, atau bukan milik pengembang saat ini
`10000004`	`OPEN_PLATFORM_SYSTEM_ERROR`	Error sistem
`10000005`	`OPEN_PLATFORM_TICKET_INVALID`	Ticket tidak valid atau kedaluwarsa
`10000006`	`OPEN_PLATFORM_TICKET_USED`	Tiket telah digunakan (kredensial sekali pakai)
`10000007`	`OPEN_PLATFORM_WORLD_NOT_READY`	World belum siap dan tidak dapat dimasuki
`10000008`	`OPEN_PLATFORM_INFERENCE_ALLOCATE_FAILED`	Alokasi sumber daya inferensi gagal (kapasitas tidak mencukupi, kegagalan pembuatan stream, kegagalan inisialisasi sesi, dll.)
`10000009`	`OPEN_PLATFORM_MAIN_API_KEY_REQUIRED`	API ini hanya menerima API Key utama (API Key sementara tidak didukung)
`10000010`	`OPEN_PLATFORM_CONTENT_MODERATION`	Input ditolak oleh moderasi konten
`10000011`	`OPEN_PLATFORM_CONTENT_COPYRIGHT`	Gambar input melanggar kebijakan hak cipta atau KI
`10000012`	`OPEN_PLATFORM_STATE_CONFLICT`	Permintaan bertentangan dengan status sumber daya saat ini
`10010001`	`INVALID_ARGUMENT`	Validasi argumen klien SDK gagal (tidak dipetakan dari Open Platform)
`10010002`	`SDK_FEATURE_DISABLED`	Fitur SDK dinonaktifkan
`10010101`	`ACTIVE_TRAVEL_EXISTS`	Travel sudah aktif
`10020001`	`STREAM_DISCONNECTED_WHILE_PLAYING`	Stream video terputus selama pemutaran
`10020101`	`START_REQUEST_FAILED`	Permintaan mulai sesi gagal
`10020102`	`START_RTC_CONFIG_MISSING`	Konfigurasi stream video hilang saat startup
`10020103`	`START_JOIN_CHANNEL_FAILED`	Koneksi stream video gagal
`10020104`	`START_REMOTE_USER_TIMEOUT`	Waktu habis saat menunggu stream video
`10020105`	`START_STREAM_TIMEOUT`	Waktu habis saat menunggu video dapat diputar
`10020201`	`PAUSE_REQUEST_FAILED`	Permintaan jeda gagal
`10020202`	`PAUSE_STREAM_TIMEOUT`	Waktu habis saat menunggu video dijeda
`10020301`	`RESUME_REQUEST_FAILED`	Permintaan lanjut gagal
`10020302`	`RESUME_STREAM_TIMEOUT`	Waktu habis saat menunggu video dilanjutkan
`10020401`	`REWIND_REQUEST_FAILED`	Permintaan mundur cepat gagal
`10020402`	`REWIND_STREAM_TIMEOUT`	Waktu habis saat menunggu video dilanjutkan setelah pemutaran mundur
`10020501`	`SEND_COMMAND_FAILED`	Gagal mengirim perintah kontrol real-time
`10020601`	`INSTRUCT_REQUEST_FAILED`	Gagal mengirim instruksi Directing
`10020701`	`END_REQUEST_FAILED`	Permintaan akhir sesi gagal

Ekspor Lainnya

Ekspor runtime

Ekspor	Tipe	Deskripsi
`HappyOysterEngine`	`class`	Klien SDK yang mengonfigurasi Open Platform, memperbarui token, dan membuat sesi Travel.
`HappyOysterEngine.version`	`string`	Versi SDK saat ini.
`HappyOysterEngine.metadata`	`SDKMetadata`	Nama paket SDK, versi, dan saluran paket saat ini.
`ErrorCode`	`const`	Objek konstanta kode kesalahan yang diekspor oleh SDK.
`isSdkError`	`function`	Memeriksa apakah kesalahan yang tidak diketahui merupakan kesalahan SDK standar.

`ErrorCode`

Objek konstanta kode error yang diekspor oleh SDK. Bandingkan dengan SdkError.code alih-alih menyebarkan literal numerik di seluruh kode aplikasi.

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

`isSdkError`

Memeriksa apakah error yang tidak dikenal merupakan error SDK standar. Ketika mengembalikan true, TypeScript mempersempit error menjadi SdkError, sehingga memungkinkan akses aman ke code dan 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.
  }
}

Tipe Publik

Tipe berikut diekspor dari titik masuk paket dan dapat diimpor langsung dari @happy-oyster/js-sdk. Tipe ini hanya ada pada waktu kompilasi TypeScript dan tidak menghasilkan kode runtime.

Tipe	Deskripsi
`SDKConfig`	Tipe parameter konstruktor `HappyOysterEngine`.
`LogLevel`	Level log SDK: `verbose` / `debug` / `info` / `warn` / `error` / `none`.
`SDKMetadata`	Metadata paket SDK: `version`, `packageName`, `packageChannel`.
`SDKPackageChannel`	Saluran paket SDK: `internal` / `public` / `unknown`.
`CreateTravelConfig`	Tipe parameter `createTravel(config)`.
`StartTravelResult`	Metadata sesi `start()` dikembalikan saat Promise terselesaikan.
`TravelInfo`	Metadata sesi yang digunakan oleh `travelInfoReady`, `getInfo()`, dan `StartTravelResult`.
`TravelAspectRatio`	Rasio aspek Acting: `"9:16"` / `"16:9"`.
`Travel`	Kontrak sesi publik `createTravel()` yang dikembalikan oleh metode.
`TravelStatus`	Status sesi SDK lokal: `idle` / `prepare` / `running` / `paused` / `completed`.
`TravelAction`	Nama tindakan yang didukung `can(action)`.
`AdventureCommand`	Tipe parameter `sendCommand(params)`.
`InstructData`	Tipe parameter `sendInstruct(params)`.
`RewindTravelParams`	Tipe parameter `rewind(params)`.
`RewindTravelResult`	Data `rewind(params)` dikembalikan saat Promise terselesaikan.
`SDKError`	Bentuk kesalahan SDK yang berisi `code` dan `message`.
`SdkError`	Tipe kesalahan yang menggabungkan `Error` runtime dan `SDKError`.
`ErrorCodeValue`	Union dari semua nilai kode kesalahan dalam objek `ErrorCode`.

​Terminologi Inti

​Ikhtisar

​HappyOysterEngine

​Travel

​Ekspor Lainnya

​Contoh

​HappyOysterEngine

​new HappyOysterEngine

​Signature

​Parameter

​SDKConfig

​Return

​Error

​HappyOysterEngine.updateToken

​Signature

​Parameter

​Return

​Error

​HappyOysterEngine.createTravel

​Signature

​Parameter

​CreateTravelConfig

​Return

​Error

​Travel

​Metode

​Status

​Event

​Travel.can

​Signature

​Parameter

​Return

​Ketersediaan

​Error

​Travel.start

​Signature

​Parameter

​Return

​StartTravelResult

​Error

​Travel.on("statusChanged")

​Signature

​Parameter

​Return

​Error

​Travel.on("firstFrameGenerated")

​Signature

​Parameter

​Return

​Perilaku

​Error

​Travel.onError

​Signature

​Parameter

​Return

​Error

​Travel.sendCommand

​Signature

​Parameter

​AdventureCommand

​Referensi Perintah Kontrol

translation — Arah Pergerakan

rotation — Rotasi Tampilan

interaction — Aksi Interaksi

​Return

​Error

​Travel.sendInstruct

​Signature

​Parameter

​InstructData

​Return

​Error

​Travel.pause

​Signature

​Parameter

​Return

​Error

​Travel.resume

​Signature

​Parameter

Terminologi Inti

Ikhtisar

HappyOysterEngine

Travel

Ekspor Lainnya

Contoh

`HappyOysterEngine`

`new HappyOysterEngine`

Signature

Parameter

`SDKConfig`

Return

Error

`HappyOysterEngine.updateToken`

Signature

Parameter

Return

Error

`HappyOysterEngine.createTravel`

Signature

Parameter

`CreateTravelConfig`

Return

Error

`Travel`

Metode

Status

Event

`Travel.can`

Signature

Parameter

Return

Ketersediaan

Error

`Travel.start`

Signature

Parameter

Return

`StartTravelResult`

Error

`Travel.on("statusChanged")`

Signature

Parameter

Return

Error

`Travel.on("firstFrameGenerated")`

Signature

Parameter

Return

Perilaku

Error

`Travel.onError`

Signature

Parameter

Return

Error

`Travel.sendCommand`

Signature

Parameter

`AdventureCommand`

Referensi Perintah Kontrol

`translation` — Arah Pergerakan

`rotation` — Rotasi Tampilan

`interaction` — Aksi Interaksi

Return

Error

`Travel.sendInstruct`

Signature

Parameter

`InstructData`

Return

Error

`Travel.pause`

Signature

Parameter

Return

Error

`Travel.resume`

Signature

Parameter