Livedeck widget SDK’sı: fonksiyonlar ve olaylar
livedeck nesnesinin yaptığı her şey: olaylar, ayarlar, resimler, sesler ve bağlam.
SDK, Livedeck’in her widget’ın adresinde /sdk/v1.js altında sunduğu küçük bir kütüphanedir. Widget’ını overlay’e bağlar ve livedeck nesnesini sağlar.
<script src="/sdk/v1.js"></script>Kendi kodundan önce yükle. Sayfa yüklenir yüklenmez SDK overlay’e kendiliğinden bildirir. Bunun için bir şey çağırman gerekmez.
Fonksiyonlar
livedeck.on(type, fn)
Bu türdeki her olay için fn’i çağırır. fn’i tekrar kaldıran bir fonksiyon döndürür.
livedeck.off(type, fn)
fn’i kaldırır.
livedeck.ready(fn)
Overlay bağlandığında ve ayarlar geldiğinde fn’i çağırır. Ayrıca bir Promise döndürür.
livedeck.settings
Mevcut ayarlar (salt okunur). Kullanıcı bir şeyi değiştirdiğinde settings olayı gelir.
livedeck.context
{ mode, format, locale, size, scale, test }. size CSS pikseli cinsinden sayfa boyutu, scale yeniden boyutlandırılan widget’ın yakınlaştırması (varsayılanda 1). mode; live (OBS linki), editor (önizleme) ya da demo (Marketplace) olur.
livedeck.host
Yayıncının { handle, nickname, avatar } bilgisi; yalnızca host.profile izniyle, aksi halde null.
livedeck.image(ref)
Bir resim referansını (avatar, gift.image) yerel bir resim adresine çevirir. Adresi ya da null’u içeren Promise.
livedeck.media.play(key, { volume })
key medya ayarındaki sesi Livedeck üzerinden ana ses seviyesiyle çalar. volume 0 ile 1 arası. media.play gerekir. true ya da false içeren Promise.
livedeck.media.url(key)
key medya ayarındaki resmin ya da klibin yerel adresi. Adresi ya da null’u içeren Promise.
livedeck.version
"1"
| Çağrı | Ne yapar |
|---|---|
| livedeck.on(type, fn) | Bu türdeki her olay için fn’i çağırır. fn’i tekrar kaldıran bir fonksiyon döndürür. |
| livedeck.off(type, fn) | fn’i kaldırır. |
| livedeck.ready(fn) | Overlay bağlandığında ve ayarlar geldiğinde fn’i çağırır. Ayrıca bir Promise döndürür. |
| livedeck.settings | Mevcut ayarlar (salt okunur). Kullanıcı bir şeyi değiştirdiğinde settings olayı gelir. |
| livedeck.context | { mode, format, locale, size, scale, test }. size CSS pikseli cinsinden sayfa boyutu, scale yeniden boyutlandırılan widget’ın yakınlaştırması (varsayılanda 1). mode; live (OBS linki), editor (önizleme) ya da demo (Marketplace) olur. |
| livedeck.host | Yayıncının { handle, nickname, avatar } bilgisi; yalnızca host.profile izniyle, aksi halde null. |
| livedeck.image(ref) | Bir resim referansını (avatar, gift.image) yerel bir resim adresine çevirir. Adresi ya da null’u içeren Promise. |
| livedeck.media.play(key, { volume }) | key medya ayarındaki sesi Livedeck üzerinden ana ses seviyesiyle çalar. volume 0 ile 1 arası. media.play gerekir. true ya da false içeren Promise. |
| livedeck.media.url(key) | key medya ayarındaki resmin ya da klibin yerel adresi. Adresi ya da null’u içeren Promise. |
| livedeck.version | "1" |
Olaylar
gift
İzin: events.gift
Alanlar: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest
chat
İzin: events.chat
Alanlar: user (ayrıca isModerator, isSubscriber, fanLevel), text
like
İzin: events.like
Alanlar: user (ya da null), count, total
follow
İzin: events.follow
Alanlar: user
share
İzin: events.share
Alanlar: user
join
İzin: events.join
Alanlar: user
fanclub
İzin: events.fanclub
Alanlar: user
viewers
İzin: events.viewers
Alanlar: count
stream
İzin: stream.status
Alanlar: status: live, offline ya da checking
settings
İzin: yok
Alanlar: yeni ayarlar
context
İzin: yok
Alanlar: yeni bağlam, örneğin yeni bir boyut
ready
İzin: yok
Alanlar: bağlandıktan sonra bir kez
*
İzin: yok
Alanlar: yukarıdaki her canlı olay
| Tür | İzin | Alanlar |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (ayrıca isModerator, isSubscriber, fanLevel), text |
| like | events.like | user (ya da 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 ya da checking |
| settings | yok | yeni ayarlar |
| context | yok | yeni bağlam, örneğin yeni bir boyut |
| ready | yok | bağlandıktan sonra bir kez |
| * | yok | yukarıdaki her canlı olay |
Her canlı olayın type ve id’si vardır. user { handle, nickname, avatar } şeklindedir: handle @ olmadan TikTok kullanıcı adı, avatar ise livedeck.image() için bir resim referansıdır. İzleyicileri kullanıcı adlarıyla göster ("@" + handle). nickname izleyicinin girdiği görünen addır ve çoğu zaman gerçek isimdir: bunu gösterme. Widget asla TikTok sayısal ID’lerini, e-posta adreslerini ya da linkleri almaz.
{
"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
}Hediyeler
- gift.diamonds TEK bir hediyenin jeton fiyatıdır. count bu olaydaki yeni hediye sayısı, totalDiamonds = count × gift.diamonds ise eklediği jetonlardır. Kombolar zaten mahsup edilmiştir: count ve totalDiamonds’ı topla, başka bir şey yapma.
- combo sadece gösterim için tüm seriyi verir („Rose ×7”): combo.count şu ana kadarki hediye sayısı, combo.ended ise TikTok seriyi kapattığında gelir. combo.count’u asla toplama ve asla onunla çarpma.
- Jeton değerleri her zaman event’ten gelir. Asla kendi fiyat listeni kullanma ve hediye adından fiyat tahmin etme.
- En büyük tekil hediye: gift.diamonds’u karşılaştır. En iyi destekçi / sıralama: totalDiamonds’u user.handle başına topla.
- Hediye çok konuklu bir LIVE’da bir konuğa gittiyse toGuest true olur.
- Belirli bir hediye için gift türünde bir ayar kullan ve e.gift.id’yi onun değeriyle karşılaştır.
Beğeniler
LIVE sırasında Livedeck beğenileri her 500 ms’de tek bir event’te toplar: count bu süredeki toplam, total ise LIVE’ın genel sayısıdır.
Örnek: hediye hedefi
„manifest.json referansı” sayfasındaki manifest.json ile eşleşir. Sayfada bir #bar ve bir #label öğesi olmalı.
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);Örnek: profil fotoğraflı sohbet
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;
});Bilmekte fayda var
- İsimleri ve sohbet metinlerini izleyiciler yazar. Bunları her zaman textContent ile ekle, asla innerHTML ile ekleme.
- Widget’ın tarayıcı depolaması yok: localStorage, sessionStorage, IndexedDB ve çerezler engellenir. Durumunu bellekte tut. Kullanıcı overlay’i yeniden yüklediğinde widget baştan başlar.
- Yükleme sadece kendi paketinden çalışır. Başka sitelere fetch, WebSocket’ler, frame’ler, formlar, pop-up’lar ve sayfadan ayrılma engellenir.
- Overlay her 2000 ms’de widget’ının hâlâ yanıt verip vermediğini kontrol eder. Kodun tarayıcıyı kilitlemediği sürece SDK kendiliğinden yanıt verir.
- LIVE sırasında bir widget saniyede en fazla 50 mesaj alır. Çok fazla event olduğunda öncelik hediyeler ve sohbettedir.
- Widget’ın overlay’e saniyede en fazla 10 istek gönderebilir (örneğin livedeck.image), her biri en fazla 64 KB. SDK resimleri hatırlar, yani aynı referans yalnızca bir kez maliyet çıkarır.
- livedeck.media.play ile çalınan sesler Livedeck’in ses sisteminden geçer, bu yüzden ana ses seviyesi ve kullanıcının seçtiği çıkış geçerli olur. Paketindeki sesleri <audio> ile de çalabilirsin, ama bunlar Livedeck’in ses seviyesini atlar.
- Fontları pakete .woff2 olarak koy ve @font-face ile göreli bir yolla yükle. Resimleri kendin de oluşturabilirsin (canvas, data:, blob:).
Bu makale işine yaradı mı?