Banners.js - Topsort Documentation

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.

​Installation

​Utilisation

​Attributs de bannière

​Comportements de bannière

​Interface de bannière

Installation

Utilisation

Attributs de bannière

Comportements de bannière

Interface de bannière