Aller au contenu

SDK JavaScript

Le SDK expose l’objet global window.iDalgo. Les balises data-idalgo-* suffisent dans la plupart des cas ; l’API JavaScript sert au rendu à la demande, aux applications monopages et au suivi des widgets.

<script src="https://delivery.idalgo.live/sdk/v1.js" async></script>

/sdk/v1.js est figée sur la version majeure 1 du SDK : elle reçoit les corrections et les ajouts compatibles, jamais un changement qui vous obligerait à modifier votre intégration. Un tel changement sortira sous une autre URL (/sdk/v2.js), annoncée dans le journal des changements, et /sdk/v1.js continuera de répondre.

/sdk.js, l’URL des premières intégrations, sert le même script que /sdk/v1.js et le restera : passez à /sdk/v1.js à votre rythme.

Le navigateur et le CDN gardent le script une heure, puis le revalident (ETag) : une correction atteint vos pages dans l’heure, sans changer votre balise. iDalgo.version donne la version déployée.

Réglages globaux, fusionnés à chaque appel.

iDalgo.configure({
key: "idl_pk_…", // votre clé publique, envoyée en Authorization (voir Votre clé)
client: "votre-media", // votre identifiant : thème, direct et réglages de tous les widgets
lazyLoad: true, // chargement différé
lazyLoadMargin: "200px", // marge de préchargement
cacheTTL: 300, // cache en mémoire, en secondes
retryCount: 2, // nouvelles tentatives sur erreur passagère (réseau, 5xx, 429)
retryDelay: 1000, // délai initial entre deux tentatives, en ms
onError: (error) => {}, // gestionnaire d'erreur global
loadingTemplate: "<div>Chargement…</div>", // HTML affiché pendant le chargement
});
Option Type Défaut Description
baseUrl string Origine du SDK URL du serveur iDalgo
key string data-idalgo-key de la page Votre clé publique idl_pk_…, envoyée en Authorization (voir Votre clé)
links object — Gabarits des liens vers vos pages (voir Liens)
client string — Votre identifiant (voir Identifiant client)
lazyLoad boolean true Chargement différé des widgets hors écran
lazyLoadMargin string "200px" Marge avant le déclenchement
cacheTTL number 300 Durée du cache en mémoire (secondes) quand le serveur n’en indique pas
retryCount number 2 Tentatives sur erreur passagère (réseau, 5xx, 429)
retryDelay number 1000 Délai initial entre tentatives (ms)
onError (error) => void — Gestionnaire d’erreur global
loadingTemplate string | null Indicateur iDalgo HTML affiché pendant le chargement

Un widget reste en cache le temps de sa donnée la plus fraîche, que le serveur indique avec le fragment : une minute le jour d’un match (pendant le direct, le widget se met ensuite à jour seul), 5 minutes pour une saison en cours, un jour au plus pour l’historique. cacheTTL ne sert que si le serveur n’en dit rien.

Les scripts des widgets ont des noms qui changent à chaque version : le navigateur les garde un an sans les redemander. iDalgo.version donne la version déployée, la même que meta.version des fragments.

Côté réseau, le fragment arrive compressé (brotli ou gzip) et porte un ETag : passé ce délai, le navigateur le revalide et ne le retélécharge que s’il a changé. Le SDK lui-même se revalide de la même façon.

client (ou data-idalgo-client sur une balise) désigne votre média. iDalgo y associe vos réglages, appliqués à chaque widget :

  • le thème de vos widgets, et leur mode (clair, sombre ou automatique) ;
  • le direct de la feuille de match, de la liste de matchs, du Score Center et du tableau de phase finale, selon votre offre ;
  • des valeurs par défaut pour les gabarits de liens, la langue (lang), le fuseau horaire (timeZone) et le mode (mode) : un paramètre donné sur la balise ou dans params l’emporte ;
  • les sites autorisés à afficher vos widgets : demandé depuis une autre page, un widget répond 403 avec le code origin-not-allowed.

Sans identifiant, ou avec un identifiant inconnu, les widgets prennent les réglages iDalgo : thème iDalgo, direct actif, aucun site imposé.

Rend un widget dans un conteneur et renvoie son handle.

const widget = iDalgo.render("#classement", {
component: "RankingTable",
params: { season: "374703" },
lazy: false,
onLoad: () => console.log("Prêt"),
onError: (error) => console.error(error),
});
Option Type Description
component string Requis. Nom du widget
params Record<string, string> Paramètres du widget
client string Identifiant, prioritaire sur le réglage global
links object Gabarits de liens, ajoutés aux globaux
lazy boolean Remplace le chargement différé global
seo boolean Ajoute le JSON-LD dans la page (défaut true)
onLoad () => void Appelé une fois le widget affiché
onError (error) => void Appelé en cas d’erreur
onDestroy () => void Appelé à la suppression

Donnez au SDK l’adresse de vos pages joueur, équipe, match, résultats et classement : les widgets font de leurs noms des liens vers elles. Chaque gabarit contient {id}, remplacé par l’identifiant iDalgo de l’entité (le même que dans l’API et les paramètres des widgets).

