Titik masuk SDK iOS HappyOyster adalah singleton tingkat proses HappyOysterEngine.shared. Metode bisnis semuanya bersifat async throws, melempar OysterSDKError saat gagal. Satu pengalaman dibawa oleh handle OysterTravel, yang mencakup tiga mode — adventure, directing, dan acting — pada UIKit maupun SwiftUI.
- Dokumen ini adalah deskripsi fitur eksternal + referensi antarmuka untuk Happy Oyster iOS SDK: dokumen ini menjelaskan parameter, waktu, penggunaan, dan contoh singkat dari setiap tipe dan metode publik, satu per satu.
- Untuk alur integrasi lengkap (pengaturan proyek, konfigurasi dependensi, koordinasi sisi server, pelaksanaan end-to-end), lihat dokumentasi proyek sampel; tidak diulang di sini.
1. Konsep Inti
Beberapa istilah terlebih dahulu, agar sisanya lebih mudah dibaca.
Konsep | Deskripsi |
|---|---|
token | Token autentikasi HTTP (API Key sementara Bailian). Server Anda menukarnya melalui API Bailian dan mengirimkannya ke bawah; diinjeksikan melalui |
ticket | Kredensial uji coba sekali pakai. Server Anda menukarnya melalui platform terbuka |
World | World AI, berisi karakter dan adegan. Dibuat dan dikelola oleh server Anda; SDK tidak terlibat. |
Travel | Pengalaman real-time tunggal, sesuai dengan satu handle |
Status sesi |
|
Mode |
|
2. Ikhtisar
Setelah mengintegrasikan SDK ini, aplikasi Anda dapat memasuki "world" yang dihasilkan secara real-time oleh AI, dan memiliki pengalaman video interaktif real-time dalam tiga mode — adventure, directing, atau acting: mulai pengalaman → pemutaran real-time → interaksi real-time → kontrol proses (pause/resume/rewind/end) → callback status dan error.
Setiap mode mendukung serangkaian kapabilitas yang berbeda. Gerakkan UI Anda dari mode yang dikembalikan oleh start():
Kapabilitas |
|
|
|
|---|---|---|---|
| Ya | Tidak | Tidak |
| Tidak | Ya | Ya |
| Tidak | Ya | Ya |
| Tidak | Ya | Tidak — sembunyikan titik masuk |
| Ya | Ya | Ya |
| Diterapkan | Diabaikan | Diabaikan |
acting mengutamakan potret: start() mengembalikan aspectRatio (9:16 / 16:9) untuk sesi tersebut. Gunakan ini untuk memilih orientasi pemutar dan ukuran kontainer sebelum menarik aliran (lihat §8).import HappyOysterSDK; titik masuk intinya terdiri dari dua tipe.
HappyOysterEngine — titik masuk orkestrasi, singleton tingkat proses HappyOysterEngine.shared.
Method / Property | Deskripsi |
|---|---|
| Inisialisasi runtime dan daftarkan mesin real-time secara otomatis (sekali, sebelum |
| Injeksikan / perbarui token autentikasi HTTP |
| Buat handle sesi dengan kredensial sekali pakai |
| Lepaskan sumber daya (dapat |
| Versi SDK saat ini |
OysterTravel — handle sesi untuk satu pengalaman, dibuat oleh createTravel(ticket:).
Method / Property | Deskripsi |
|---|---|
| Tampilan pemutaran (UIKit / SwiftUI) |
| Aliran push perubahan status + error / status saat ini yang dapat diobservasi |
| Hubungkan dan mainkan (opsional meminta durasi maksimum pengalaman adventure) |
| Instruksi teks mode Directing |
| Kontrol mode Adventure |
| Jeda / lanjutkan ( |
| Putar mundur (hanya saat dijeda) |
| Akhiri (idempoten, pastikan untuk memanggilnya) |
| Lepaskan / pulihkan mikrofon sementara |
OysterLog untuk mengambil alih pencatatan internal SDK; HappyOysterEngine.version untuk membaca versi; OysterVideoView adalah tampilan pemutaran SwiftUI (setara dengan videoView). Penggunaan dijelaskan selanjutnya.
Siklus hidup: inisialisasi → injeksi token → buat sesi → mount video + berlangganan event → mulai pemutaran → interaksi → akhiri. SDK tidak bertanggung jawab untuk membuat atau mengelola world (dilakukan oleh server Anda), dan tidak mengekspos detail komunikasi real-time tingkat rendah.
3. Quick Start
Alur lengkap dari inisialisasi hingga pengakhiran, dengan komentar langkah demi langkah. Detail setiap API ada di §6.
4. Persyaratan
Item | Requirement |
|---|---|
OS Minimum | iOS 15.0+ (semua tipe publik ditandai dengan |
Language | Swift ( |
Konkurensi | Akses main-thread (tipe entri ditandai dengan |
Network | Akses jaringan publik diperlukan |
Izin |
|
Info.plist harus menyediakan NSMicrophoneUsageDescription, jika tidak, memulai penangkapan real-time akan crash. Saat Anda memerlukan akses mikrofon eksklusif (misalnya pengenalan suara), gunakan pauseLocalAudioCapture() / resumeLocalAudioCapture() untuk melepaskannya dan memulihkannya sementara waktu (lihat §6.2).
5. Integrasi dan Autentikasi
5.1 Integrasi dan Dependensi
import HappyOysterSDK adalah semua yang Anda butuhkan di tingkat kode. SDK didistribusikan sebagai biner yang telah dikompilasi sebelumnya (xcframework) melalui subspecs CocoaPods, dipublikasikan ke CocoaPods Trunk publik — deklarasikan dependensi di Podfile Anda:
AliVCSDK_ARTC diperlukan setiap kali Anda menarik HappyOysterSDK/StreamAliRTC: jika tidak ada, SDK secara diam-diam kembali ke Loopback — SDK dapat terhubung dan mencapai running, tetapi menampilkan layar hitam tanpa error.5.2 Model Autentikasi
SDK tidak memperoleh atau menyegarkan token, menjaga agar tetap ringan. Autentikasi memiliki dua lapisan, dan integrator mengelola siklus hidupnya:
- Token autentikasi HTTP (API Key sementara Bailian): Server Anda menukarnya melalui API Bailian dan mengirimkannya ke bawah; diinjeksikan melalui
updateToken(_:). Beberapa layanan internal SDK memanggil gateway Bailian secara langsung, membawa token ini untuk autentikasi — oleh karena itu harus berupa API Key sementara yang dikeluarkan oleh Bailian, bukan token dari layanan bisnis Anda sendiri. SDK hanya menyimpan yang terbaru, tidak menyimpan atau menyegarkannya; setelah kedaluwarsa, Anda menukar dan menginjeksikannya kembali. - Kredensial uji coba sekali pakai
ticket: Server Anda menukarnya melalui platform terbukaget-travel-credential(prefikstk_, berlaku selama 30 menit, sekali pakai), digunakan sebagai argumencreateTravel(ticket:); menjadi tidak valid setelah pengalaman berakhir (secara normal atau tidak normal) atau kedaluwarsa, dan tidak dapat digunakan kembali.
start / pause / resume / rewind / sendInstruct / sendCommand) ditolak dengan 108001 dan pengalaman yang sedang berjalan dihentikan oleh SDK (lihat §9). OysterSDKError.raw membawa alasan yang dapat dibaca manusia; minta pengguna untuk melakukan upgrade saat versinya terlalu rendah.updateToken(_:). Ada dua tempat di mana Anda perlu menentukan apakah token telah kedaluwarsa:
- Saat memanggil API seperti
engine.createTravelatautravel.start, tangani error dan periksa tipe error token kedaluwarsa/tidak valid (101001/101002); setelah menyuntikkan token baru, panggil ulang API yang sesuai. - Saat mendengarkan event
.errordariOysterTravelEvent, periksa tipe error token kedaluwarsa/tidak valid, minta ulang token, dan suntikkan.
6. Referensi API
Ada dua tipe entri, keduanya @MainActor dan @available(iOS 15.0, *). Metode bisnis bersifat async throws dan melempar OysterSDKError saat gagal; metode dengan nilai kembalian semuanya ditandai dengan @discardableResult.
6.1 HappyOysterEngine
Singleton tingkat proses, titik masuk orkestrasi. init tidak bersifat publik — selalu gunakan HappyOysterEngine.shared; jangan menginstansiasinya sendiri (mesin real-time yang mendasarinya juga merupakan singleton proses).
initialize(config:)
- Tujuan: Menginisialisasi runtime dan mendaftarkan mesin real-time secara otomatis (tidak perlu pendaftaran manual oleh host).
- Parameter:
config.apiHostadalah URL gateway Bailian, bukan server bisnis Anda, dan wajib diisi; di lingkungan pra-rilis/ujicoba, Anda harus secara eksplisit meneruskan gateway yang sesuai, jika tidak, permintaan akan gagal (misalnya106001, domain tidak dapat diselesaikan).config.modeladalah nama model berversi yang diaktifkan untuk akun Anda dan juga wajib diisi tanpa nilai default — Happy Oyster dibagi menjadi sub-model per-mode, sehingga SDK tidak dapat menyimpulkan mana yang harus digunakan. Keduanya harus termasuk dalam akun dan wilayah yang sama dengan token yang diinjeksi. Bidang lainnya ada di §8OysterConfig. - Satu model melayani satu
mode: setiap model per-mode memiliki rute gateway-nya sendiri, sehingga satuinitializehanya melayani dunia dengan satumodetersebut. Jika aplikasi Anda menawarkan dunia dalam beberapa mode, cukup panggilinitialize()lagi dengan model yang sesuai sebelum memasuki dunia dengan mode yang berbeda — saat idle, konfigurasi terbaru yang akan digunakan, tidak perlucleanup()dan token yang diinjeksi tetap dipertahankan; saat Travel sedang berlangsung, panggilan akan diabaikan, jadiend()terlebih dahulu. Model yang tidak sesuai denganmodedunia akan ditolak oleh gateway denganAccessDenied, dinormalisasi menjadi106003. - Kapan digunakan: Panggil sekali sebelum
createTravel, sedini mungkin setelah peluncuran aplikasi. - Mengembalikan:
Bool— apakahconfigyang Anda berikan berlaku. Bernilaifalsedalam dua kasus: konfigurasi tidak valid (apiHost/modelkosong atau tidak membentuk URL gateway yang valid), atau Travel sedang berjalan sehingga panggilan diabaikan. Dalam kedua kasus tersebut, runtime dibiarkan tidak berubah. - Catatan: Saat idle, memanggilnya kembali akan mengonfigurasi ulang runtime dengan konfigurasi baru (mengubah
apiHost/modeltidak memerlukancleanup(), dan token yang diinjeksi tetap dipertahankan); ini menjadi no-op dengan peringatan hanya saat Travel sedang berlangsung, jadiend()terlebih dahulu. Konfigurasi yang tidak valid membiarkan runtime tidak berubah. Jangan gunakanisReadyuntuk mengetahui apakah re-initializeberhasil — jika ditolak, konfigurasi sebelumnya masih berlaku danisReadytetaptrue;isReadymenjawab "apakah engine dapat digunakan sekarang", nilai pengembalian menjawab "apakah konfigurasi yang baru saja saya berikan telah berlaku".
OysterLog
- Tujuan: Mengonfigurasi dan mengambil alih pencatatan internal SDK, mencetaknya ke dalam modul pencatatan Anda sendiri. Menyediakan
setMinimumLevel(_:)untuk mengatur level dansetHandler(_:)untuk output kustom (lihat contoh §3).
updateToken(_:)
- Tujuan: Menyuntikkan / memperbarui token autentikasi HTTP (API Key sementara Bailian, §5.2).
- Kapan digunakan: Setelah
initialize, dapat dipanggil kapan saja; tukar ulang dan panggil lagi setelah token kedaluwarsa atau setelah menerima error terkait autentikasi (101001/101002). - Catatan: Tidak ada operasi dan menampilkan peringatan jika belum di-
initialize.
createTravel(ticket:)
- Tujuan: Membuat handle sesi tunggal dengan
ticketsekali pakai. - Parameter:
ticketadalah kredensial sekali pakai; setelah dibuat, dianggap terpakai untuk pengalaman ini. - Kapan digunakan: Panggil sebelum setiap pengalaman baru; handle yang dikembalikan belum terhubung dan Anda harus memanggil
travel.start()setelahnya. Video diambil dari handle yang dikembalikan (lihat §6.2). - Catatan (
throwssinkron): melempar100001jika belum di-initialize; melempar103004jika dipanggil lagi sebelum Travel sebelumnya di-end()(setiap mesin hanya mengizinkan satu Travel aktif pada satu waktu).
cleanup()
- Tujuan: Melepaskan sumber daya SDK (mengakhiri travel aktif, konfigurasi runtime, token).
- Kapan digunakan: Saat keluar sepenuhnya dari SDK atau perlu mengubah
config. - Catatan:
async— secara internal ia secara deterministik mengakhiri travel aktif saat ini denganend()terlebih dahulu, kemudian meruntuhkan runtime, tanpa meninggalkan fire-and-forget. Setelah dilepaskan, Anda dapat melakukaninitializelagi.
6.2 OysterTravel
Handle sesi yang dibuat oleh createTravel; sekali pakai, menjadi tidak valid setelah status terminal (end / akhir sisi server / kegagalan) tercapai, memerlukan createTravel baru melalui engine. Ini juga merupakan ObservableObject (@Published status, dapat langsung menggerakkan SwiftUI).
videoView / OysterVideoView(travel:)
- Tujuan: Entri rendering untuk gambar jarak jauh — "SDK menyediakan tampilan, host menempatkannya". Untuk UIKit, ambil
travel.videoView; untuk SwiftUI, gunakanOysterVideoView(travel:). - Kapan digunakan: Tersedia segera setelah handle dibuat (akses berulang mengembalikan tampilan yang sama); mount ke dalam hierarki apa pun, dan setelah engine siap, tampilan akan dirender secara otomatis. Mount sebelum atau setelah
start()keduanya berfungsi, tanpa layar hitam. - Catatan: Saat sesi berakhir, SDK secara otomatis melepaskan binding rendering; hapus tampilan dari hierarki sesuai kebutuhan.
events / status / isEnded
- Tujuan:
eventsadalah aliran push perubahan status + error;statusadalah status eksternal saat ini yang dapat diobservasi;isEndedadalah flag yang dapat dibaca secara sinkron untuk status terminal. - Kapan digunakan: Disarankan untuk mulai mengonsumsi
eventssebelumstart(), untuk menghindari terlewatnya status awal. - Catatan: Setiap akses ke
eventsmengembalikan stream independen, mendukung multi-subscription; berhenti berlangganan = mengakhiri iterasifor await(atau menghancurkanTaskyang ditahan). Di SwiftUI Anda dapat mengamatistatussecara langsung dengan@StateObject/@ObservedObject(error tetap masuk melaluievents). Lihat §7.
start() / start(maxExperienceTimeSec:)
- Tujuan: Gunakan
ticketyang diambil pada saat pembuatan untuk ditukar dengan konfigurasi travel + join RTC dan terhubung untuk bermain. Jika berhasil, SDK secara otomatis membuat koneksi real-time dan memulai polling status internal, memunculkan status melaluievents. - Parameter:
maxExperienceTimeSec(opsional) — meminta durasi maksimum (dalam detik) untuk pengalaman petualangan ini. Nilai dikirim ke server apa adanya; nilai yang diizinkan, durasi efektif aktual, dan waktu berakhir otomatis semuanya ditentukan oleh server — SDK tidak melakukan validasi lokal. Meneruskannil(atau memanggilstart()tanpa parameter) menggunakan durasi default server. Mode Directing mengabaikan parameter ini. Ketika waktu habis, server mengakhiri pengalaman dan host menerima status terminalendedmelaluievents(sama seperti akhir sisi server, lihat §7). - Mengembalikan:
OysterStartTravelData(mode/version/encryptedTravelId, dll., lihat §8), yang menentukan UI interaksi. - Error:
401010/401011(kredensial tidak valid/terpakai),403002(world belum siap),403007(spesifikasi layanan tidak diaktifkan, misal acting),429001/429002(batas konkurensi / kapasitas habis),500001(kegagalan resource/server),103004(start konkuren). modeduniaticketharus cocok denganmodelyang diteruskan keinitialize(tanggung jawab pemanggil): dengan model per-mode, setiap model memiliki rute gateway-nya sendiri, danstart()mengirimticketke rute model yang saat ini diinisialisasi. SDK tidak dan tidak dapat memverifikasi ini untuk Anda sebelumnya —modedikirimkan oleh respons dari panggilanstart()ini sendiri (OysterStartTravelData.mode); sebelum panggilan, SDK hanya menyimpanticketyang buram dan nama model, tanpa mode untuk dibandingkan, dan menyimpulkan mode dari nama model berarti menebak skema penamaan milik server, yang tidak dilakukan oleh SDK. Jadi: sebelum memasuki dunia dengan mode yang berbeda, panggilinitialize()lagi dengan model yang sesuai (saat idle, konfigurasi terbaru yang digunakan — tidak perlucleanup()dan token dipertahankan; saat Travel sedang berlangsung, panggilan diabaikan, jadiend()terlebih dahulu). Jika tidak cocok,start()ini akan gagal di gateway; saat mendiagnosis, pertama-tama periksa apakahmodelsaat ini danmodedari duniaticketsaling terkait, lalu lihat kode kesalahan kredensial di atas.- Catatan (auto-end saat tidak ada stream): Server mengirimkan "no-stream timeout" (default ~30s). Jika, setelah terhubung, tidak ada stream yang diterima dalam durasi tersebut (tidak pernah mencapai
running), SDK secara otomatis mengakhiri pengalaman, beralih kefailed, dan memunculkan105006melalui.errordarievents(fatal; tangani dengan kembali ke layar pra-start, tidak perlu menghitung waktunya sendiri).
pause() / resume()
- Tujuan: Menjeda / melanjutkan pengalaman (idempoten).
- Kapan digunakan: Didukung oleh world
directingdanacting; tidak didukung olehadventure. Gunakanmodeyang dikembalikan olehstart()untuk memutuskan terlebih dahulu apakah akan menampilkan tombol pause.pausemengharuskan status saat ini beruparunning;resumemengharuskanpaused. - Error:
103001(tidak ada pengalaman aktif),103002(status/versi tidak diizinkan),103003(ketidakcocokan mode).
rewind(toSec:)
- Tujuan: Memutar mundur ke detik yang ditentukan. Jika berhasil, SDK secara otomatis bergabung kembali dengan rtcConfig asli dan kembali ke pemutaran.
- Kapan digunakan: Hanya dapat dimulai dalam status
paused, dan hanya oleh worlddirecting—actingdanadventuretidak mendukung putar mundur, jadi sembunyikan titik masuk putar mundur dalam mode tersebut dan jangan memanggilnya. - Error:
103001,103002.
end()
- Tujuan: Mengakhiri pengalaman (idempoten, dapat dipanggil berulang kali). Setelah panggilan berhasil atau keluar secara tidak normal, SDK secara otomatis memutuskan koneksi real-time, menghentikan polling, dan melepaskan semua resource sesi;
ticketmenjadi tidak valid pada saat yang sama, dan handle memasuki status terminal. - Kapan digunakan / Catatan: Baik pengguna keluar secara aktif maupun pengalaman berakhir secara pasif (kedaluwarsa timer, menerima
.ended/.failed, penghancuran halaman), pastikan satuend()tercapai, jika tidak, resource jarak jauh mungkin tidak dilepaskan tepat waktu. Disarankan untuk menyalurkan semua jalur keluar ke metode pembersihan idempoten yang sama.
sendInstruct(content:) (mode directing)
- Tujuan: Mengirim instruksi teks untuk menggerakkan alur cerita.
- Kapan digunakan: Mode directing; dikirim langsung saat
running, di-cache saatpauseddan dikirim ulang dengan frame pertama setelah dilanjutkan kembali kerunningmelalui reconnect. - Error:
103001,103002,103003(dipanggil dalam mode adventure),403004(moderasi konten),404000(travel tidak ditemukan).
sendCommand(_:) / flushCommands() (mode adventure)
sendCommand: Kirim perintah kontrol direction/view/action (lihat §8OysterAdventureCommand; fire-and-forget, tidak ada pengembalian, tidak melempar error). Efektif hanya dalam mode adventure saatrunning. Input eksternal dapat berfrekuensi tinggi setiap frame, dan SDK melakukan throttle secara internal (sampling latest-wins, penggabungan frame pada line rate RTC); host tidak perlu melakukan throttle sendiri. Perhatikan bahwa respons server terhadap perintah itu sendiri memiliki latensi, sehingga waktu efektif sebenarnya tidak tetap.flushCommands: Dipanggil pada saat "pelepasan tombol / pelepasan input", segera mengirim ulang perintah terakhir yang sudah menunggu dalam antrean; murni tidak melakukan apa pun ketika tidak ada perintah yang tertunda, tidak menghasilkan perintah baru.- Error (semua dimunculkan melalui
.errordarievents, bukanthrows): tidak ada pengalaman aktif103001; dipanggil dalam mode directing103003; saluran real-time belum siap / gagal mengirim105004.
pauseLocalAudioCapture() / resumeLocalAudioCapture()
- Tujuan: Melepaskan / memulihkan sementara pendudukan SDK pada penangkapan mikrofon lokal.
- Kapan digunakan: Ketika sesuatu seperti pengenalan suara memerlukan akses mikrofon eksklusif,
pauseterlebih dahulu danresumesetelahnya.
7. Event dan Status
Event dilampirkan pada OysterTravel.events dan merupakan saluran push aktif SDK kepada Anda, digunakan untuk memunculkan situasi yang tidak dipicu oleh panggilan Anda sendiri (misalnya masalah dengan koneksi real-time yang dikelola secara internal atau polling status).
- SwiftUI:
OysterTraveladalahObservableObject; gunakan@StateObject/@ObservedObjectsecara langsung untuk mengobservasistatusdan menggerakkan UI; error tetap berasal darievents. - Imperatif / UIKit: dalam
Task,for await event in travel.events { ... }, danswitchatas.statusChanged/.error; batalkanTaskyang ditahan setelah selesai.
OysterTravelStatus (5 status proses + 2 status terminal):
Status | Deskripsi | Penanganan umum |
|---|---|---|
| setelah create, sebelum start | — |
| menghubungkan / menghubungkan ulang (menghubungkan / menghubungkan ulang internal) | tampilkan petunjuk koneksi / koneksi ulang |
| stream siap, interaktif (pemutaran internal) | tampilkan gambar dan kontrol |
| jeda diterima, menunggu konfirmasi server | tampilkan "pausing…" |
| dijeda (dikonfirmasi) | tampilkan status dijeda (hanya |
| berakhir (diakhiri aktif atau diakhiri sisi server). Terminal | akhiri dan tutup halaman |
| gagal. Terminal | tampilkan kesalahan dan akhiri |
ended / failed, sesi telah berakhir, dan semua operasi sesi (pause/resume/sendCommand…) tidak lagi berlaku. Callback dapat dipicu pada main thread, sehingga Anda dapat memperbarui UI secara langsung.8. Model Data
@available(iOS 15.0, *). Nilai/parameter pengembalian di bawah ini adalah output SDK, dibangun di tempat secara internal dengan tipe Swift native (Date / TimeInterval / OysterTravelStatus); semuanya bukan Codable dan tidak mengekspos detail wire (snake_case) — decoding wire terjadi di dalam SDK.- Catatan: rawValues perintah menggunakan lower camelCase (misalnya
front/mouseLeft/jump); nilai enum di atas adalah yang otoritatif. - Catatan:
modesecara eksternal adalahadventure(wander) /directing(cerita) /acting(bermain peran); definisiOysterModeValueadalah yang otoritatif. - Catatan:
aspectRatioadalah string terbuka (saat ini9:16/16:9, lebih banyak mungkin ditambahkan). Uraikan sebagaiwidth:heightdan bandingkan rasionya alih-alih mencocokkan nilai yang diketahui.
9. Kode Error
SDK melaporkan error secara seragam sebagai OysterSDKError, dan tipenya selalu dibedakan oleh code — jangan menilai tipe dari "jalur mana error berasal": code yang sama dapat dilempar oleh metode bisnis (async throws) atau dimunculkan melalui .error dari events. Untuk pencocokan bertipe, gunakan error.kind (lihat §8 OysterErrorKind).
Kode error: server 4xxxxx/5xxxxx, client-local 1xxxxx.
Kode Error Server (umum)
code | Arti | Penanganan yang disarankan |
|---|---|---|
| Parameter tidak valid (nilai enum tidak valid, dll.) | Periksa parameter permintaan atau versi SDK |
| Kredensial pengalaman ( | Minta server menerbitkan ulang kredensial |
| Kredensial pengalaman ( | Kredensial sekali pakai; terbitkan ulang |
| World tidak ada, telah dihapus, atau bukan milik pengembang saat ini (termasuk world yang dihapus setelah kredensial diterbitkan) | Pilih World yang valid lagi |
| Status World belum siap | Tunggu hingga world siap sebelum memulai |
| API hanya mengizinkan API Key utama | Key sementara tidak dapat digunakan untuk API ini |
| Konten input ditolak oleh moderasi konten; berlaku untuk instruksi teks | Ubah input dan coba lagi |
| Spesifikasi layanan yang diminta tidak diaktifkan | Jangan mencoba lagi seolah-olah kapasitas penuh; beralih ke spesifikasi yang diaktifkan (biasanya: akun tidak memiliki spesifikasi acting) |
| Konfigurasi kapasitas sementara tidak tersedia | Coba lagi nanti |
| Sumber daya tidak ada (kepemilikan world/wander atau tidak ada artefak) | Verifikasi ID / status |
| Permintaan bertentangan dengan status sumber daya saat ini | Periksa status experience |
| Batas konkurensi tercapai untuk spesifikasi ini | Coba lagi setelah sesi yang ada berakhir (jangan bingung dengan |
| Kapasitas tersedia tidak mencukupi | Coba lagi nanti |
| Kesalahan sistem internal | Coba lagi nanti / laporkan |
| Alokasi sumber daya inferensi atau kegagalan layanan internal | Coba lagi nanti |
Kode Error Client-Local
code | Arti | SDK mengakhiri sesi secara otomatis | Penanganan yang disarankan |
|---|---|---|---|
| Dipanggil sebelum inisialisasi SDK; juga mencakup | Tidak (dilontarkan secara sinkron, menolak panggilan ini) |
|
| Token autentikasi HTTP tidak diinjeksikan | Tidak | coba lagi setelah |
| Token autentikasi HTTP tidak valid / ditolak | Tidak | tukar ulang token lalu coba lagi |
| Tidak ada experience aktif saat ini | Tidak (menolak panggilan ini) |
|
| Status/versi saat ini tidak mengizinkan operasi ini | Tidak (menolak panggilan ini) | periksa status experience / |
| Ketidakcocokan mode (misalnya | Tidak (menolak panggilan ini) | pilih API yang tepat berdasarkan |
| Create/start experience secara konkuren | Tidak (dilontarkan secara sinkron) | serialisasikan panggilan, |
| Koneksi real-time gagal | Ya | akhiri dan mulai ulang |
| Batas waktu bergabung real-time | Ya | akhiri dan mulai ulang |
| Batas waktu menunggu frame video pertama | Ya | akhiri dan mulai ulang |
| Channel real-time belum siap / pengiriman gagal | tergantung (kegagalan pengiriman aktif; heartbeat hanya untuk pelaporan) | kirim setelah |
| Batas waktu callback (default 30s) | Tidak | coba lagi, dan tingkatkan |
| Tidak ada stream setelah bergabung; SDK mengakhiri experience secara otomatis | Ya | akhiri dan mulai ulang |
| Kesalahan jaringan lokal | Tidak | dapat dicoba ulang |
| Gagal mengurai respons | tergantung | tingkatkan versi SDK / laporkan |
| Tidak ada kode error yang dapat dikenali / kode error string proxy | Tidak | dapat dicoba ulang |
| Dinonaktifkan dari jarak jauh oleh sakelar fitur server (penonaktifan penuh atau versi terlalu rendah; alasan di | Ya | Ikuti alasan di |
OysterSDKError tidak memiliki isFatal). Secara semantik, "fatal" secara khusus berarti apakah SDK secara aktif mengakhiri sesi (memutuskan RTC, melepaskan seluruh sesi) —
- Error yang mengakhiri sesi secara otomatis (misalnya
105001/105002/105003/105006/108001): host menyadari hal ini dari status terminal state-machine (status → failed, dimunculkan melalui.statusChangeddarievents), dan kembali ke layar sebelum "mulai pengalaman" sesuai dengan itu, tanpa perlu menilai fatalitasnya sendiri. - Error penolakan panggilan (
100001/103001/103002/103003/103004): dilempar secara sinkron / panggilan ditolak saat Anda secara aktif memanggil; error ini tidak mengakhiri sesi. - Error non-fatal lainnya (misalnya
101001/101002/105005/106001/106003): error ini tidak mengakhiri sesi; coba lagi seperti yang disarankan atau lanjutkan setelah menyuntikkan ulang token.
106001 mungkin memiliki dua penyebab: error jaringan lokal, atau apiHost yang salah. Jika mencoba lagi tidak memulihkan permintaan, periksa apakah apiHost dikonfigurasi dengan benar.106003 yang muncul setelah Anda mengatur model biasanya berarti nama/versi model salah atau tidak diaktifkan untuk akun Anda: periksa model bersama dengan apiHost dan token, yang semuanya harus berasal dari akun dan wilayah yang sama — gateway menolak ketidakcocokan dengan AccessDenied, dinormalisasi ke kode ini.