SDK de widgets de Livedeck: funciones y eventos

Todo lo que hace el objeto livedeck: eventos, ajustes, imágenes, sonidos y contexto.

9 min de lectura Actualizado el 4 nov 2026

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.

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

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

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.

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
}

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.

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

Ejemplo: chat con fotos de perfil

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

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?