Aller au contenu

Intégration côté serveur

Le SDK récupère chaque widget dans le navigateur. Votre serveur peut aussi le récupérer lui-même et l’insérer dans la page qu’il génère : le widget est alors présent dans le HTML dès la première réponse, sans attendre de JavaScript.

Fenêtre de terminal
curl "https://delivery.idalgo.live/render/MatchSheet?contest=54732603"

/render/<Widget> prend le nom du widget (MatchSheet, ScoreCenter, Bracket…) et ses paramètres en query string, les mêmes que les attributs data-idalgo-param-* (voir la galerie). S’y ajoutent, facultatifs :

Paramètre Rôle
client Votre identifiant (voir Identifiant client), idalgo par défaut
css link : les styles seulement en URL (dom.styles), sans dom.css ; voir CSS
link.person, link.team, link.contest, link.results, link.standings Gabarits de liens vers vos pages (voir Liens), encodés dans l’URL

Votre serveur envoie votre clé secrète en Authorization: Bearer idl_sk_…, et votre page porte votre clé publique (data-idalgo-key) pour les relectures du direct : voir Votre clé. Un paramètre que le widget ne connaît pas est ignoré. Un appel de serveur à serveur, sans en-tête Origin ni Referer, n’est pas soumis au contrôle des sites autorisés de votre client.

Fenêtre de terminal
curl -G "https://delivery.idalgo.live/render/MatchSheet" \
--data-urlencode "contest=54732603" \
--data-urlencode "link.team=/equipes/{id}"
{
"meta": {
"component": "MatchSheet",
"version": "…",
"cacheControl": "public, max-age=300"
},
"seo": { "@context": "https://schema.org", "@type": "SportsEvent", "…": "…" },
"dom": {
"html": "<div data-component=\"MatchSheet\" data-idalgo-mode=\"light\" style=\"…\">…</div><script type=\"application/json\" data-props=\"MatchSheet\">…</script>",
"css": "@font-face { … } …",
"styles": [
"https://delivery.idalgo.live/assets/idalgo-base-….css",
"https://delivery.idalgo.live/assets/….css"
],
"js": ["https://delivery.idalgo.live/assets/…"],
"preload": ["https://delivery.idalgo.live/assets/svelte-runtime-….js", "…"]
}
}
Champ Contenu
meta.component Composant rendu. Il peut porter un autre nom que le widget (StandingsTable pour RankingTable) : ne vous en servez pas pour identifier le widget
meta.version Version du rendu
meta.cacheControl Durée de validité du fragment, la même que l’en-tête Cache-Control de la réponse
seo Données structurées JSON-LD du widget
dom.html Le fragment HTML, thème appliqué. Il se termine par un <script type="application/json"> qui porte les données du widget pour son JavaScript : gardez le fragment intact
dom.css La feuille de style complète du widget : police (URL absolues), couleurs du design system, styles du widget. Absent avec css=link
dom.styles Les mêmes styles en URL absolues de feuilles : la feuille commune à tous les widgets d’abord, puis celles du widget
dom.js URL absolues des modules JavaScript du widget (onglets, « Voir plus », direct) : un module par widget aujourd’hui
dom.preload URL absolues des modules qu’importent ceux de dom.js, à précharger en même temps qu’eux

Dans votre gabarit, avec {{ … }} pour les champs de la réponse :

<head>
<style>
{{ dom.css }}
</style>
<script type="application/ld+json">
{{ seo, sérialisé en JSON }}
</script>
</head>
<body>
<div class="feuille-de-match">{{ dom.html }}</div>
{{ pour chaque URL de dom.preload, sans doublon : }}
<link rel="modulepreload" href="{{ url }}" />
<script type="module" src="{{ dom.js[0] }}"></script>
</body>
  • HTML : insérez dom.html sans le modifier ni l’échapper. Sans JavaScript, le widget affiche son premier rendu complet.
  • CSS : dom.css dans un <style> (voir CSS).
  • JSON-LD : sérialisez seo en JSON en remplaçant < par <, pour qu’un nom contenant </script> ne ferme pas la balise.
  • JavaScript : chargez chaque URL de dom.js telle quelle, en module (type="module"), et annoncez celles de dom.preload en <link rel="modulepreload"> : le navigateur les télécharge en même temps au lieu de les découvrir l’une après l’autre. Le module rend le widget interactif et lance ses mises à jour en direct, lues dans le navigateur sur l’API iDalgo.

Les styles d’un widget ne s’appliquent qu’à l’intérieur de son <div data-component> : ils ne changent rien au reste de votre page.

Deux façons de les insérer :

  • dom.css dans un <style> (par défaut) : tout tient dans la réponse. Deux widgets du même nom partagent la même feuille ; des widgets différents répètent la partie commune (police, couleurs).
  • dom.styles en <link rel="stylesheet">, avec css=link dans la requête : une balise par URL, chaque URL une seule fois dans la page. La feuille commune n’est chargée qu’une fois quel que soit le nombre de widgets, et le navigateur garde chaque feuille en cache : une URL ne change jamais de contenu. C’est ce que fait le SDK, et le plus léger dès deux widgets dans la page.
<head>
{{ pour chaque URL de dom.styles, sans doublon : }}
<link rel="stylesheet" href="{{ url }}" />
</head>

Un module prend en charge le premier widget de son type dans la page. Pour plusieurs widgets du même type, ou une page qui charge aussi le SDK, appelez sa fonction hydrateIn sur le conteneur de chacun ; déclarez alors window.__IDALGO_SDK__ = true avant les modules, qui ne s’activent plus d’eux-mêmes (le SDK le déclare aussi) :

<script>
window.__IDALGO_SDK__ = true;
</script>
<script type="module">
import { hydrateIn } from "{{ dom.js[0] }}";
for (const container of document.querySelectorAll(".feuille-de-match")) hydrateIn(container);
</script>

Gardez la réponse au plus le temps indiqué par son Cache-Control (max-age, en secondes), pour une même URL complète : la durée suit la donnée la plus fraîche du widget (plus courte le jour d’un match). Un widget en direct se met à jour seul dans le navigateur : son fragment n’a pas besoin d’être redemandé pendant le match.

Une réponse en erreur ne porte pas de Cache-Control : ne la gardez pas.

Une erreur répond en JSON { "error": "…", "code": "…" } :

{ "error": "Équipe 999 inconnue", "code": "team-not-found" }

Branchez votre traitement sur code, stable, jamais sur error. Pour une erreur de données, c’est le code de l’API, relayé tel quel ; le serveur de rendu ajoute les siens :

Statut code Cause Réessayer
400 Celui de l’API (invalid-request) Paramètre du widget manquant ou invalide ; le message reprend celui de l’API (« contest: … ») Non
404 Celui de l’API (team-not-found, contest-not-found…) Entité inconnue (« Contest 999 inconnu… ») : le message reprend celui de l’API Non
403 origin-not-allowed Page hors des sites autorisés pour ce client (en-tête Origin, à défaut Referer) Non
404 component-not-found Widget inconnu Non
502 data-source-unavailable Source de données indisponible ou réponse non conforme ; message « Source de données indisponible » Oui
500 internal-error Erreur inattendue du serveur de rendu Oui

Le message est fait pour vos journaux, pas pour vos lecteurs : en cas d’erreur, n’affichez pas le widget ou affichez votre propre message. La section « Erreurs et états » de chaque widget détaille ses cas.