@livespark/theme-sdk

SDK pour créer des thèmes LiveSpark (overlay TikTok Live).

Installation

npm install @livespark/theme-sdk

Utilisation

Configuration de base

import { createLiveSparkClient } from "@livespark/theme-sdk";

// Le SDK récupère automatiquement le token depuis l'URL ou via postMessage
const client = await createLiveSparkClient();

// Écouter les cadeaux
client.onGift((gift) => {
  console.log(
    "Cadeau reçu:",
    gift.giftName,
    "x",
    gift.giftCount
  );
});

// Écouter les messages de chat
client.onChatMessage((message) => {
  console.log(
    message.viewerName,
    ":",
    message.message
  );
});

// Écouter les nouveaux abonnés
client.onFollow((follow) => {
  console.log(
    "Nouvel abonné:",
    follow.viewerName
  );
});

// Écouter quand un utilisateur rejoint le live
client.onJoin((join) => {
  console.log(
    "👋 Nouvel arrivant:",
    join.viewerName
  );
});

// Écouter les likes sur le live
client.onLike((like) => {
  console.log(
    "❤️",
    like.viewerName,
    "a envoyé",
    like.likeCount,
    "like(s)"
  );
});

// Écouter tous les événements
client.onEvent((event) => {
  console.log(
    "Événement:",
    event.type,
    event.data
  );
});

// Écouter les événements de connexion
client.onConnected(() => {
  console.log("Connecté au live !");
});

client.onReconnected(() => {
  console.log("Reconnecté au live !");
});

client.onDisconnected((reason) => {
  console.log("Déconnecté:", reason);
});

// Vérifier le statut du live
const status = await client.getLiveStatus();
if (status.isLive) {
  console.log("Le live est actif !");
}

// Écouter les changements de statut du live (actif/inactif)
client.onLiveStatusChange((status) => {
  if (status.isLive) {
    console.log(
      "Le live vient de démarrer !",
      status.liveId
    );
  } else {
    console.log("Le live vient de se terminer");
  }
});

Gestion automatique de la reconnexion

Par défaut, le SDK gère automatiquement :

• ✅ Polling automatique : Vérifie le statut du live toutes les 10 secondes
• ✅ Reconnexion automatique : Se reconnecte automatiquement quand le live redevient actif
• ✅ Détection des changements : Notifie via onLiveStatusChange quand le live démarre/s'arrête

// Configuration par défaut (recommandée)
const client = await createLiveSparkClient({
  autoPolling: true, // Active le polling (défaut: true)
  pollingInterval: 10000, // Vérifie toutes les 10s (défaut: 10000ms)
  autoReconnect: true, // Reconnexion auto (défaut: true)
});

// Désactiver le polling si nécessaire
client.stopPolling();

// Réactiver le polling
client.startPolling();

Vérification du statut sans créer de client

import { getLiveStatus } from "@livespark/theme-sdk";

// Vérifier si un live est actif avant d'initialiser le SDK
const status = await getLiveStatus(
  "votre-token",
  {
    devMode: true,
  }
);

if (status.isLive) {
  console.log("Live actif, ID:", status.liveId);
  // Initialiser le client complet
  const client = await createLiveSparkClient({
    token: "votre-token",
    devMode: true,
  });
} else {
  console.log("Aucun live actif");
}

Mode développement

const client = await createLiveSparkClient({
  devMode: true, // Utilise http://localhost:4000
  token: "votre-token-de-test",
});

Configuration avancée

const client = await createLiveSparkClient({
  apiUrl: "https://custom-api.example.com", // URL personnalisée
  hostOrigin: "https://livespark.live", // Validation de l'origine des messages
  token: "token-manuel", // Token manuel (optionnel)
});

API

createLiveSparkClient(options?)

Crée et initialise un client LiveSpark.

Options:

• token?: string - Token d'authentification (optionnel si utilisé dans un iframe)
• devMode?: boolean - Mode développement (utilise localhost:4000)
• apiUrl?: string - URL de l'API personnalisée
• hostOrigin?: string - Origine de l'hôte pour la validation des messages
• autoPolling?: boolean - Active le polling automatique du statut (défaut: true)
• pollingInterval?: number - Intervalle de polling en ms (défaut: 10000)
• autoReconnect?: boolean - Reconnexion automatique quand le live redevient actif (défaut: true)

Retourne: Promise<LiveSparkClient>

getLiveStatus(token, options?)

Vérifie le statut du live sans créer de client complet.

Paramètres:

• token: string - Token d'authentification (requis)
• options?: object
  • devMode?: boolean - Mode développement
  • apiUrl?: string - URL de l'API personnalisée

Retourne: Promise<LiveSparkStatus>

LiveSparkClient

Méthodes:

• onGift(handler) - Écouter les événements de cadeaux
• onChatMessage(handler) - Écouter les messages de chat
• onFollow(handler) - Écouter les nouveaux abonnés
• onJoin(handler) - Écouter quand un utilisateur rejoint le live
• onLike(handler) - Écouter les likes sur le live
• onEvent(handler) - Écouter tous les événements
• onConnected(handler) - Écouter la connexion initiale
• onReconnected(handler) - Écouter les reconnexions
• onDisconnected(handler) - Écouter les déconnexions
• onLiveStatusChange(handler) - Écouter les changements de statut du live
• getLiveStatus() - Récupérer le statut du live
• stopPolling() - Arrêter le polling automatique
• startPolling() - Redémarrer le polling automatique
• disconnect() - Déconnecter le client

Types

LiveSparkStatus

{
  isLive: boolean;        // Indique si le live est actif
  liveId?: string;        // ID du live (si actif)
  live?: {                // Informations du live
    id: string;
    title?: string;
    startedAt?: string;
    [key: string]: any;
  };
}

LiveSparkGiftEvent

{
  eventType: string;
  giftCount: number;
  giftName: string;
  giftValue: number;
  viewerId: string;
  viewerName: string;
}

LiveSparkChatMessageEvent

{
  eventType: string;
  message: string;
  profilePictureUrl: string;
  viewerId: string;
  viewerName: string;
  timestamp: number;
}

LiveSparkFollowEvent

{
  eventType: string;
  viewerId: string;
  viewerName: string;
}

LiveSparkJoinEvent

{
  eventType: string;
  viewerId: string;
  viewerName: string;
  profilePictureUrl?: string;
}

LiveSparkLikeEvent

{
  eventType: string;
  viewerId: string;
  viewerName: string;
  likeCount: number;      // Nombre de likes envoyés
  totalLikes?: number;    // Total de likes sur le live (optionnel)
}

Licence

MIT