SDK de widget Livedeck : fonctions et événements
Tout ce que fait l’objet livedeck : événements, paramètres, images, sons et contexte.
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.
<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"
| Appel | Rôle |
|---|---|
| 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
| Type | Permission | Champs |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (plus 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 | aucun | les nouveaux paramètres |
| context | aucun | le nouveau contexte, par exemple une nouvelle taille |
| ready | aucun | une fois après la connexion |
| * | aucun | 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.
{
"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.
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
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 ?