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.
Version du SDK
Section intitulée « Version du SDK »<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.
iDalgo.configure(options)
Section intitulée « iDalgo.configure(options) »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.
Identifiant client
Section intitulée « Identifiant client »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 dansparamsl’emporte ; - les sites autorisés à afficher vos widgets : demandé depuis une autre page, un widget répond
403avec le codeorigin-not-allowed.
Sans identifiant, ou avec un identifiant inconnu, les widgets prennent les réglages iDalgo : thème iDalgo, direct actif, aucun site imposé.
iDalgo.render(container, options)
Section intitulée « iDalgo.render(container, options) »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 |
Liens vers vos pages
Section intitulée « Liens vers vos pages »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.
Le handle d’un widget
Section intitulée « Le handle d’un widget »| 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" });Autres méthodes
Section intitulée « Autres méthodes »| 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énements
Section intitulée « Événements »| É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(); },});