Banners.js

Die öffentliche banners.js-Bibliothek von Topsort ermöglicht es Marktplätzen, Werbebanner durch eine Low-Code-Integration anzuzeigen. Mit einem einfachen HTML-Tag kann sich der Marktplatz mit dem Werbeserver von Topsort verbinden und Banner aus aktiven Kampagnen ohne komplexe Integrationen anzeigen.

Installation

banners.js führt die Auktion durch und zeigt das Banner an. Laden Sie zusätzlich analytics.js, damit Renders, Impressionen und Klicks auf dem Banner gemeldet werden. Installieren Sie beide mit npm:

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

Importieren Sie anschließend @topsort/banners, nachdem Sie analytics.js wie auf der zugehörigen Seite beschrieben eingerichtet haben. Dabei muss window.TS gesetzt sein, bevor eine der beiden Bibliotheken geladen wird. Alternativ können Sie beide mit <script>-Tags laden. Setzen Sie dabei zuerst 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>

Verwendung

Dieses Beispiel zeigt die minimal erforderliche Konfiguration. Die Integration funktioniert mit Standard-HTML und Javascript und ist daher mit den meisten Frontend-Stacks kompatibel. Um es zu testen, müssen Sie einfach Ihren Marketplace-API-Schlüssel und die Banner-Slot-ID hinzufügen, die in der Kampagne konfiguriert ist.

<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>

Hier sind die verfügbaren Attribute für die Komponente <topsort-banner>. Sie dienen als Eingabe für die Auktionsanfrage, um die richtigen Gewinner für diesen Kontext abzurufen.

Name	Typ	Beschreibung
width	number	Breite des Banners
height	number	Höhe des Banners
id	string	Die Slot-ID für dieses Banner, in der Kampagne konfiguriert
category-id (optional)	string	Die Kategorie-ID der aktuellen Seite
category-ids (optional)	string	Durch Kommas getrennte Kategorie-IDs; das Element muss allen davon entsprechen
category-disjunctions (optional)	string	Durch Kommas getrennte Kategorie-IDs; das Element muss mindestens einer davon entsprechen
search-query (optional)	string	Die Suchanfrage der aktuellen Seite
location (optional)	string	Der Standort für das Geotargeting
new-tab (optional)	boolean	Öffnet den Link des Banners in einem neuen Tab. Standardwert ist false

Setzen Sie nur eines der Attribute category-id, category-ids und category-disjunctions. Wenn mehrere gesetzt sind, wird nur das erste in dieser Reihenfolge verwendet. Diese Funktionen auf window.TS_BANNERS passen an, wie Banner angezeigt werden. Alle sind optional.

Name	Rückgabe	Beschreibung
getLink(banner)	string	Ziel-URL des Banners
getLoadingElement()	HTMLElement	Ein benutzerdefiniertes Element, das während des Ladens des Banners angezeigt wird
getErrorElement(error)	HTMLElement	Ein benutzerdefiniertes Element, das angezeigt wird, wenn ein Fehler auftritt
getNoWinnersElement()	HTMLElement	Ein benutzerdefiniertes Element, das angezeigt wird, wenn die Auktion kein Banner zurückgibt
getBannerElement(banner)	HTMLElement	Ein benutzerdefiniertes Element, das anstelle des Standardbanners angezeigt wird

Die Banner-Schnittstelle ist die Struktur eines Banner-Objekts. Jedes Banner enthält Metadaten über die Kampagne und die resolvedBidId, den Parameter, der zum Verfolgen von Benutzerinteraktionen (Renders, Impressionen und Klicks) erforderlich ist.

Name	Typ	Beschreibung
type	”product” \| “vendor” \| “brand” \| “url”	Der Typ der gewinnenden Entität, dargestellt durch das Banner, in der Kampagne konfiguriert.
id	string	Die ID der gewinnenden Entität. Wenn die Entität vom Typ URL ist, ist dies die URL.
resolvedBidId	string	Die entsprechende Gebots-ID der gewinnenden Entität, erforderlich zum Verfolgen von Renders, Impressionen und Klicks.
asset	[{ url: string }]	Ein Array von URLs, die auf die Banner-Ressourcen verweisen.
isFallback	boolean (optional)	`true` für ein Fallback-Banner. Fallback-Banner werden nicht verfolgt.

Übersicht

Werbeplattform

Werbeserver

Toppie

Erweiterte Integrationen

API

Installation

Verwendung

Banner-Attribute

Banner-Verhalten

Banner-Schnittstelle

​Installation

​Verwendung

​Banner-Attribute

​Banner-Verhalten

​Banner-Schnittstelle

Installation

Verwendung

Banner-Attribute

Banner-Verhalten

Banner-Schnittstelle