SDK de widget Livedeck : fonctions et événements

Tout ce que fait l’objet livedeck : événements, paramètres, images, sons et contexte.

9 min de lecture Mis à jour le 4 nov. 2026

Le SDK est une petite bibliothèque que Livedeck fournit à l’adresse de chaque widget sous /sdk/v1.js. Il connecte votre widget à l’overlay et fournit l’objet livedeck.

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

Chargez-le avant votre propre code. Dès que la page est chargée, le SDK se signale automatiquement à l’overlay. Vous n’avez rien à appeler pour cela.

Fonctions

livedeck.on(type, fn)

Appelle fn pour chaque événement de ce type. Renvoie une fonction qui retire fn.

livedeck.off(type, fn)

Retire fn.

livedeck.ready(fn)

Appelle fn dès que l’overlay est connecté et que les paramètres sont disponibles. Renvoie aussi une Promise.

livedeck.settings

Les paramètres actuels (lecture seule). Quand l’utilisateur modifie quelque chose, l’événement settings arrive.

livedeck.context

{ mode, format, locale, size, scale, test }. size est la taille de la page en pixels CSS, scale le zoom du widget redimensionné (1 par défaut). mode vaut live (lien OBS), editor (aperçu) ou demo (Marketplace).

livedeck.host

{ handle, nickname, avatar } du streamer, uniquement avec l’autorisation host.profile, sinon null.

livedeck.image(ref)

Convertit une référence d’image (avatar, gift.image) en adresse d’image locale. Promise avec l’adresse ou null.

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

Joue le son du paramètre média key via Livedeck, avec le volume principal. volume de 0 à 1. Nécessite media.play. Promise avec true ou false.

livedeck.media.url(key)

Adresse locale de l’image ou du clip du paramètre média key. Promise avec l’adresse ou null.

livedeck.version

"1"

Événements

gift

Permission: events.gift

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

chat

Permission: events.chat

Champs: user (plus isModerator, isSubscriber, fanLevel), text

like

Permission: events.like

Champs: user (ou null), count, total

follow

Permission: events.follow

Champs: user

share

Permission: events.share

Champs: user

join

Permission: events.join

Champs: user

fanclub

Permission: events.fanclub

Champs: user

viewers

Permission: events.viewers

Champs: count

stream

Permission: stream.status

Champs: status : live, offline ou checking

settings

Permission: aucun

Champs: les nouveaux paramètres

context

Permission: aucun

Champs: le nouveau contexte, par exemple une nouvelle taille

ready

Permission: aucun

Champs: une fois après la connexion

*

Permission: aucun

Champs: chaque événement live ci-dessus

Chaque événement live possède type et id. user vaut { handle, nickname, avatar } : handle est le nom d’utilisateur TikTok sans @, avatar une référence d’image pour livedeck.image(). Affichez les spectateurs par leur nom d’utilisateur ("@" + handle). nickname est le nom d’affichage saisi par le spectateur, souvent un vrai nom : ne l’affichez pas. Un widget ne reçoit jamais d’identifiants numériques TikTok, d’adresses e-mail ni de liens.

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
}

Cadeaux

  • gift.diamonds est le prix en pièces d’UN seul cadeau. count est le nombre de nouveaux cadeaux dans cet événement, totalDiamonds = count × gift.diamonds les pièces qu’il ajoute. Les combos sont déjà déduits : additionnez count et totalDiamonds, rien d’autre.
  • combo représente toute la série, uniquement pour l’affichage (« Rose ×7 ») : combo.count indique le nombre de cadeaux jusqu’ici, combo.ended dès que TikTok la clôture. N’additionnez jamais combo.count et ne multipliez jamais par cette valeur.
  • Les valeurs en pièces proviennent toujours de l’événement. N’utilisez jamais votre propre liste de prix et ne devinez jamais un prix à partir du nom du cadeau.
  • Plus gros cadeau unique : comparez gift.diamonds. Top supporters / classement : additionnez totalDiamonds par user.handle.
  • toGuest vaut true lorsque le cadeau a été envoyé à un invité dans un LIVE multi-invités.
  • Pour un cadeau précis, utilisez un paramètre de type gift et comparez e.gift.id à sa valeur.

J’aime

Pendant le LIVE, Livedeck regroupe les likes toutes les 500 ms en un seul événement : count est la somme sur cette période, total le nombre global du LIVE.

Exemple : objectif de cadeaux

Correspond au manifest.json de la page « Référence manifest.json ». La page doit contenir un élément #bar et un élément #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);

Exemple : chat avec photos de profil

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

Bon à savoir

  • Les noms et les messages du chat sont écrits par les spectateurs. Insérez-les toujours avec textContent, jamais avec innerHTML.
  • Le widget n’a pas de stockage navigateur : localStorage, sessionStorage, IndexedDB et les cookies sont bloqués. Gardez votre état en mémoire. Quand l’utilisateur recharge l’overlay, le widget repart de zéro.
  • Le chargement ne fonctionne que depuis votre propre package. Les fetch vers d’autres sites, les WebSockets, les frames, les formulaires, les pop-ups et la navigation vers d’autres pages sont bloqués.
  • L’overlay vérifie toutes les 2000 ms si votre widget répond encore. Le SDK répond tout seul tant que votre code ne bloque pas le navigateur.
  • Pendant le LIVE, un widget reçoit au maximum 50 messages par seconde. En cas de très nombreux événements, les cadeaux et le chat sont prioritaires.
  • Votre widget peut envoyer au maximum 10 requêtes par seconde à l’overlay (par exemple livedeck.image), de 64 Ko maximum chacune. Le SDK mémorise les images : une même référence n’est donc comptée qu’une fois.
  • Les sons joués avec livedeck.media.play passent par l’audio de Livedeck : le volume principal et la sortie choisie par l’utilisateur s’appliquent. Vous pouvez aussi jouer des sons de votre package avec <audio>, mais ils échappent au volume de Livedeck.
  • Ajoutez les polices au package en .woff2 et chargez-les avec @font-face et un chemin relatif. Vous pouvez aussi générer vous-même des images (canvas, data:, blob:).

Cet article vous a-t-il été utile ?