SDK de widgets do Livedeck: funções e eventos

Tudo o que o objeto livedeck faz: eventos, configurações, imagens, sons e contexto.

9 min de leitura Atualizado em 4 de nov. de 2026

O SDK é uma pequena biblioteca que o Livedeck disponibiliza no endereço de cada widget em /sdk/v1.js. Ele conecta seu widget ao overlay e fornece o objeto livedeck.

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

Carregue-o antes do seu próprio código. Assim que a página carrega, o SDK se conecta sozinho ao overlay. Você não precisa chamar nada para isso.

Funções

livedeck.on(type, fn)

Chama fn a cada evento desse tipo. Retorna uma função que remove fn de novo.

livedeck.off(type, fn)

Remove fn.

livedeck.ready(fn)

Chama fn assim que o overlay estiver conectado e as configurações tiverem chegado. Também retorna uma Promise.

livedeck.settings

As configurações atuais (somente leitura). Quando o usuário muda algo, chega o evento settings.

livedeck.context

{ mode, format, locale, size, scale, test }. size é o tamanho da página em pixels CSS, scale o zoom do widget redimensionado (1 no padrão). mode é live (link do OBS), editor (prévia) ou demo (Marketplace).

livedeck.host

{ handle, nickname, avatar } do streamer, só com a permissão host.profile; caso contrário, null.

livedeck.image(ref)

Transforma uma referência de imagem (avatar, gift.image) em um endereço local de imagem. Promise com o endereço ou null.

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

Toca o som da configuração de mídia key pelo Livedeck, com o volume geral. volume de 0 a 1. Precisa de media.play. Promise com true ou false.

livedeck.media.url(key)

Endereço local da imagem ou do clipe da configuração de mídia key. Promise com o endereço ou null.

livedeck.version

"1"

Eventos

gift

Permissão: events.gift

Campos: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest

chat

Permissão: events.chat

Campos: user (mais isModerator, isSubscriber, fanLevel), text

like

Permissão: events.like

Campos: user (ou null), count, total

follow

Permissão: events.follow

Campos: user

share

Permissão: events.share

Campos: user

join

Permissão: events.join

Campos: user

fanclub

Permissão: events.fanclub

Campos: user

viewers

Permissão: events.viewers

Campos: count

stream

Permissão: stream.status

Campos: status: live, offline ou checking

settings

Permissão: nenhum

Campos: as novas configurações

context

Permissão: nenhum

Campos: o novo contexto, por exemplo um novo tamanho

ready

Permissão: nenhum

Campos: uma vez após conectar

*

Permissão: nenhum

Campos: todos os eventos ao vivo acima

Todo evento ao vivo tem type e id. user é { handle, nickname, avatar }: handle é o nome de usuário do TikTok sem @, avatar uma referência de imagem para livedeck.image(). Mostre os espectadores pelo nome de usuário (“@” + handle). nickname é o nome de exibição que o espectador digitou e muitas vezes é um nome real: não mostre. Um widget nunca recebe IDs numéricos do TikTok, e-mails ou links.

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
}

Presentes

  • gift.diamonds é o preço em moedas de UM presente. count é o número de novos presentes neste evento, totalDiamonds = count × gift.diamonds as moedas que ele soma. Os combos já vêm descontados: some count e totalDiamonds, nada mais.
  • combo é a sequência inteira, só para exibição ("Rose ×7"): combo.count presentes até agora, combo.ended quando o TikTok fecha a sequência. Nunca some combo.count e nunca multiplique por ele.
  • Os valores em moedas sempre vêm do evento. Nunca use sua própria tabela de preços nem tente adivinhar o preço pelo nome do presente.
  • Maior presente individual: compare gift.diamonds. Top apoiadores / ranking: some totalDiamonds por user.handle.
  • toGuest é true quando o presente foi para um convidado numa LIVE com vários convidados.
  • Para um presente específico, use uma configuração do tipo gift e compare e.gift.id com o valor dela.

Curtidas

Durante a LIVE, o Livedeck agrupa as curtidas a cada 500 ms em um único evento: count é a soma nesse intervalo, total é a contagem geral da LIVE.

Exemplo: meta de presentes

Corresponde ao manifest.json da página "Referência do manifest.json". A página precisa de um elemento #bar e um #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);

Exemplo: chat com 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;
});

Bom saber

  • Os nomes e textos do chat são escritos pelos espectadores. Sempre insira com textContent, nunca com innerHTML.
  • O widget não tem armazenamento do navegador: localStorage, sessionStorage, IndexedDB e cookies são bloqueados. Guarde o estado na memória. Quando o usuário recarrega o overlay, o widget começa do zero.
  • Só dá para carregar arquivos do seu próprio pacote. fetch para outros sites, WebSockets, frames, formulários, pop-ups e sair da página são bloqueados.
  • O overlay verifica a cada 2000 ms se o seu widget ainda responde. O SDK responde sozinho, desde que seu código não trave o navegador.
  • Durante a LIVE, um widget recebe no máximo 50 mensagens por segundo. Com muitos eventos, presentes e chat têm prioridade.
  • Seu widget pode enviar no máximo 10 requisições por segundo ao overlay (por exemplo livedeck.image), cada uma com no máximo 64 KB. O SDK guarda as imagens, então a mesma referência só conta uma vez.
  • Sons tocados com livedeck.media.play passam pelo áudio do Livedeck, então valem o volume geral e a saída escolhida pelo usuário. Você também pode tocar sons do seu pacote com <audio>, mas eles ignoram o volume do Livedeck.
  • Coloque as fontes no pacote como .woff2 e carregue com @font-face e um caminho relativo. Você também pode gerar imagens por conta própria (canvas, data:, blob:).

Este artigo foi útil?