SDK widget Livedeck: fungsi dan event
Semua yang bisa dilakukan objek livedeck: event, pengaturan, gambar, suara, dan konteks.
SDK adalah library kecil yang disediakan Livedeck di alamat setiap widget pada /sdk/v1.js. SDK ini menghubungkan widget kamu ke overlay dan menyediakan objek livedeck.
<script src="/sdk/v1.js"></script>Muat SDK sebelum kode kamu sendiri. Begitu halaman selesai dimuat, SDK otomatis melapor ke overlay. Kamu tidak perlu memanggil apa pun untuk itu.
Fungsi
livedeck.on(type, fn)
Memanggil fn untuk setiap event dengan tipe ini. Mengembalikan fungsi untuk menghapus fn lagi.
livedeck.off(type, fn)
Menghapus fn.
livedeck.ready(fn)
Memanggil fn setelah overlay terhubung dan pengaturan sudah tersedia. Juga mengembalikan Promise.
livedeck.settings
Pengaturan saat ini (hanya baca). Saat pengguna mengubah sesuatu, event settings akan masuk.
livedeck.context
{ mode, format, locale, size, scale, test }. size adalah ukuran halaman dalam piksel CSS, scale adalah zoom widget yang diubah ukurannya (1 secara default). mode bisa live (link OBS), editor (pratinjau), atau demo (Marketplace).
livedeck.host
{ handle, nickname, avatar } milik streamer, hanya dengan izin host.profile, selain itu null.
livedeck.image(ref)
Mengubah referensi gambar (avatar, gift.image) menjadi alamat gambar lokal. Promise berisi alamat atau null.
livedeck.media.play(key, { volume })
Memutar suara dari pengaturan media key lewat Livedeck, dengan volume utama. volume 0 sampai 1. Butuh media.play. Promise berisi true atau false.
livedeck.media.url(key)
Alamat lokal gambar atau klip dari pengaturan media key. Promise berisi alamat atau null.
livedeck.version
"1"
| Panggilan | Fungsinya |
|---|---|
| livedeck.on(type, fn) | Memanggil fn untuk setiap event dengan tipe ini. Mengembalikan fungsi untuk menghapus fn lagi. |
| livedeck.off(type, fn) | Menghapus fn. |
| livedeck.ready(fn) | Memanggil fn setelah overlay terhubung dan pengaturan sudah tersedia. Juga mengembalikan Promise. |
| livedeck.settings | Pengaturan saat ini (hanya baca). Saat pengguna mengubah sesuatu, event settings akan masuk. |
| livedeck.context | { mode, format, locale, size, scale, test }. size adalah ukuran halaman dalam piksel CSS, scale adalah zoom widget yang diubah ukurannya (1 secara default). mode bisa live (link OBS), editor (pratinjau), atau demo (Marketplace). |
| livedeck.host | { handle, nickname, avatar } milik streamer, hanya dengan izin host.profile, selain itu null. |
| livedeck.image(ref) | Mengubah referensi gambar (avatar, gift.image) menjadi alamat gambar lokal. Promise berisi alamat atau null. |
| livedeck.media.play(key, { volume }) | Memutar suara dari pengaturan media key lewat Livedeck, dengan volume utama. volume 0 sampai 1. Butuh media.play. Promise berisi true atau false. |
| livedeck.media.url(key) | Alamat lokal gambar atau klip dari pengaturan media key. Promise berisi alamat atau null. |
| livedeck.version | "1" |
Event
gift
Permission: events.gift
Field: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest
chat
Permission: events.chat
Field: user (plus isModerator, isSubscriber, fanLevel), text
like
Permission: events.like
Field: user (atau null), count, total
follow
Permission: events.follow
Field: user
share
Permission: events.share
Field: user
join
Permission: events.join
Field: user
fanclub
Permission: events.fanclub
Field: user
viewers
Permission: events.viewers
Field: count
stream
Permission: stream.status
Field: status: live, offline, atau checking
settings
Permission: tidak ada
Field: pengaturan baru
context
Permission: tidak ada
Field: konteks baru, misalnya ukuran baru
ready
Permission: tidak ada
Field: sekali setelah terhubung
*
Permission: tidak ada
Field: setiap event live di atas
| Jenis | Permission | Field |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (plus isModerator, isSubscriber, fanLevel), text |
| like | events.like | user (atau null), count, total |
| follow | events.follow | user |
| share | events.share | user |
| join | events.join | user |
| fanclub | events.fanclub | user |
| viewers | events.viewers | count |
| stream | stream.status | status: live, offline, atau checking |
| settings | tidak ada | pengaturan baru |
| context | tidak ada | konteks baru, misalnya ukuran baru |
| ready | tidak ada | sekali setelah terhubung |
| * | tidak ada | setiap event live di atas |
Setiap event live punya type dan id. user adalah { handle, nickname, avatar }: handle adalah username TikTok tanpa @, avatar adalah referensi gambar untuk livedeck.image(). Tampilkan penonton dengan username mereka ("@" + handle). nickname adalah nama tampilan yang diketik penonton dan sering berupa nama asli: jangan tampilkan. Widget tidak pernah mendapat ID angka TikTok, alamat e-mail, atau link.
{
"type": "gift",
"id": "42",
"user": { "handle": "lena.loops", "nickname": "Lena", "avatar": "i:7" },
"gift": { "id": 5655, "name": "Rose", "image": "i:8", "diamonds": 1 },
"count": 3,
"totalDiamonds": 3,
"combo": { "count": 7, "ended": false },
"toGuest": false
}Gift
- gift.diamonds adalah harga koin untuk SATU gift. count adalah jumlah gift baru di event ini, totalDiamonds = count × gift.diamonds adalah koin yang ditambahkan. Combo sudah diperhitungkan: cukup jumlahkan count dan totalDiamonds, tidak perlu yang lain.
- combo adalah seluruh rentetan, hanya untuk tampilan ("Rose ×7"): combo.count berisi jumlah gift sejauh ini, combo.ended saat TikTok menutupnya. Jangan pernah menjumlahkan combo.count, dan jangan pernah mengalikan dengannya.
- Nilai koin selalu diambil dari event. Jangan pakai daftar harga sendiri atau menebak harga dari nama gift.
- Gift tunggal terbesar: bandingkan gift.diamonds. Pendukung teratas / leaderboard: jumlahkan totalDiamonds per user.handle.
- toGuest bernilai true kalau gift dikirim ke tamu di LIVE multi-tamu.
- Untuk satu gift tertentu, pakai setting bertipe gift lalu bandingkan e.gift.id dengan nilainya.
Suka
Selama LIVE, Livedeck menggabungkan like setiap 500 ms jadi satu event: count adalah jumlah dalam rentang itu, total adalah jumlah keseluruhan di LIVE.
Contoh: target gift
Sesuai dengan manifest.json di halaman "Referensi manifest.json". Halamannya butuh elemen #bar dan #label.
let total = 0;
let reached = false;
function render() {
const goal = Number(livedeck.settings.goal) || 100;
const bar = document.getElementById("bar");
bar.style.width = Math.min(total / goal, 1) * 100 + "%";
bar.style.background = livedeck.settings.accent;
document.getElementById("label").textContent = total + " / " + goal;
if (!reached && total >= goal) {
reached = true;
if (livedeck.settings.doneSound) livedeck.media.play("doneSound", { volume: 0.8 });
}
}
livedeck.on("gift", (e) => {
const only = livedeck.settings.giftId;
if (only && e.gift.id !== only) return;
total += e.count; // counts gifts; for a diamond goal use e.totalDiamonds
render();
});
livedeck.on("settings", render);
livedeck.ready(render);Contoh: chat dengan foto profil
livedeck.on("chat", async (e) => {
const row = document.createElement("div");
const img = document.createElement("img");
img.alt = "";
row.append(img, "@" + e.user.handle + ": " + e.text);
document.getElementById("chat").prepend(row);
// picture reference → local address (or null, then it stays empty)
const url = await livedeck.image(e.user.avatar);
if (url) img.src = url;
});Perlu diketahui
- Nama dan teks chat ditulis oleh penonton. Selalu masukkan dengan textContent, jangan pernah dengan innerHTML.
- Widget tidak punya penyimpanan browser: localStorage, sessionStorage, IndexedDB, dan cookie diblokir. Simpan state di memori. Saat pengguna me-reload overlay, widget mulai dari awal.
- Memuat file hanya bisa dari paketmu sendiri. fetch ke situs lain, WebSocket, frame, form, pop-up, dan berpindah halaman diblokir.
- Overlay mengecek setiap 2000 ms apakah widgetmu masih merespons. SDK menjawab otomatis selama kodemu tidak memblokir browser.
- Selama LIVE, widget menerima maksimal 50 pesan per detik. Kalau event sangat banyak, gift dan chat didahulukan.
- Widgetmu boleh mengirim maksimal 10 request per detik ke overlay (misalnya livedeck.image), masing-masing maksimal 64 KB. SDK mengingat gambar, jadi referensi yang sama hanya dihitung sekali.
- Suara yang diputar dengan livedeck.media.play lewat audio Livedeck, jadi volume utama dan output pilihan pengguna ikut berlaku. Kamu juga bisa memutar suara dari paketmu dengan <audio>, tapi itu melewati volume Livedeck.
- Masukkan font ke paket sebagai .woff2 lalu muat dengan @font-face dan path relatif. Kamu juga boleh membuat gambar sendiri (canvas, data:, blob:).
Apakah artikel ini membantu?