SDK de widgets do Livedeck: funções e eventos
Tudo o que o objeto livedeck faz: eventos, configurações, imagens, sons e contexto.
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.
<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"
| Chamada | O que faz |
|---|---|
| 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
| Tipo | Permissão | Campos |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (mais isModerator, isSubscriber, fanLevel), text |
| like | events.like | user (ou 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 ou checking |
| settings | nenhum | as novas configurações |
| context | nenhum | o novo contexto, por exemplo um novo tamanho |
| ready | nenhum | uma vez após conectar |
| * | nenhum | 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.
{
"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.
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
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?