bannerx-client

SDK React do BannerX — a rede de troca de banners entre mini apps do World App.

Cada mini app que mostra banners de outras apps ganha 1 crédito por cada exposição válida de 60 segundos; cada crédito ganho paga a exibição do teu próprio banner na rede. 1 visualização = 1 crédito.

Instalação

npm install bannerx-client

Requer React 18+.

Antes de começar

1. Abre o dashboard do BannerX e liga o teu World ID.
2. Regista a tua mini app (nome, link de destino) e faz upload do banner (1500×120 recomendado, PNG/JPEG/WEBP até 1 MB).
3. Aguarda a aprovação — recebes créditos de boas-vindas quando a app é aprovada.
4. Copia o App ID da tua app (botão de copiar na lista "As minhas apps").

Uso

O componente não faz autenticação: a tua app é responsável pelo login e passa um id estável do utilizador em viewerId (por exemplo a wallet address do MiniKit walletAuth, que é igual em todas as mini apps, ou um nullifier hash). Sem viewerId o banner não é mostrado.

import { BannerX } from "bannerx-client";

export default function App() {
  const user = useMyAuth(); // o teu fluxo de login (ex.: MiniKit walletAuth)

  return (
    <>
      {/* o resto da tua app */}
      {user && (
        <BannerX
          appId="O_TEU_APP_ID"          // da lista "As minhas apps"
          viewerId={user.walletAddress} // id estável do utilizador
        />
      )}
    </>
  );
}

Exemplo com MiniKit (dentro do World App):

const { finalPayload } = await MiniKit.commandsAsync.walletAuth({ nonce });
if (finalPayload.status === "success") {
  setViewerId(finalPayload.address.toLowerCase());
}

Props

| Prop | Tipo | Obrigatória | Default | Descrição | | ------------ | --------------------------------- | ----------- | ---------------------- | --------- | | appId | string | sim | — | O App ID da tua app registada no BannerX (é a tua app que ganha os créditos) | | viewerId | string | sim | — | Id estável do utilizador autenticado na tua app | | apiUrl | string | não | https://banner-x.nonnux.com | URL base da API do BannerX | | position | "top" \| "bottom" | não | "bottom" | Posição da barra de 60px (fixed) | | className | string | não | — | Classe CSS extra no container | | style | CSSProperties | não | — | Estilos extra no container | | onExposure | (exposureId: string) => void | não | — | Disparado quando uma exposição de 60s é creditada | | onError | (error: string) => void | não | — | Disparado em erros de fetch/report |

Como funciona

• O componente renderiza uma barra fixa de 60px (topo ou fundo) com um spacer para não tapar o conteúdo da tua app.
• Busca um banner à rede (nunca o teu próprio — appId é excluído) e conta 60 segundos visíveis (pausa quando a tab/app está em background).
• Aos 60s regista a exposição: a app do banner paga 1 crédito e a tua app recebe 1 crédito. Depois roda para o banner seguinte.
• Se a rede não tiver banners com créditos, mostra o banner do BannerX (fallback) — sem créditos envolvidos.

Anti-spam

O servidor impõe um intervalo mínimo de 60s por utilizador+banner e valida que o appId anfitrião está registado e ativo. Exposições inválidas não geram créditos.

Licença

MIT