Banners.js

A biblioteca pública banners.js do Topsort permite que marketplaces exibam banners através de uma integração low-code. Usando uma tag HTML simples, o marketplace pode se conectar ao servidor de anúncios do Topsort e renderizar banners de campanhas ativas sem integrações complexas.

Instalação

O banners.js executa o leilão e exibe o banner. Carregue o analytics.js junto com ele, para que os renders, impressões e cliques no banner sejam reportados. Instale ambos com npm:

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

Em seguida, importe @topsort/banners depois de configurar o analytics.js conforme descrito na página dele, com window.TS definido antes que qualquer uma das bibliotecas seja carregada. Ou carregue-os com tags <script>, definindo window.TS primeiro:

<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 exemplo mostra uma configuração mínima necessária para fazer isso. A integração funciona com HTML e Javascript padrão, tornando-a compatível com a maioria dos stacks frontend. Para testá-la, você só precisa adicionar sua Chave de API do Marketplace e o id do slot do banner, configurado na campanha.

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

Estes são os atributos disponíveis para o componente <topsort-banner>. Eles servem como entrada para a solicitação de leilão, para buscar os vencedores certos para aquele contexto.

Nome	Tipo	Descrição
width	number	Largura do banner
height	number	Altura do banner
id	string	O ID do slot para este banner, configurado na campanha
category-id (opcional)	string	O ID da categoria da página atual
category-ids (opcional)	string	IDs de categoria separados por vírgula; o item deve corresponder a todos eles
category-disjunctions (opcional)	string	IDs de categoria separados por vírgula; o item deve corresponder a qualquer um deles
search-query (opcional)	string	A consulta de busca da página atual
location (opcional)	string	A localização para segmentação geográfica
new-tab (opcional)	boolean	Abre o link do banner em uma nova aba. O padrão é false

Defina apenas um entre category-id, category-ids e category-disjunctions. Se mais de um for definido, apenas o primeiro nessa ordem será usado. Estas funções em window.TS_BANNERS personalizam como os banners são exibidos. Todas elas são opcionais.

Nome	Retorno	Descrição
getLink(banner)	string	URL de destino do banner
getLoadingElement()	HTMLElement	Um elemento personalizado a ser exibido enquanto o banner está carregando
getErrorElement(error)	HTMLElement	Um elemento personalizado a ser exibido quando ocorre um erro
getNoWinnersElement()	HTMLElement	Um elemento personalizado a ser exibido quando o leilão não retorna nenhum banner
getBannerElement(banner)	HTMLElement	Um elemento personalizado a ser exibido no lugar do banner padrão

A interface do banner é a estrutura de um objeto banner. Cada banner contém metadados sobre a campanha e o resolvedBidId, o parâmetro necessário para rastrear interações do usuário (renders, impressões e cliques).

Nome	Tipo	Descrição
type	”product” \| “vendor” \| “brand” \| “url”	O tipo da entidade vencedora, representada pelo banner, configurado na campanha.
id	string	O ID da entidade vencedora. Se a entidade for do tipo URL, este é o URL.
resolvedBidId	string	O ID de lance correspondente da entidade vencedora, necessário para rastrear renders, impressões e cliques.
asset	[{ url: string }]	Um array de urls vinculando aos ativos do banner.
isFallback	boolean (opcional)	`true` para um banner de fallback. Banners de fallback não são rastreados.

Visão Geral

Plataforma de Anúncios

Servidor de Anúncios

Toppie

Integrações Avançadas

API

Instalação

Uso

Atributos do Banner

Comportamentos do Banner

Interface do Banner

​Instalação

​Uso

​Atributos do Banner

​Comportamentos do Banner

​Interface do Banner

Instalação

Uso

Atributos do Banner

Comportamentos do Banner

Interface do Banner