Livedeck widget SDK: ฟังก์ชันและอีเวนต์

ทุกอย่างที่ออบเจ็กต์ livedeck ทำได้: อีเวนต์ การตั้งค่า รูปภาพ เสียง และบริบท

อ่าน 9 นาที อัปเดตเมื่อ 4 พ.ย. 2569

SDK คือไลบรารีขนาดเล็กที่ Livedeck ให้บริการที่ที่อยู่ของทุก widget ภายใต้ /sdk/v1.js ทำหน้าที่เชื่อม widget ของคุณกับ overlay และให้ออบเจ็กต์ livedeck

html
<script src="/sdk/v1.js"></script>

โหลด SDK ก่อนโค้ดของคุณเอง เมื่อหน้าโหลดเสร็จ SDK จะแจ้ง overlay เองโดยอัตโนมัติ ไม่ต้องเรียกอะไรเพิ่ม

ฟังก์ชัน

livedeck.on(type, fn)

เรียก fn ทุกครั้งที่มีอีเวนต์ชนิดนี้ และคืนค่าเป็นฟังก์ชันที่ใช้ลบ fn ออก

livedeck.off(type, fn)

ลบ fn ออก

livedeck.ready(fn)

เรียก fn เมื่อ overlay เชื่อมต่อแล้วและได้รับการตั้งค่าแล้ว และคืนค่าเป็น Promise ด้วย

livedeck.settings

การตั้งค่าปัจจุบัน (อ่านอย่างเดียว) เมื่อผู้ใช้เปลี่ยนแปลงค่า จะได้รับอีเวนต์ settings

livedeck.context

{ mode, format, locale, size, scale, test } โดย size คือขนาดหน้าเป็น CSS pixel ส่วน scale คือการซูมของ widget ที่ปรับขนาด (ค่าเริ่มต้นคือ 1) และ mode คือ live (ลิงก์ OBS), editor (พรีวิว) หรือ demo (Marketplace)

livedeck.host

{ handle, nickname, avatar } ของสตรีมเมอร์ ใช้ได้เฉพาะเมื่อมีสิทธิ์ host.profile ไม่เช่นนั้นจะเป็น null

livedeck.image(ref)

แปลงการอ้างอิงรูปภาพ (avatar, gift.image) เป็นที่อยู่รูปภาพในเครื่อง คืนค่าเป็น Promise พร้อมที่อยู่หรือ null

livedeck.media.play(key, { volume })

เล่นเสียงจากการตั้งค่าสื่อ key ผ่าน Livedeck ด้วยระดับเสียงหลัก volume 0 ถึง 1 ต้องมีสิทธิ์ media.play คืนค่าเป็น Promise พร้อม true หรือ false

livedeck.media.url(key)

ที่อยู่ในเครื่องของรูปภาพหรือคลิปจากการตั้งค่าสื่อ key คืนค่าเป็น Promise พร้อมที่อยู่หรือ null

livedeck.version

"1"

อีเวนต์

gift

สิทธิ์: events.gift

ฟิลด์: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest

chat

สิทธิ์: events.chat

ฟิลด์: user (พร้อม isModerator, isSubscriber, fanLevel), text

like

สิทธิ์: events.like

