Pixel v2 (@beworke/pixel)

SDK de analytics e conversão para web — implemente funis (landing, checkout, upsell, thank-you) em React, Next.js, SPA ou HTML puro sem conhecer a arquitetura interna.

A versão publicada está em package.json. Instale a tag @rc para receber a release candidate atual.

Instalação (npm — sem token)

Pacote público. Qualquer dev instala sem login no npm:

npm install @beworke/pixel@rc

Importante: npm install @beworke/pixel sem tag usa latest. Use @rc até alinhar tags.

Documentação pública

O npm não hospeda arquivos .md como site (URLs tipo npmjs.com/.../installation.md não existem).

| Onde ler | Link | |----------|------| | GitHub (recomendado no browser) | docs/public/README.md | | Após npm install | node_modules/@beworke/pixel/docs/public/ |

| Guia | GitHub | |------|--------| | Instalação | getting-started/installation.md | | Quick start | getting-started/quick-start.md | | API Pixel | api/pixel.md | | Eventos | events/catalog.md | | Configuração | configuration/overview.md | | Funis | guides/funnel-full.md | | Privacidade (RC) | privacy/limitations.md | | Limitações | limitations.md |

Repositório: https://github.com/beworke-apps/Pixel-Global

Três níveis de uso

HTML simples (script tag)

Carregar o bundle apenas registra window.Pixel. Nada é inicializado até Pixel(settings) resolver. Top-level await exige type="module" (ou um IIFE/then).

<script src="https://unpkg.com/@beworke/pixel@rc/dist/browser/pixel.global.js"></script>
<script type="module">
  const pixel = await Pixel({
    identity: { pixelId: 'pix_YOUR_ID' },
  });
  pixel.lead({ email: '[email protected]' });
</script>

Pixel(settings) usa o bootstrap (uma instância por window). window.PixelV2 permanece como compatibilidade / API de baixo nível.

NPM com factory

createPixel cria instâncias independentes (não é singleton).

import { createPixel } from '@beworke/pixel';

const pixel = await createPixel({
  identity: { pixelId: 'pix_YOUR_ID' },
});

pixel.lead({ email: '[email protected]' });

A classe continua disponível:

import { Pixel } from '@beworke/pixel';

const pixel = new Pixel({
  identity: { pixelId: 'pix_YOUR_ID' },
});
await pixel.init();

Browser avançado

bootstrapPixel gerencia uma instância por window. Para trocar a configuração, destrua explicitamente ou use force. Chamadas concorrentes compartilham a configuração da primeira chamada.

import { bootstrapPixel } from '@beworke/pixel/browser';

const pixel = await bootstrapPixel(
  {
    identity: { pixelId: 'pix_YOUR_ID' },
  },
  {
    waitForConsent: () => window.consentGranted === true,
  }
);

React: use @beworke/pixel-react (PixelProvider / usePixel).

Métodos públicos

| Método | Descrição | |--------|-----------| | init() / destroy() / isInitialized() | Ciclo de vida | | getDebugSnapshot() | Snapshot read-only (dev/QA) | | purchase, lead, addToCart, removeFromCart | Conversão | | initiateCheckout, addPaymentInfo, viewContent, search | Conversão |

Detalhes: api/pixel.md

Métodos internos de playground (@internal) não são API pública.

Limitações do RC

• O bundle não auto-inicializa; a aplicação controla quando chamar Pixel(settings) / init()
• Consent gate opcional no bootstrap — a aplicação decide quando há consentimento suficiente
• Não declarar GDPR/LGPD/CCPA compliant com este RC
• Sem eventos dedicados upsell/downsell — use VIEW_CONTENT + PURCHASE

Lista: limitations.md

Contribuidores

Arquitetura interna: PLAN_PIXEL/ARCHITECTURE.md · Playgrounds: apps/playground-html/ no monorepo.