Banners.js

La bibliothèque publique banners.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

banners.js exécute l’enchère et affiche la bannière. Chargez analytics.js avec elle, afin que les renders, les impressions et les clics sur la bannière soient signalés. Installez les deux avec npm :

npm install @topsort/banners @topsort/analytics.js

Importez ensuite @topsort/banners après avoir configuré analytics.js comme décrit sur sa page, avec window.TS défini avant le chargement de l’une ou l’autre bibliothèque. Ou chargez-les avec des balises <script>, en définissant d’abord window.TS :

<script>
  // Global configuration for Topsort
  window.TS = {
    token: "TSE_XXXXXXXXXXXX", // Replace with your Topsort API key
  };
</script>
<script src="https://unpkg.com/@topsort/analytics.js@latest/dist/ts.iife.js"></script>
<script type="module" src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"></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>
  // Set API key for auctions and events
  window.TS = {
    token: "TSE_XXXXXXXXXXXX",
  };
  // Custom behavior can be configured for each site.
  window.TS_BANNERS = {
    // handle the destination link
    getLink(banner) {
      return `https://example.com/${banner.id}`;
    },
    // handle loading/fetching state
    getLoadingElement() {
      const el = document.createElement("div");
      el.innerText = "Loading...";
      return el;
    },
    // handle errors
    getErrorElement() {
      const el = document.createElement("div");
      el.innerText = "Error loading banner";
      return el;
    },
  };
</script>
<script src="https://unpkg.com/@topsort/analytics.js@latest/dist/ts.iife.js"></script>
<script type="module" src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"></script>
<body>
  <topsort-banner width="600" height="400" id="<your 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	L’ID de catégorie de la page actuelle
category-ids (optional)	string	IDs de catégorie séparés par des virgules ; l’article doit correspondre à tous
category-disjunctions (optional)	string	IDs de catégorie séparés par des virgules ; l’article doit correspondre à l’un d’eux
search-query (optional)	string	La requête de recherche de la page actuelle
location (optional)	string	La localisation pour le géociblage
new-tab (optional)	boolean	Ouvre le lien de la bannière dans un nouvel onglet. Par défaut : false

Définissez un seul des attributs category-id, category-ids et category-disjunctions. Si plusieurs sont définis, seul le premier dans cet ordre est utilisé.

Comportements de bannière

Ces fonctions de window.TS_BANNERS personnalisent l’affichage des bannières. Toutes sont facultatives.

Nom	Retour	Description
getLink(banner)	string	URL de destination de la bannière
getLoadingElement()	HTMLElement	Un élément personnalisé à afficher pendant le chargement de la bannière
getErrorElement(error)	HTMLElement	Un élément personnalisé à afficher lorsqu’une erreur se produit
getNoWinnersElement()	HTMLElement	Un élément personnalisé à afficher lorsque l’enchère ne renvoie aucune bannière
getBannerElement(banner)	HTMLElement	Un élément personnalisé à afficher à la place de la bannière par défaut

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 (renders, impressions et clics).

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 les renders, les impressions et les clics.
asset	[{ url: string }]	Un tableau d’urls pointant vers les ressources de la bannière.
isFallback	boolean (optional)	`true` pour une bannière de secours. Les bannières de secours ne sont pas suivies.

Aperçu

Plateforme Publicitaire

Serveur Publicitaire

Toppie

Intégrations Avancées

API

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

Installation

Utilisation

Attributs de bannière

Comportements de bannière

Interface de bannière