SDK de widgets de Livedeck: funciones y eventos
Todo lo que hace el objeto livedeck: eventos, ajustes, imágenes, sonidos y contexto.
El SDK es una pequeña biblioteca que Livedeck sirve en la dirección de cada widget bajo /sdk/v1.js. Conecta tu widget con el overlay y proporciona el objeto livedeck.
<script src="/sdk/v1.js"></script>Cárgalo antes de tu propio código. En cuanto la página se carga, el SDK se comunica solo con el overlay. No tienes que llamar a nada para eso.
Funciones
livedeck.on(type, fn)
Llama a fn en cada evento de este tipo. Devuelve una función que vuelve a quitar fn.
livedeck.off(type, fn)
Quita fn.
livedeck.ready(fn)
Llama a fn cuando el overlay está conectado y los ajustes ya llegaron. También devuelve una Promise.
livedeck.settings
Los ajustes actuales (solo lectura). Cuando el usuario cambia algo, llega el evento settings.
livedeck.context
{ mode, format, locale, size, scale, test }. size es el tamaño de la página en píxeles CSS, scale el zoom del widget redimensionado (1 por defecto). mode es live (enlace de OBS), editor (vista previa) o demo (Marketplace).
livedeck.host
{ handle, nickname, avatar } del streamer, solo con el permiso host.profile; si no, null.
livedeck.image(ref)
Convierte una referencia de imagen (avatar, gift.image) en una dirección de imagen local. Promise con la dirección o null.
livedeck.media.play(key, { volume })
Reproduce a través de Livedeck el sonido del ajuste de medios key, con el volumen general. volume de 0 a 1. Requiere media.play. Promise con true o false.
livedeck.media.url(key)
Dirección local de la imagen o el clip del ajuste de medios key. Promise con la dirección o null.
livedeck.version
"1"
| Llamada | Qué hace |
|---|---|
| livedeck.on(type, fn) | Llama a fn en cada evento de este tipo. Devuelve una función que vuelve a quitar fn. |
| livedeck.off(type, fn) | Quita fn. |
| livedeck.ready(fn) | Llama a fn cuando el overlay está conectado y los ajustes ya llegaron. También devuelve una Promise. |
| livedeck.settings | Los ajustes actuales (solo lectura). Cuando el usuario cambia algo, llega el evento settings. |
| livedeck.context | { mode, format, locale, size, scale, test }. size es el tamaño de la página en píxeles CSS, scale el zoom del widget redimensionado (1 por defecto). mode es live (enlace de OBS), editor (vista previa) o demo (Marketplace). |
| livedeck.host | { handle, nickname, avatar } del streamer, solo con el permiso host.profile; si no, null. |
| livedeck.image(ref) | Convierte una referencia de imagen (avatar, gift.image) en una dirección de imagen local. Promise con la dirección o null. |
| livedeck.media.play(key, { volume }) | Reproduce a través de Livedeck el sonido del ajuste de medios key, con el volumen general. volume de 0 a 1. Requiere media.play. Promise con true o false. |
| livedeck.media.url(key) | Dirección local de la imagen o el clip del ajuste de medios key. Promise con la dirección o null. |
| livedeck.version | "1" |
Eventos
gift
Permiso: events.gift
Campos: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest
chat
Permiso: events.chat
Campos: user (más isModerator, isSubscriber, fanLevel), text
like
Permiso: events.like
Campos: user (o null), count, total
follow
Permiso: events.follow
Campos: user
share
Permiso: events.share
Campos: user
join
Permiso: events.join
Campos: user
fanclub
Permiso: events.fanclub
Campos: user
viewers
Permiso: events.viewers
Campos: count
stream
Permiso: stream.status
Campos: status: live, offline o checking
settings
Permiso: ninguno
Campos: los nuevos ajustes
context
Permiso: ninguno
Campos: el nuevo contexto, por ejemplo un nuevo tamaño
ready
Permiso: ninguno
Campos: una vez tras conectarse
*
Permiso: ninguno
Campos: cada evento en vivo de arriba
| Tipo | Permiso | Campos |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (más isModerator, isSubscriber, fanLevel), text |
| like | events.like | user (o 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 o checking |
| settings | ninguno | los nuevos ajustes |
| context | ninguno | el nuevo contexto, por ejemplo un nuevo tamaño |
| ready | ninguno | una vez tras conectarse |
| * | ninguno | cada evento en vivo de arriba |
Cada evento en vivo tiene type e id. user es { handle, nickname, avatar }: handle es el nombre de usuario de TikTok sin @, avatar una referencia de imagen para livedeck.image(). Muestra a los espectadores por su nombre de usuario ("@" + handle). nickname es el nombre visible que escribió el espectador y a menudo es un nombre real: no lo muestres. Un widget nunca recibe IDs numéricos de TikTok, direcciones de correo ni enlaces.
{
"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
}Regalos
- gift.diamonds es el precio en monedas de UN regalo. count es el número de regalos nuevos en este evento, totalDiamonds = count × gift.diamonds las monedas que suma. Los combos ya vienen descontados: suma count y totalDiamonds, nada más.
- combo es la racha completa, solo para mostrarla (“Rose ×7”): combo.count son los regalos hasta ahora y combo.ended se activa cuando TikTok la cierra. Nunca sumes combo.count ni multipliques por él.
- Los valores en monedas siempre vienen del evento. Nunca uses tu propia lista de precios ni adivines un precio por el nombre del regalo.
- Regalo individual más grande: compara gift.diamonds. Top supporter / ranking: suma totalDiamonds por user.handle.
- toGuest es true cuando el regalo fue para un invitado en un LIVE con varios invitados.
- Para un regalo concreto, usa un ajuste de tipo gift y compara e.gift.id con su valor.
Likes
Durante el LIVE, Livedeck agrupa los likes cada 500 ms en un solo evento: count es la suma en ese tiempo y total, el conteo general del LIVE.
Ejemplo: meta de regalos
Coincide con el manifest.json de la página “Referencia de manifest.json”. La página necesita un elemento #bar y uno #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);Ejemplo: chat con fotos de perfil
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;
});Bueno saber
- Los nombres y textos del chat los escriben los espectadores. Insértalos siempre con textContent, nunca con innerHTML.
- El widget no tiene almacenamiento del navegador: localStorage, sessionStorage, IndexedDB y las cookies están bloqueados. Guarda tu estado en memoria. Cuando el usuario recarga el overlay, el widget empieza de cero.
- Solo se puede cargar desde tu propio paquete. fetch a otros sitios, WebSockets, frames, formularios, pop-ups y salir de la página están bloqueados.
- El overlay comprueba cada 2000 ms si tu widget sigue respondiendo. El SDK responde solo mientras tu código no bloquee el navegador.
- Durante el LIVE, un widget recibe como máximo 50 mensajes por segundo. Con muchísimos eventos, los regalos y el chat van primero.
- Tu widget puede enviar como máximo 10 solicitudes por segundo al overlay (por ejemplo, livedeck.image), de 64 KB como máximo cada una. El SDK recuerda las imágenes, así que la misma referencia solo cuenta una vez.
- Los sonidos reproducidos con livedeck.media.play pasan por el audio de Livedeck, así que se aplican el volumen general y la salida que eligió el usuario. También puedes reproducir sonidos de tu paquete con <audio>, pero esos ignoran el volumen de Livedeck.
- Incluye las fuentes en el paquete como .woff2 y cárgalas con @font-face y una ruta relativa. También puedes generar imágenes tú mismo (canvas, data:, blob:).
¿Te resultó útil este artículo?