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.
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.
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 |
Insertion dans la page
Section intitulée « Insertion dans la page »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.htmlsans le modifier ni l’échapper. Sans JavaScript, le widget affiche son premier rendu complet. - CSS :
dom.cssdans un<style>(voir CSS). - JSON-LD : sérialisez
seoen JSON en remplaçant<par<, pour qu’un nom contenant</script>ne ferme pas la balise. - JavaScript : chargez chaque URL de
dom.jstelle quelle, en module (type="module"), et annoncez celles dedom.preloaden<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.cssdans 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.stylesen<link rel="stylesheet">, aveccss=linkdans 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.