ฟิลด์: user (หรือ 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 หรือ checking

settings

สิทธิ์: ไม่มี

ฟิลด์: การตั้งค่าใหม่

context

สิทธิ์: ไม่มี

ฟิลด์: บริบทใหม่ เช่น ขนาดใหม่

ready

สิทธิ์: ไม่มี

ฟิลด์: หนึ่งครั้งหลังเชื่อมต่อ

*

สิทธิ์: ไม่มี

ฟิลด์: ทุกอีเวนต์ LIVE ด้านบน

ทุกอีเวนต์ LIVE มี type และ id ส่วน user คือ { handle, nickname, avatar } โดย handle คือชื่อผู้ใช้ TikTok ที่ไม่มี @ และ avatar คือการอ้างอิงรูปภาพสำหรับ livedeck.image() ให้แสดงผู้ชมด้วยชื่อผู้ใช้ ("@" + handle) ส่วน nickname คือชื่อที่แสดงซึ่งผู้ชมตั้งเองและมักเป็นชื่อจริง: ห้ามแสดง widget จะไม่ได้รับ ID ตัวเลขของ TikTok อีเมล หรือลิงก์ใดๆ

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.diamonds คือราคาเหรียญของของขวัญหนึ่งชิ้น count คือจำนวนของขวัญใหม่ในอีเวนต์นี้ และ totalDiamonds = count × gift.diamonds คือเหรียญที่เพิ่มขึ้น คอมโบถูกหักลบให้แล้ว: แค่รวม count และ totalDiamonds ก็พอ ไม่ต้องทำอย่างอื่น
  • combo คือสตรีคทั้งหมดสำหรับแสดงผลเท่านั้น ("Rose ×7"): combo.count คือจำนวนของขวัญจนถึงตอนนี้ combo.ended เมื่อ TikTok ปิดสตรีคแล้ว ห้ามรวม combo.count และห้ามคูณด้วยค่านี้เด็ดขาด
  • ค่าเหรียญมาจากอีเวนต์เสมอ ห้ามใช้รายการราคาของตัวเองหรือเดาราคาจากชื่อของขวัญ
  • ของขวัญชิ้นใหญ่ที่สุด: เปรียบเทียบ gift.diamonds ผู้สนับสนุนอันดับต้น / ลีดเดอร์บอร์ด: รวม totalDiamonds ต่อ user.handle
  • toGuest เป็น true เมื่อของขวัญส่งให้แขกใน LIVE แบบหลายแขก
  • สำหรับของขวัญชิ้นใดชิ้นหนึ่ง ให้ใช้การตั้งค่าประเภท gift แล้วเปรียบเทียบ e.gift.id กับค่าของการตั้งค่านั้น

ถูกใจ

ระหว่าง LIVE นั้น Livedeck จะรวมยอดถูกใจทุก 500 ms เป็นอีเวนต์เดียว: count คือผลรวมในช่วงเวลานั้น total คือยอดรวมทั้งหมดของ LIVE

ตัวอย่าง: เป้าหมายของขวัญ

ตรงกับ manifest.json ในหน้า "ข้อมูลอ้างอิง manifest.json" หน้าเว็บต้องมีองค์ประกอบ #bar และ #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);

ตัวอย่าง: แชทพร้อมรูปโปรไฟล์

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;
});

ควรรู้

  • ชื่อและข้อความแชทมาจากผู้ชม ให้แทรกด้วย textContent เสมอ ห้ามใช้ innerHTML
  • วิดเจ็ตไม่มีพื้นที่จัดเก็บของเบราว์เซอร์: localStorage, sessionStorage, IndexedDB และคุกกี้ถูกบล็อก ให้เก็บสถานะไว้ในหน่วยความจำ เมื่อผู้ใช้รีโหลด overlay วิดเจ็ตจะเริ่มใหม่
  • โหลดได้จากแพ็กเกจของคุณเองเท่านั้น การ fetch ไปยังเว็บอื่น, WebSockets, เฟรม, ฟอร์ม, ป๊อปอัป และการนำทางออกจากหน้าจะถูกบล็อก
  • overlay จะตรวจสอบทุก 2000 ms ว่าวิดเจ็ตยังตอบสนองอยู่หรือไม่ SDK จะตอบเองตราบใดที่โค้ดของคุณไม่ทำให้เบราว์เซอร์ค้าง
  • ระหว่าง LIVE วิดเจ็ตได้รับข้อความสูงสุด 50 ข้อความต่อวินาที หากมีอีเวนต์จำนวนมาก ของขวัญและแชทจะมาก่อน
  • วิดเจ็ตส่งคำขอไปยัง overlay ได้สูงสุด 10 ครั้งต่อวินาที (เช่น livedeck.image) ครั้งละไม่เกิน 64 KB SDK จะจำรูปภาพไว้ ดังนั้นการอ้างอิงเดิมจะนับแค่ครั้งเดียว
  • เสียงที่เล่นด้วย livedeck.media.play จะผ่านระบบเสียงของ Livedeck จึงใช้ระดับเสียงหลักและเอาต์พุตที่ผู้ใช้เลือก คุณเล่นเสียงจากแพ็กเกจด้วย <audio> ได้เช่นกัน แต่จะไม่ผ่านระดับเสียงของ Livedeck
  • ใส่ฟอนต์ไว้ในแพ็กเกจเป็น .woff2 แล้วโหลดด้วย @font-face และพาธแบบสัมพัทธ์ คุณสร้างรูปภาพเองได้ด้วย (canvas, data:, blob:)

บทความนี้มีประโยชน์ไหม?