iDalgo.configure({
links: {
person: "/joueurs/{id}", // un joueur, un entraîneur
team: "/equipes/{id}", // une équipe
contest: "/matchs/{id}", // un match
results: "/resultats/{id}", // les résultats d'une compétition ({id} : la saison)
standings: "/classements/{id}", // le classement d'une compétition ({id} : la saison)
},
});
Gabarit Ce qui devient un lien
person Feuille de match : joueurs du terrain, remplaçants, entraîneur, buteurs, auteurs des actions, joueurs clés. Fiche équipe : effectif et encadrement
team Feuille de match : équipes de l’en-tête, du classement et de la forme récente. Classement : bouton « Fiche complète » de la fiche dépliée d’une équipe. Fiche joueur : son club
contest Toute la carte d’un match (liste de matchs, fiches équipe et joueur), toute la carte d’une opposition du tableau de phase finale et le score des dernières confrontations de la feuille de match
standings Score Center : bouton « Tableau complet » du panneau Classement ; {id} reçoit l’identifiant de la saison. Sans gabarit, pas de bouton
results Liste de matchs : bouton « Tous les matchs » sous la liste ; {id} reçoit l’identifiant de la saison affichée

Un gabarit est un chemin de votre site (/joueurs/{id}) ou une URL https:// ; un gabarit sans {id}, ou d’un autre schéma, est ignoré. Sans gabarit pour un type, ses noms restent du texte.

Membre Description
id Identifiant unique du widget
status "idle", "loading", "ready" ou "error"
container Élément DOM du widget
update(params) Fusionne de nouveaux paramètres et rafraîchit le widget
refresh() Recharge le widget en ignorant le cache
destroy() Retire le widget, ses écouteurs, sa mise à jour en direct et son JSON-LD
on(event, handler) Écoute un événement de ce widget (off pour se désabonner)
widget.update({ split: "home" });
Méthode Description
iDalgo.scan(root?) Rend les balises [data-idalgo-component] pas encore rendues (après un ajout de HTML)
iDalgo.getWidget(id) Handle d’un widget par son identifiant
iDalgo.getWidgets() Tous les widgets actifs
iDalgo.preload(component, params?) Met un widget en cache sans l’afficher
iDalgo.clearCache() Vide le cache en mémoire
iDalgo.destroyAll() Retire tous les widgets de la page
iDalgo.on(event, handler) Écoute un événement de tous les widgets (off pour se désabonner)

Le scan automatique au chargement se désactive avec data-idalgo-auto-scan="false" sur la balise <script>.

Événement Contenu Quand
loading { widgetId } Début du chargement
load { widgetId, meta } Widget affiché
error { widgetId, error } Échec du chargement
destroy { widgetId } Widget retiré
update { widgetId, params } Paramètres modifiés
scan { count } Scan terminé
ready {} SDK initialisé, scan automatique fait

Les mêmes événements sont émis sur le conteneur du widget sous forme de CustomEvent préfixés idalgo:, qui remontent dans le DOM :

document.addEventListener("idalgo:load", (event) => console.log(event.detail));

Les callbacks onError reçoivent { code, message, status?, apiCode?, retryable, component?, widgetId? }, la même erreur que le champ error de l’événement error :

Champ Description
code Ce qui a échoué (tableau ci-dessous)
message Explication, pour vos journaux : celle du serveur pour une réponse en erreur
status Statut HTTP, pour HTTP_ERROR et COMPONENT_NOT_FOUND
apiCode code de la réponse du serveur : celui de l’API pour une erreur de données (team-not-found…), ou celui du serveur de rendu (voir Intégration côté serveur)
retryable true pour une erreur passagère (réseau, 5xx, 429) : une nouvelle tentative peut réussir
Code Cause retryable
NETWORK_ERROR Requête réseau échouée true
HTTP_ERROR Réponse HTTP en erreur Selon status
PARSE_ERROR Réponse illisible false
COMPONENT_NOT_FOUND Widget inconnu (apiCode component-not-found) false
CONTAINER_NOT_FOUND Conteneur introuvable (levée par render()) false

Pour HTTP_ERROR, status précise la cause :

status Cause Nouvelle tentative
400 Paramètre du widget manquant ou invalide Non
404 Entité inconnue (« Équipe 999 inconnue ») Non
429 Trop de requêtes Oui (retryCount)
500 Erreur inattendue du serveur de rendu Oui (retryCount)
502 Source de données indisponible ou réponse non conforme Oui (retryCount)

Le SDK réessaie seul une erreur passagère, retryCount fois, en doublant retryDelay à chaque tentative ; une erreur 4xx (sauf 429) remonte tout de suite, une nouvelle tentative échouerait à l’identique. Sans onError, il affiche « Impossible de charger le widget » dans le conteneur, avec un bouton « Réessayer » seulement si retryable vaut true.

iDalgo.render("#feuille", {
component: "MatchSheet",
params: { contest: "54732603" },
onError: (error) => {
// Match inconnu : rien à montrer, le bloc disparaît.
if (error.apiCode === "contest-not-found") document.querySelector("#feuille").remove();
},
});