Documentation Index
Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
Use this file to discover all available pages before exploring further.
La bibliothèque publique banner.js de Topsort permet aux marketplaces d’afficher des bannières publicitaires grâce à une intégration low-code. En utilisant une simple balise HTML, la marketplace peut se connecter au serveur publicitaire de Topsort et afficher des bannières provenant de campagnes actives sans intégrations complexes.
Installation
Vous pouvez installer la bibliothèque en utilisant npm ou yarn, ou charger le SDK directement dans votre fichier HTML en incluant une balise <script> :
<script
async
type="module"
src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"
></script>
<script>
// Configuration globale pour Topsort
window.TS = {
token: "TSE_XXXXXXXXXXXX", // Remplacez par votre clé API Topsort
};
</script>
Utilisation
Cet exemple montre la configuration minimale requise. L’intégration fonctionne avec HTML et Javascript standard, la rendant compatible avec la plupart des stacks frontend.
Pour le tester, vous avez simplement besoin d’ajouter votre clé API Marketplace et l’ID du slot de bannière, configuré dans la campagne.
<script
async
type="module"
src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"
></script>
<script
async
type="module"
src="https://unpkg.com/@topsort/analytics.js/dist/ts.js"
></script>
<script>
// Définir la clé API pour les enchères et les événements
window.TS = {
token: "TSE_XXXXXXXXXXXX",
};
// Un comportement personnalisé peut être configuré pour chaque site.
window.TS_BANNERS = {
// gérer le lien de destination
getLink(banner) {
return `https://example.com/${banner.id}`;
},
// gérer l'état de chargement
getLoadingElement() {
const el = document.createElement("div");
el.innerText = "Chargement...";
return el;
},
// gérer les erreurs
getErrorElement() {
const el = document.createElement("div");
el.innerText = "Erreur de chargement de la bannière";
return el;
},
};
</script>
<body>
<topsort-banner width="600" height="400" id="<votre slot id>"></topsort-banner>
</body>
Attributs de bannière
Voici les attributs disponibles pour le composant <topsort-banner>. Ils servent d’entrée à la requête d’enchères, pour récupérer les bons gagnants pour ce contexte.
| Nom | Type | Description |
|---|
| width | number | Largeur de la bannière |
| height | number | Hauteur de la bannière |
| id | string | L’ID du slot pour cette bannière, configuré dans la campagne |
| Category-id (optional) | string | Catégorie contextuelle pour le ciblage |
| Search-query (optional) | string | Mot-clé contextuel pour le ciblage |
Comportements de bannière
Voici les attributs disponibles pour le composant <topsort-banner>. Ils servent d’entrée à la requête d’enchères, pour récupérer les bons gagnants pour ce contexte.
| Nom | Type | Description |
|---|
| getLink(banner) | string | URL de destination de la bannière, configurée dans la campagne. |
| getLoadingElement | HTMLElement | Un élément personnalisé à afficher lors du chargement de la bannière. |
| getErrorElement | HTMLElement | Un élément personnalisé à afficher lorsqu’une erreur se produit. |
Interface de bannière
L’interface de bannière est la structure d’un objet bannière. Chaque bannière contient des métadonnées sur la campagne, et le resolvedBidId, le paramètre nécessaire pour suivre les interactions utilisateur (clics et impressions).
| Nom | Type | Description |
|---|
| type | ”product” | “vendor” | “brand” | “url” | Le type de l’entité gagnante, représentée par la bannière, configuré dans la campagne. |
| id | string | L’ID de l’entité gagnante. Si l’entité est de type URL, c’est l’URL. |
| resolvedBidId | string | L’ID d’enchère correspondant de l’entité gagnante, nécessaire pour suivre l’interaction utilisateur (clics, impressions) avec la publicité. |
| asset | [{ url: string }] | Un tableau d’urls pointant vers les ressources de la bannière. |
