SDK widget Livedeck: fungsi dan event

Semua yang bisa dilakukan objek livedeck: event, pengaturan, gambar, suara, dan konteks.

9 menit baca Diperbarui 4 Nov 2026

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.

html
<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"

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

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.

json
{
  "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.

js
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

js
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?