Banners.js

A biblioteca pública banner.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

Você pode instalar a biblioteca usando npm ou yarn, ou carregar o SDK diretamente no seu arquivo HTML incluindo uma tag <script>:

<script
  async
  type="module"
  src="https://unpkg.com/@topsort/banners@latest/dist/banners.mjs"
></script>
<script>
  // Configuração global para o Topsort
  window.TS = {
    token: "TSE_XXXXXXXXXXXX", // Substitua pela sua chave de API do Topsort
  };
</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
  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>
  // Define a chave de API para leilões e eventos
  window.TS = {
    token: "TSE_XXXXXXXXXXXX",
  };
  // Comportamento personalizado pode ser configurado para cada site.
  window.TS_BANNERS = {
    // manipular o link de destino
    getLink(banner) {
      return `https://example.com/${banner.id}`;
    },
    // manipular estado de carregamento/busca
    getLoadingElement() {
      const el = document.createElement("div");
      el.innerText = "Carregando...";
      return el;
    },
    // manipular erros
    getErrorElement() {
      const el = document.createElement("div");
      el.innerText = "Erro ao carregar banner";
      return el;
    },
  };
</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	Categoria contextual para segmentação
Search-query (opcional)	string	Palavra-chave contextual para segmentação

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
getLink(banner)	string	URL de destino do banner, configurado na campanha.
getLoadingElement	HTMLElement	Um elemento personalizado a ser exibido quando o banner está carregando.
getErrorElement	HTMLElement	Um elemento personalizado a ser exibido quando ocorre um erro.

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 (cliques e impressões).

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 a interação do usuário (cliques, impressões) com o anúncio.
asset	[{ url: string }]	Um array de urls vinculando aos ativos 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

Instalação

Uso

Atributos do Banner

Comportamentos do Banner

Interface do Banner