BilSports Widgets Documentation

O BilSports Widget é um Web Component — um elemento HTML personalizado que funciona em qualquer site sem dependências externas. Você cola um único <script> e adiciona quantos <bilsports-widget> quiser. Os dados carregam automaticamente, isolados dentro de um Shadow DOM.

Instalação rápida

<!-- Cole este script UMA VEZ no seu HTML -->
<script src="https://www.bilsports.com/widgets/v1.js" async defer></script>

<!-- Adicione widgets onde quiser -->
<bilsports-widget
  data-type="live-scores"
  data-api-key="pub_xxxxxxxxxxxx">
</bilsports-widget>

Ligas populares

Cada widget autentica suas requisições com uma chave pública passada via data-api-key. Chaves públicas começam com pub_ e são seguras para expor em HTML do lado do cliente.

Como obter uma chave

1. Acesse bilsports.com/dashboard/widgets
2. Copie sua chave pública (pub_...)
3. Use-a no atributo data-api-key de qualquer elemento <bilsports-widget>

CORS e origem das requisições

O widget faz requisições diretamente para api.bilsports.com no browser do visitante. O CORS está configurado para aceitar qualquer origem — não é necessário adicionar seu domínio a uma allowlist.

Chave de demonstração

data-api-key="pub_demo_bilsports_2026"

Cada visita a uma página com widgets dispara uma ou mais requisições à API para buscar dados. Sem um sistema de cache, sua cota diária pode ser esgotada muito rapidamente.

Por que o cache importa

Imagine uma página que dispara 1 requisição por visitante e recebe 80 visitas por minuto. Isso representa 115 200 requisições por dia — sem cache.

Com um cache de apenas 60 segundos, a primeira visita dispara a requisição e a resposta fica armazenada. As 79 visitas seguintes dentro desse intervalo são servidas diretamente do cache — reduzindo o consumo de 115 200 para 1 440 requisições por dia.

Como o BilSports implementa o cache

O BilSports já faz isso automaticamente. A infraestrutura mantém um cache Redis entre os widgets e a fonte de dados — todos os visitantes do seu site compartilham o mesmo resultado em cache. Você não precisa implementar nada: basta usar o widget.

Intervalos de cache por widget

Se o widget não exibe as informações esperadas, é possível ativar o atributo data-show-errors="true" para exibir as mensagens de erro diretamente no widget e no console do navegador.

Ativando erros visíveis

<bilsports-widget
  data-type="live-scores"
  data-api-key="pub_xxxxxxxxxxxx"
  data-show-errors="true">
</bilsports-widget>

Causas comuns (lista não exaustiva)

Content Security Policy (CSP)

/* Cabeçalho Content-Security-Policy */
script-src  'self' https://www.bilsports.com;
connect-src 'self' https://api.bilsports.com;
img-src     'self' https://api.bilsports.com data:;

Os widgets servem logos e fotos pelo nosso próprio proxy em api.bilsports.com/media. Essas chamadas não contam para a sua cota diária — são gratuitas — porém estão sujeitas a limites de requisições por segundo e por minuto.

Para alto volume ou latência crítica, recomendamos configurar sua própria CDN com um Pull Zone apontando para api.bilsports.com/media. Uma vez feito isso, informe a URL base com o atributo data-logo-url.

Usando sua própria CDN (opcional)

<bilsports-widget
  data-type="standings"
  data-api-key="pub_xxxxxxxxxxxx"
  data-league="39"
  data-logo-url="https://cdn.seusite.com">
</bilsports-widget>

Quando data-logo-url está definido, o widget substitui automaticamente api.bilsports.com/media pelo valor informado, mantendo o caminho dos arquivos (ex.: /football/teams/39.png).

Formatos e tamanhos

Fallback

Quando um logo não está disponível, o widget exibe automaticamente um ícone genérico com as iniciais do nome. Não é necessário nenhum tratamento especial no seu código.

Aviso legal

Referência rápida de todos os tipos de widget. Clique num card disponível para ir à documentação completa.

Disponíveis