Banners.js

La biblioteca pública banners.js de Topsort permite a los marketplaces mostrar anuncios de banner a través de una integración de bajo código. Al usar una simple etiqueta HTML, el marketplace puede conectarse al servidor de anuncios de Topsort y renderizar banners de campañas activas sin integraciones complejas.

Instalación

banners.js ejecuta la subasta y muestra el banner. Carga analytics.js junto con ella, para que se reporten los renders, impresiones y clics del banner. Instala ambas con npm:

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

Luego importa @topsort/banners después de configurar analytics.js como se describe en su página, con window.TS definido antes de que se cargue cualquiera de las dos bibliotecas. O cárgalas con etiquetas <script>, definiendo window.TS primero:

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

Uso

Este ejemplo muestra la configuración mínima requerida para hacerlo. La integración funciona con HTML y Javascript estándar, haciéndola compatible con la mayoría de los stacks frontend. Para probarlo, solo necesitas agregar tu Marketplace API Key y el banner slot id, configurado en la campaña.

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

Estos son los atributos disponibles para el componente <topsort-banner>. Sirven como entrada para la solicitud de subasta, para obtener los ganadores correctos para ese contexto.

Nombre	Tipo	Descripción
width	number	Ancho del banner
height	number	Alto del banner
id	string	El ID del slot para este banner, configurado en la campaña
category-id (opcional)	string	El ID de categoría de la página actual
category-ids (opcional)	string	IDs de categoría separados por comas; el artículo debe coincidir con todos ellos
category-disjunctions (opcional)	string	IDs de categoría separados por comas; el artículo debe coincidir con alguno de ellos
search-query (opcional)	string	La consulta de búsqueda de la página actual
location (opcional)	string	La ubicación para la geosegmentación
new-tab (opcional)	boolean	Abre el enlace del banner en una pestaña nueva. Por defecto es false

Define solo uno de category-id, category-ids y category-disjunctions. Si defines más de uno, solo se usa el primero en ese orden. Estas funciones en window.TS_BANNERS personalizan cómo se muestran los banners. Todas son opcionales.

Nombre	Retorna	Descripción
getLink(banner)	string	URL de destino del banner
getLoadingElement()	HTMLElement	Un elemento personalizado que se muestra mientras el banner está cargando
getErrorElement(error)	HTMLElement	Un elemento personalizado que se muestra cuando ocurre un error
getNoWinnersElement()	HTMLElement	Un elemento personalizado que se muestra cuando la subasta no devuelve banner
getBannerElement(banner)	HTMLElement	Un elemento personalizado que se muestra en lugar del banner predeterminado

La interfaz del banner es la estructura de un objeto banner. Cada banner contiene metadatos sobre la campaña, y el resolvedBidId, el parámetro necesario para rastrear las interacciones del usuario (renders, impresiones y clics).

Nombre	Tipo	Descripción
type	”product” \| “vendor” \| “brand” \| “url”	El tipo de la entidad ganadora, representada por el banner, configurado en la campaña.
id	string	El ID de la entidad ganadora. Si la entidad es de tipo URL, esta es la URL.
resolvedBidId	string	El ID de oferta correspondiente de la entidad ganadora, necesario para rastrear renders, impresiones y clics.
asset	[{ url: string }]	Un array de urls que enlazan a los assets del banner.
isFallback	boolean (opcional)	`true` para un banner de respaldo (fallback). Los banners de respaldo no se rastrean.

Resumen

Plataforma de Anuncios

Servidor de Anuncios

Toppie

Integraciones Avanzadas

API

Instalación

Uso

Atributos del Banner

Comportamientos del Banner

Interfaz del Banner

​Instalación

​Uso

​Atributos del Banner

​Comportamientos del Banner

​Interfaz del Banner

Instalación

Uso

Atributos del Banner

Comportamientos del Banner

Interfaz del Banner