@beworke/pixel 0.1.0-rc.7 → 0.1.0-rc.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +71 -56
  3. package/RELEASE_CANDIDATE.md +28 -62
  4. package/dist/Pixel-BnN86r4X.d.ts +797 -0
  5. package/dist/Pixel-BoUGqCbP.d.mts +797 -0
  6. package/dist/{StorageFactory-DeMaZ8wk.d.ts → StorageFactory-BfCArzMM.d.ts} +1 -1
  7. package/dist/{StorageFactory-Cq29vF32.d.mts → StorageFactory-C0prtNR7.d.mts} +1 -1
  8. package/dist/browser/index.cjs.js +3 -0
  9. package/dist/browser/index.cjs.js.map +1 -0
  10. package/dist/browser/index.d.mts +55 -0
  11. package/dist/browser/index.d.ts +55 -0
  12. package/dist/browser/index.esm.js +3 -0
  13. package/dist/browser/index.esm.js.map +1 -0
  14. package/dist/browser/pixel.global.js +4 -0
  15. package/dist/browser/pixel.global.js.map +1 -0
  16. package/dist/config/index.cjs.js +1 -1
  17. package/dist/config/index.cjs.js.map +1 -1
  18. package/dist/config/index.d.mts +15 -5
  19. package/dist/config/index.d.ts +15 -5
  20. package/dist/config/index.esm.js +1 -1
  21. package/dist/config/index.esm.js.map +1 -1
  22. package/dist/examples/html-script/RELEASE_CANDIDATE.md +6 -8
  23. package/dist/examples/html-script/add-payment-info/example-add-payment-info-card-autocomplete.html +40 -47
  24. package/dist/examples/html-script/add-payment-info/example-add-payment-info-card-disabled.html +40 -47
  25. package/dist/examples/html-script/add-payment-info/example-add-payment-info-card-fields.html +40 -47
  26. package/dist/examples/html-script/add-payment-info/example-add-payment-info-data-track.html +40 -47
  27. package/dist/examples/html-script/add-payment-info/example-add-payment-info-dedupe.html +40 -47
  28. package/dist/examples/html-script/add-payment-info/example-add-payment-info-manual.html +40 -47
  29. package/dist/examples/html-script/add-payment-info/example-add-payment-info-rules-card.html +40 -47
  30. package/dist/examples/html-script/add-payment-info/example-add-payment-info-security.html +40 -47
  31. package/dist/examples/html-script/add-to-cart/example-add-to-cart-attribute.html +40 -47
  32. package/dist/examples/html-script/add-to-cart/example-add-to-cart-auto.html +40 -47
  33. package/dist/examples/html-script/add-to-cart/example-add-to-cart-click.html +40 -47
  34. package/dist/examples/html-script/add-to-cart/example-add-to-cart-dedupe.html +40 -47
  35. package/dist/examples/html-script/add-to-cart/example-add-to-cart-link.html +40 -47
  36. package/dist/examples/html-script/add-to-cart/example-add-to-cart-manual.html +40 -47
  37. package/dist/examples/html-script/add-to-cart/example-add-to-cart-order-bump.html +40 -47
  38. package/dist/examples/html-script/add-to-cart/example-add-to-cart-text.html +40 -47
  39. package/dist/examples/html-script/behavior/example-behavior-engagement.html +4 -4
  40. package/dist/examples/html-script/behavior/example-behavior-heartbeat.html +4 -4
  41. package/dist/examples/html-script/behavior/example-behavior-runtime-intelligence.html +4 -4
  42. package/dist/examples/html-script/behavior/example-behavior-viewport.html +4 -4
  43. package/dist/examples/html-script/buygoods/example-buygoods-checkout.html +156 -0
  44. package/dist/examples/html-script/example-checkout-commerce.html +31 -30
  45. package/dist/examples/html-script/example-conversion.html +41 -48
  46. package/dist/examples/html-script/example-global-factory-classic.html +45 -0
  47. package/dist/examples/html-script/example-global-factory.html +40 -0
  48. package/dist/examples/html-script/example-integration.html +39 -45
  49. package/dist/examples/html-script/example-landing-commerce.html +3 -8
  50. package/dist/examples/html-script/example-runtime-diagnostics.html +4 -4
  51. package/dist/examples/html-script/example-transport.html +59 -57
  52. package/dist/examples/html-script/full-funnel/checkout.html +3 -1
  53. package/dist/examples/html-script/full-funnel/downsell.html +3 -1
  54. package/dist/examples/html-script/full-funnel/landing.html +3 -1
  55. package/dist/examples/html-script/full-funnel/thank-you.html +3 -1
  56. package/dist/examples/html-script/full-funnel/upsell.html +3 -1
  57. package/dist/examples/html-script/initiate-checkout/example-initiate-checkout-attribute.html +40 -47
  58. package/dist/examples/html-script/initiate-checkout/example-initiate-checkout-auto.html +40 -47
  59. package/dist/examples/html-script/initiate-checkout/example-initiate-checkout-click.html +40 -47
  60. package/dist/examples/html-script/initiate-checkout/example-initiate-checkout-manual.html +40 -47
  61. package/dist/examples/html-script/initiate-checkout/example-initiate-checkout-snapshot.html +40 -47
  62. package/dist/examples/html-script/initiate-checkout/example-initiate-checkout-submit.html +40 -47
  63. package/dist/examples/html-script/initiate-checkout/example-initiate-checkout-text.html +40 -47
  64. package/dist/examples/html-script/lead/example-lead-trigger-attribute.html +40 -47
  65. package/dist/examples/html-script/lead/example-lead-trigger-auto.html +40 -47
  66. package/dist/examples/html-script/lead/example-lead-trigger-click.html +40 -47
  67. package/dist/examples/html-script/release-candidate.html +31 -30
  68. package/dist/examples/html-script/remove-from-cart/README.md +3 -3
  69. package/dist/examples/html-script/remove-from-cart/example-remove-from-cart-attribute.html +40 -47
  70. package/dist/examples/html-script/remove-from-cart/example-remove-from-cart-css.html +40 -47
  71. package/dist/examples/html-script/remove-from-cart/example-remove-from-cart-dedupe.html +47 -54
  72. package/dist/examples/html-script/remove-from-cart/example-remove-from-cart-manual.html +40 -47
  73. package/dist/examples/html-script/remove-from-cart/example-remove-from-cart-multi.html +40 -47
  74. package/dist/examples/html-script/remove-from-cart/example-remove-from-cart-state.html +40 -47
  75. package/dist/examples/html-script/remove-from-cart/example-remove-from-cart-text.html +40 -47
  76. package/dist/examples/html-script/search/example-search-attribute.html +40 -47
  77. package/dist/examples/html-script/search/example-search-button-sync.html +40 -47
  78. package/dist/examples/html-script/search/example-search-dedupe.html +40 -47
  79. package/dist/examples/html-script/search/example-search-input.html +40 -47
  80. package/dist/examples/html-script/search/example-search-manual.html +40 -47
  81. package/dist/examples/html-script/search/example-search-submit.html +40 -47
  82. package/dist/examples/html-script/search/example-search-text.html +40 -47
  83. package/dist/examples/html-script/url-context/example-url-context-allowed-domains.html +4 -4
  84. package/dist/examples/html-script/url-context/example-url-context-landing.html +4 -4
  85. package/dist/examples/html-script/url-context/example-url-context-upsell.html +4 -4
  86. package/dist/examples/html-script/url-context/example-url-context.html +4 -4
  87. package/dist/examples/html-script/view-content/example-view-content-attribute.html +40 -47
  88. package/dist/examples/html-script/view-content/example-view-content-css.html +40 -47
  89. package/dist/examples/html-script/view-content/example-view-content-dedupe.html +40 -47
  90. package/dist/examples/html-script/view-content/example-view-content-empty.html +40 -47
  91. package/dist/examples/html-script/view-content/example-view-content-manual.html +40 -47
  92. package/dist/examples/html-script/view-content/example-view-content-product-card.html +40 -47
  93. package/dist/examples/html-script/view-content/example-view-content-text.html +40 -47
  94. package/dist/index.cjs.js +1 -1
  95. package/dist/index.cjs.js.map +1 -1
  96. package/dist/index.d.mts +8 -6
  97. package/dist/index.d.ts +8 -6
  98. package/dist/index.esm.js +1 -1
  99. package/dist/index.esm.js.map +1 -1
  100. package/dist/{pixel-2uL4LSyC.d.ts → pixel-DNGbAN5C.d.ts} +117 -98
  101. package/dist/{pixel-DMwpppf_.d.mts → pixel-_BSDpx4M.d.mts} +117 -98
  102. package/dist/pixel-default-config-BMYaqs7i.d.ts +21 -0
  103. package/dist/pixel-default-config-DLRya1tl.d.mts +21 -0
  104. package/dist/pixel-settings-D-t9zQb4.d.ts +40 -0
  105. package/dist/pixel-settings-DGxl0MVm.d.mts +40 -0
  106. package/dist/runtime/index.cjs.js +1 -1
  107. package/dist/runtime/index.cjs.js.map +1 -1
  108. package/dist/runtime/index.d.mts +4 -4
  109. package/dist/runtime/index.d.ts +4 -4
  110. package/dist/runtime/index.esm.js +1 -1
  111. package/dist/runtime/index.esm.js.map +1 -1
  112. package/dist/services/index.cjs.js +1 -1
  113. package/dist/services/index.cjs.js.map +1 -1
  114. package/dist/services/index.d.mts +4 -4
  115. package/dist/services/index.d.ts +4 -4
  116. package/dist/services/index.esm.js +1 -1
  117. package/dist/services/index.esm.js.map +1 -1
  118. package/dist/{types-6HF3UlsL.d.mts → types-B-Nzagpk.d.mts} +2 -2
  119. package/dist/{types-CgrabttM.d.mts → types-D0KVsgzs.d.mts} +1 -1
  120. package/dist/{types-fFcQ1apy.d.ts → types-D3kJ9bfT.d.ts} +1 -1
  121. package/dist/{types-BqUEoZo0.d.ts → types-Dfi9C49l.d.ts} +2 -2
  122. package/dist/v2/global.global.js +1 -1
  123. package/dist/v2/global.global.js.map +1 -1
  124. package/dist/v2/index.cjs.js +1 -1
  125. package/dist/v2/index.cjs.js.map +1 -1
  126. package/dist/v2/index.d.mts +21 -787
  127. package/dist/v2/index.d.ts +21 -787
  128. package/dist/v2/index.esm.js +1 -1
  129. package/dist/v2/index.esm.js.map +1 -1
  130. package/docs/public/README.md +7 -4
  131. package/docs/public/api/exports.md +12 -8
  132. package/docs/public/api/pixel.md +27 -6
  133. package/docs/public/configuration/commerce.md +2 -2
  134. package/docs/public/configuration/modules.md +11 -14
  135. package/docs/public/configuration/overview.md +45 -26
  136. package/docs/public/configuration/transport.md +127 -0
  137. package/docs/public/events/catalog.md +3 -1
  138. package/docs/public/getting-started/installation.md +14 -12
  139. package/docs/public/getting-started/quick-start.md +95 -30
  140. package/docs/public/getting-started/react-nextjs.md +57 -34
  141. package/docs/public/getting-started/script-tag.md +55 -32
  142. package/docs/public/guides/funnel-checkout.md +1 -1
  143. package/docs/public/guides/funnel-landing.md +9 -7
  144. package/docs/public/limitations.md +5 -4
  145. package/docs/public/privacy/limitations.md +6 -6
  146. package/docs/public/release-candidate/validation.md +4 -4
  147. package/docs/public/troubleshooting.md +7 -6
  148. package/package.json +8 -3
  149. package/dist/pixel-default-config-BDPUVHse.d.ts +0 -5
  150. package/dist/pixel-default-config-C5uLt52W.d.mts +0 -5
@@ -1,49 +1,110 @@
1
1
  # Quick start
2
2
 
3
- ## 1. Config mínima
3
+ Há três níveis de uso. O input público é `PixelSettings`: somente
4
+ `identity.pixelId` é obrigatório. O SDK mescla o restante com
5
+ `DEFAULT_PIXEL_CONFIG` dentro do construtor de `Pixel`.
4
6
 
5
- ```typescript
6
- import { Pixel, DEFAULT_PIXEL_CONFIG } from '@beworke/pixel';
7
+ - objetos são mesclados profundamente;
8
+ - arrays substituem os defaults (não concatenam);
9
+ - `transport.sender` substitui a variante inteira (`test` / `internal` / `external`);
10
+ - `undefined` significa “usar o default”;
11
+ - `false`, `0` e `''` são valores válidos e não apagam o default por acidente.
7
12
 
8
- const pixel = new Pixel({
9
- ...DEFAULT_PIXEL_CONFIG,
10
- identity: {
11
- pixelId: 'pix_YOUR_ID',
12
- },
13
- transport: {
14
- ...DEFAULT_PIXEL_CONFIG.transport,
15
- apiEndpoint: 'https://your-pixel-api.example.com',
16
- },
17
- storage: {
18
- ...DEFAULT_PIXEL_CONFIG.storage,
19
- persistence: {
20
- visitor: 'localStorage',
21
- session: 'sessionStorage',
22
- attribution: 'localStorage',
13
+ Use `PixelSettings` no input e `PixelConfig` quando precisar da configuração
14
+ já resolvida.
15
+
16
+ ## 1. HTML — `Pixel(settings)`
17
+
18
+ O bundle global **não** auto-inicializa. Top-level `await` exige `type="module"`.
19
+
20
+ ```html
21
+ <script src="https://unpkg.com/@beworke/pixel@rc/dist/browser/pixel.global.js"></script>
22
+ <script type="module">
23
+ const pixel = await Pixel({
24
+ identity: {
25
+ pixelId: 'pix_YOUR_ID',
23
26
  },
24
- },
27
+ });
28
+ pixel.lead({ email: 'user@example.com' });
29
+ </script>
30
+ ```
31
+
32
+ Overrides opcionais:
33
+
34
+ ```js
35
+ await Pixel({
36
+ identity: { pixelId: 'pix_YOUR_ID' },
37
+ app: { environment: 'development', debug: true },
38
+ });
39
+ ```
40
+
41
+ Isso equivale a `bootstrapPixel(settings)`: uma instância por `window`.
42
+
43
+ ## 2. NPM — `createPixel`
44
+
45
+ Instâncias **independentes** (não é singleton).
46
+
47
+ ```typescript
48
+ import { createPixel } from '@beworke/pixel';
49
+
50
+ const pixel = await createPixel({
51
+ identity: { pixelId: 'pix_YOUR_ID' },
25
52
  });
26
53
  ```
27
54
 
28
- ## 2. Inicializar
55
+ A classe pública continua válida:
29
56
 
30
57
  ```typescript
58
+ import { Pixel } from '@beworke/pixel';
59
+
60
+ const pixel = new Pixel({
61
+ identity: { pixelId: 'pix_YOUR_ID' },
62
+ });
31
63
  await pixel.init();
32
64
  ```
33
65
 
34
- `init()` é assíncrono. Aguarde antes de disparar conversões manuais se depender de sessão/visitor prontos.
66
+ Um `PixelConfig` completo continua sendo aceito.
67
+
68
+ ## 3. Browser avançado — `bootstrapPixel`
69
+
70
+ ```typescript
71
+ import { bootstrapPixel } from '@beworke/pixel/browser';
72
+
73
+ const pixel = await bootstrapPixel(
74
+ {
75
+ identity: { pixelId: 'pix_YOUR_ID' },
76
+ },
77
+ { waitForConsent: () => true }
78
+ );
79
+ ```
80
+
81
+ - Sem `force`, a primeira chamada é dona da instância naquela `window`.
82
+ - Para trocar a configuração: `destroyBootstrappedPixel()` ou `{ force: true }`.
83
+ - Chamadas concorrentes compartilham a configuração da primeira chamada.
84
+
85
+ ## 4. Eventos automáticos
35
86
 
36
- ## 3. Eventos automáticos
87
+ Após `Pixel(settings)` / `createPixel` / `bootstrapPixel`:
37
88
 
38
- Com `modules.core.enabled` e `modules.behavior.enabled` (defaults), após `init()`:
89
+ - `PAGE_VIEW` (core) é emitido por default
90
+ - métodos manuais de conversão (`lead`, `purchase`, …) estão habilitados
91
+ - AutoTrack escuta `[data-track="<evento>"]` no clique (`view_content`, `add_to_cart`, `remove_from_cart`, `initiate_checkout`, `add_payment_info`, `purchase`, `lead`, `search`)
92
+ - `view_content` dispara no **hover** e quando o elemento **fica visível**; `data-trigger="hover"` (ou `click` / `visible`) restringe o modo — sem o atributo, valem os 3
93
+ - enrichment de commerce está on: informe o catálogo para completar name/price/currency
94
+ - rules de DOM extras, behavior avançado e destinos Meta/Google/TikTok
95
+ continuam **desabilitados** até você habilitá-los
39
96
 
40
- - `PAGE_VIEW` (core)
41
- - Sinais de behavior (scroll, cliques, heartbeat, etc.) conforme config
97
+ ```html
98
+ <button data-track="add_to_cart" data-product-id="sku-1">Comprar</button>
99
+ <div data-track="view_content" data-product-id="sku-1">Produto (click + hover + visible)</div>
100
+ <div data-track="view_content" data-product-id="sku-1" data-trigger="hover">Só hover</div>
101
+ <button data-track="lead" data-email="user@example.com">Quero saber mais</button>
102
+ ```
42
103
 
43
- ## 4. Conversão manual
104
+ ## 5. Conversão manual
44
105
 
45
106
  ```typescript
46
- await pixel.purchase({
107
+ pixel.purchase({
47
108
  transactionId: 'order_123',
48
109
  value: 197,
49
110
  currency: 'BRL',
@@ -52,15 +113,15 @@ await pixel.purchase({
52
113
 
53
114
  Outros métodos: `lead`, `addToCart`, `removeFromCart`, `initiateCheckout`, `addPaymentInfo`, `viewContent`, `search`.
54
115
 
55
- ## 5. Encerrar (SPA / navegação)
116
+ ## 6. Encerrar (SPA / navegação)
56
117
 
57
118
  ```typescript
58
119
  await pixel.destroy();
59
120
  ```
60
121
 
61
- Em React/Next, chame `destroy()` no cleanup do `useEffect`.
122
+ Com `bootstrapPixel` / `window.Pixel`, prefira `destroyBootstrappedPixel()` / `Pixel.destroy()`. Em React, o `PixelProvider` é dono do lifecycle.
62
123
 
63
- ## 6. Debug (somente desenvolvimento)
124
+ ## 7. Debug (somente desenvolvimento)
64
125
 
65
126
  ```typescript
66
127
  if (pixel.isInitialized()) {
@@ -70,8 +131,12 @@ if (pixel.isInitialized()) {
70
131
 
71
132
  `getDebugSnapshot()` é público; não use `getDebugServices()` (interno).
72
133
 
134
+ `DEFAULT_PIXEL_CONFIG` permanece disponível para inspeção e configuração avançada — não é necessário espalhá-lo numa integração comum.
135
+
73
136
  ## Próximos passos
74
137
 
75
138
  - [Configuração](../configuration/overview.md)
139
+ - [Transport](../configuration/transport.md)
76
140
  - [Catálogo de eventos](../events/catalog.md)
77
141
  - [Funil checkout](../guides/funnel-checkout.md)
142
+ - [React / Next.js](./react-nextjs.md)
@@ -1,55 +1,78 @@
1
1
  # React e Next.js (App Router)
2
2
 
3
- O SDK não exporta hooks React. O padrão recomendado é um hook **local** no app.
3
+ O pacote recomendado é [`@beworke/pixel-react`](../../../../pixel-react/README.md): `PixelProvider` + `usePixel` sobre `bootstrapPixel`.
4
4
 
5
- ## Hook local (`usePixel`)
5
+ Esta camada **não** duplica `lead` / `purchase` no Context. O hook devolve a instância real de `Pixel`. O playground Next Bemony continua na integração de domínio e **não** usa este pacote genérico.
6
6
 
7
- Referência: `apps/playground-next/lib/use-pixel.ts`
7
+ ## Instalação
8
8
 
9
- ```typescript
10
- 'use client';
11
-
12
- import { Pixel } from '@beworke/pixel';
13
- import { useEffect, useRef, useState } from 'react';
14
- import { createPixelConfig } from './pixel-config';
9
+ ```bash
10
+ pnpm add @beworke/pixel-react@rc @beworke/pixel@rc
11
+ ```
15
12
 
16
- export function usePixel() {
17
- const pixelRef = useRef<Pixel | null>(null);
18
- const [ready, setReady] = useState(false);
13
+ ## Provider
19
14
 
20
- useEffect(() => {
21
- const pixel = new Pixel(createPixelConfig());
22
- pixelRef.current = pixel;
15
+ ```tsx
16
+ 'use client';
23
17
 
24
- pixel.init().then(() => setReady(true));
18
+ import { PixelProvider } from '@beworke/pixel-react';
19
+ import type { PixelSettings } from '@beworke/pixel';
25
20
 
26
- return () => {
27
- void pixel.destroy();
28
- pixelRef.current = null;
29
- setReady(false);
30
- };
31
- }, []);
21
+ const settings = {
22
+ identity: { pixelId: 'pix_YOUR_ID' },
23
+ } satisfies PixelSettings;
32
24
 
33
- return { pixel: pixelRef, ready };
25
+ export function Providers({ children }: { children: React.ReactNode }) {
26
+ return <PixelProvider settings={settings}>{children}</PixelProvider>;
34
27
  }
35
28
  ```
36
29
 
37
- ## Config por página/funil
30
+ `settings` é `PixelSettings`. Somente `identity.pixelId` é obrigatório; o Core resolve o restante.
31
+
32
+ ## Hook
38
33
 
39
- Centralize em `createPixelConfig()` (`apps/playground-next/lib/pixel-config.ts`):
34
+ ```tsx
35
+ 'use client';
40
36
 
41
- - `identity.funnelId`, `funnelStepId`, `pageId` por etapa do funil
42
- - `commerce.catalog` para produtos da oferta
43
- - `storage.persistence` com `sessionStorage` para sessão sobreviver a reloads
37
+ import { usePixel } from '@beworke/pixel-react';
38
+
39
+ export function LeadButton() {
40
+ const { pixel, ready, status, error } = usePixel();
41
+
42
+ if (status === 'initializing') {
43
+ return <span>Inicializando...</span>;
44
+ }
45
+
46
+ if (error) {
47
+ return <span>Falha ao inicializar o Pixel.</span>;
48
+ }
49
+
50
+ return (
51
+ <button
52
+ disabled={!ready}
53
+ onClick={() => {
54
+ pixel?.lead({ email: 'user@example.com' });
55
+ }}
56
+ >
57
+ Enviar lead
58
+ </button>
59
+ );
60
+ }
61
+ ```
44
62
 
45
63
  ## SSR
46
64
 
47
- - Instancie `Pixel` apenas no cliente (`'use client'`).
48
- - Não chame `init()` no servidor.
49
- - `destroy()` no unmount evita listeners duplicados.
65
+ - `PixelProvider` é Client Component (`'use client'`).
66
+ - O `layout.tsx` pode permanecer Server Component.
67
+ - Importar o pacote não acessa `window`.
68
+ - Bootstrap só no `useEffect` do cliente.
69
+
70
+ ## Strict Mode e múltiplos Providers
71
+
72
+ Vários Providers na mesma `window` compartilham a instância. Strict Mode (mount → cleanup → mount) não destrói a instância reutilizada; o último unmount real destrói o bootstrap.
50
73
 
51
- ## Checkout
74
+ `settings` é capturado na montagem. Reinit dinâmico está fora do MVP.
52
75
 
53
- `apps/playground-next/app/checkout/page.tsx` demonstra `initiateCheckout`, `addPaymentInfo`, `purchase` com catálogo commerce.
76
+ ## Alternativa: instância local
54
77
 
55
- Guia: [Funil checkout](../guides/funnel-checkout.md).
78
+ Apps que precisam de uma instância isolada (sem singleton da `window`) podem continuar usando `createPixel` ou `new Pixel(settings)` num `useEffect` próprio. Nesse caso o app é dono de `destroy()`.
@@ -2,11 +2,15 @@
2
2
 
3
3
  ## Build
4
4
 
5
- O subpath `@beworke/pixel/global` expõe um bundle IIFE que define `window.PixelV2`.
5
+ O subpath `@beworke/pixel/global` expõe um bundle IIFE autossuficiente.
6
6
 
7
- Após `npm run build`, o artefato está em `dist/global/` (nome conforme `tsup` / `package.json`).
7
+ Após o build, o artefato recomendado é `dist/browser/pixel.global.js`. O bundle legado `dist/v2/global.global.js` (`window.PixelV2`) permanece para compatibilidade.
8
8
 
9
- ## HTML mínimo
9
+ Carregar o script **apenas registra** a API. Não há auto-init, leitura de `document.currentScript` nem atributos `data-*`.
10
+
11
+ ## HTML mínimo (`type="module"`)
12
+
13
+ Top-level `await` exige `type="module"`.
10
14
 
11
15
  ```html
12
16
  <!DOCTYPE html>
@@ -14,44 +18,63 @@ Após `npm run build`, o artefato está em `dist/global/` (nome conforme `tsup`
14
18
  <head>
15
19
  <meta charset="UTF-8" />
16
20
  <title>Pixel — script tag</title>
21
+ <script src="https://unpkg.com/@beworke/pixel@rc/dist/browser/pixel.global.js"></script>
17
22
  </head>
18
23
  <body>
19
- <script src="../../dist/global/pixel.global.js"></script>
20
- <script>
21
- (async function () {
22
- const { Pixel, DEFAULT_PIXEL_CONFIG } = window.PixelV2;
23
-
24
- const pixel = new Pixel({
25
- ...DEFAULT_PIXEL_CONFIG,
26
- app: { ...DEFAULT_PIXEL_CONFIG.app, debug: true },
27
- identity: { pixelId: 'pix_YOUR_ID' },
28
- transport: {
29
- ...DEFAULT_PIXEL_CONFIG.transport,
30
- apiEndpoint: 'https://your-pixel-api.example.com',
31
- },
32
- storage: {
33
- ...DEFAULT_PIXEL_CONFIG.storage,
34
- persistence: {
35
- visitor: 'localStorage',
36
- session: 'sessionStorage',
37
- attribution: 'localStorage',
38
- },
39
- },
40
- });
41
-
42
- await pixel.init();
43
- // Conversões manuais quando necessário
44
- })();
24
+ <button id="lead-button" type="button">Enviar lead</button>
25
+ <script type="module">
26
+ const pixel = await Pixel({
27
+ identity: { pixelId: 'pix_YOUR_ID' },
28
+ });
29
+
30
+ document.getElementById('lead-button').addEventListener('click', () => {
31
+ pixel.lead({ email: 'user@example.com' });
32
+ });
45
33
  </script>
46
34
  </body>
47
35
  </html>
48
36
  ```
49
37
 
50
- ## Exemplo público
38
+ ## Script clássico (sem top-level await)
39
+
40
+ ```html
41
+ <script>
42
+ Pixel({
43
+ identity: {
44
+ pixelId: 'pix_YOUR_ID',
45
+ },
46
+ })
47
+ .then(function (pixel) {
48
+ pixel.lead({ email: 'user@example.com' });
49
+ })
50
+ .catch(function (error) {
51
+ console.error(error);
52
+ });
53
+ </script>
54
+ ```
55
+
56
+ ## API global
57
+
58
+ ```js
59
+ await Pixel(settings); // bootstrap (uma instância por window)
60
+ await Pixel.create(settings); // instância independente
61
+ await Pixel.bootstrap(settings, { force: true, waitForConsent });
62
+ Pixel.getInstance();
63
+ Pixel.getPending();
64
+ await Pixel.destroy();
65
+ new Pixel.Client(settings); // classe; o construtor resolve PixelSettings
66
+ Pixel.DEFAULT_PIXEL_CONFIG; // inspeção / configuração avançada
67
+ ```
68
+
69
+ `window.PixelV2` continua como compatibilidade / baixo nível (`Pixel`, `DEFAULT_PIXEL_CONFIG`, `resolveStorageAdapterName`, `createPixel`, `bootstrap`, `getInstance`, `destroy`).
70
+
71
+ ## Exemplos no monorepo
51
72
 
52
- Veja `apps/playground-html/public/html/landing.html`.
73
+ - `apps/playground-html/example-global-factory.html`
74
+ - `apps/playground-html/example-global-factory-classic.html`
53
75
 
54
76
  ## Limitações
55
77
 
56
78
  - TypeScript/IDE não inferem tipos no global — use JSDoc ou migre para npm ESM em apps maiores.
57
- - Mesmas regras de privacidade: a aplicação controla **quando** chamar `init()` após consentimento.
79
+ - A aplicação controla **quando** chamar `Pixel(settings)` após consentimento.
80
+ - Não declare conformidade LGPD/GDPR/CCPA apenas por usar este bundle.
@@ -6,7 +6,7 @@ Rastrear início de checkout, carrinho, pagamento e compra.
6
6
 
7
7
  ## Config
8
8
 
9
- - `commerce.enabled: true` + catálogo de produtos
9
+ - catálogo de produtos em `commerce.catalog` (enrichment já está on por default)
10
10
  - `identity.checkoutId`, `funnelStepId`
11
11
  - Transport API habilitado
12
12
 
@@ -7,6 +7,13 @@ Medir visita, comportamento na página e leads antes do checkout.
7
7
  ## Config recomendada
8
8
 
9
9
  ```typescript
10
+ import { DEFAULT_TRANSPORT_CONFIG } from '@beworke/pixel/config';
11
+
12
+ transport: {
13
+ ...DEFAULT_TRANSPORT_CONFIG,
14
+ enabled: true,
15
+ sender: { mode: 'internal' },
16
+ },
10
17
  modules: {
11
18
  ...DEFAULT_PIXEL_CONFIG.modules,
12
19
  core: { ...DEFAULT_PIXEL_CONFIG.modules.core, enabled: true },
@@ -20,11 +27,6 @@ modules: {
20
27
  exitIntent: { enabled: true },
21
28
  },
22
29
  },
23
- transport: {
24
- ...DEFAULT_PIXEL_CONFIG.modules.transport,
25
- enabled: true,
26
- sender: { mode: 'api' },
27
- },
28
30
  },
29
31
  ```
30
32
 
@@ -52,7 +54,7 @@ Opcional: `modules.conversion.auto` + detector `lead` com seletores do formulár
52
54
 
53
55
  ## QA
54
56
 
55
- - [ ] `pixelId` e `apiEndpoint` corretos
57
+ - [ ] `pixelId` e sender (`internal`/`external`) corretos
56
58
  - [ ] Persistência `sessionStorage` para sessão
57
59
  - [ ] Um único `init()` por aba
58
60
  - [ ] `getDebugSnapshot()` mostra transport enviando (dev)
@@ -61,7 +63,7 @@ Opcional: `modules.conversion.auto` + detector `lead` com seletores do formulár
61
63
 
62
64
  | Problema | Causa | Solução |
63
65
  |----------|-------|---------|
64
- | Sem eventos na API | `transport.enabled: false` ou `sender.mode: 'mock'` | Habilitar transport + mode `api` |
66
+ | Sem eventos na API | `transport.enabled: false` ou sender `test` | Habilitar Transport + sender `internal`/`external` |
65
67
  | Sessão zera no reload | Sem `storage.persistence.session` | Configurar `sessionStorage` |
66
68
  | Duplo `PAGE_VIEW` | Dois `init()` | Singleton / cleanup `destroy()` |
67
69
 
@@ -1,12 +1,13 @@
1
1
  # Limitações conhecidas do RC
2
2
 
3
- Versão: `0.1.0-rc.5` · Etapas 1–20 concluídas.
3
+ A versão publicada está em `package.json`. Este documento descreve limitações do produto, não um número de RC.
4
4
 
5
5
  ## Produto
6
6
 
7
7
  | Limitação | Detalhe |
8
8
  |-----------|---------|
9
- | Consent / CMP | Incompleto — Etapa 25 |
9
+ | Consent / CMP | Incompleto — a aplicação controla quando inicializar; `waitForConsent` é um gate opcional no bootstrap |
10
+ | Auto-init | O bundle base **não** auto-inicializa ao ser carregado |
10
11
  | Commerce Lifecycle | Etapa 21 não iniciada neste RC documental |
11
12
  | Eventos upsell/downsell | Sem tipos dedicados; use `VIEW_CONTENT` + `PURCHASE` |
12
13
  | `./diagnostics` | Não é export do pacote |
@@ -17,8 +18,8 @@ Versão: `0.1.0-rc.5` · Etapas 1–20 concluídas.
17
18
  | Limitação | Detalhe |
18
19
  |-----------|---------|
19
20
  | `modules.behavior.enabled` | `false` por default — habilitar explicitamente |
20
- | `modules.transport.sender.mode` | `'mock'` por default — trocar para `'api'` |
21
- | Sessão em memory | Sem `storage.persistence.session` |
21
+ | `modules.conversion.auto` | Auto detectors e rules continuam off; só a API manual vem ligada |
22
+ | Sessão | Persistência default em `sessionStorage` |
22
23
 
23
24
  ## Distribuição
24
25
 
@@ -1,14 +1,15 @@
1
1
  # Privacidade e consentimento (RC)
2
2
 
3
- ## Estado do RC `0.1.0-rc.5`
3
+ ## Estado atual
4
4
 
5
5
  - **Não há Consent Gate / CMP completo** integrado ao SDK.
6
+ - `bootstrapPixel(..., { waitForConsent })` e `PixelProvider` permitem abortar **antes** de criar a instância.
6
7
  - `modules.core.consent` e `modules.privacy.consent` existem na config mas **defaults desligados**.
7
- - Etapa **25 — Privacy/Consent** ainda não concluída.
8
+ - O chamador controla o momento da inicialização. Este RC **não** declara conformidade LGPD/GDPR/CCPA.
8
9
 
9
10
  ## Responsabilidade da aplicação
10
11
 
11
- 1. **Quando inicializar** — só chame `pixel.init()` após obter consentimento do usuário, se exigido pela sua política.
12
+ 1. **Quando inicializar** — só chame `Pixel(settings)`, `createPixel()` ou `pixel.init()` após obter consentimento do usuário, se exigido pela sua política.
12
13
  2. **Banner / CMP** — implemente no app (React, HTML, tag manager). O Pixel não substitui ferramenta de consentimento.
13
14
  3. **PII** — `modules.privacy.pii` (hash email/phone) off por default; você controla o que envia em `lead()` etc.
14
15
 
@@ -21,11 +22,10 @@
21
22
 
22
23
  ```typescript
23
24
  async function onUserConsentGranted() {
24
- const pixel = new Pixel(createConfig());
25
- await pixel.init();
25
+ const pixel = await createPixel(createConfig());
26
26
  }
27
27
 
28
- // Antes do consentimento: não instanciar ou não chamar init()
28
+ // Antes do consentimento: não chamar Pixel(settings) / createPixel() / init()
29
29
  ```
30
30
 
31
31
  ## Próximos passos (roadmap)
@@ -22,19 +22,19 @@ Não use `pnpm --filter @beworke/pixel pack` como fluxo principal.
22
22
 
23
23
  ## Tarball
24
24
 
25
- Nome esperado: `artifacts/beworke-pixel-0.1.0-rc.6.tgz`
25
+ O nome do tarball segue a versão de `package.json` (veja `artifacts/latest-package.json`).
26
26
  Manifesto: `artifacts/latest-package.json` (caminho relativo portátil).
27
27
 
28
28
  Instalação em projeto limpo:
29
29
 
30
30
  ```bash
31
- npm install /caminho/para/artifacts/beworke-pixel-0.1.0-rc.6.tgz
31
+ npm install /caminho/para/artifacts/beworke-pixel-<versão>.tgz
32
32
  ```
33
33
 
34
34
  ## Checklist rápido
35
35
 
36
- - [ ] Exports `.`, `./global`, `./v2`, `./config`, `./events`, `./services`, `./runtime`, `./logger`
37
- - [ ] `window.PixelV2` no build global
36
+ - [ ] Exports `.`, `./browser`, `./global`, `./v2`, `./config`, `./events`, `./services`, `./runtime`, `./logger`
37
+ - [ ] `window.Pixel` (factory) e `window.PixelV2` (compat) no build global
38
38
  - [ ] Exemplos públicos sem `@internal` / sem import de `src/`
39
39
  - [ ] Links em `packages/pixel/docs/public/` válidos
40
40
  - [ ] README aponta para `packages/pixel/docs/public/`
@@ -2,11 +2,12 @@
2
2
 
3
3
  ## Nenhum evento chega na API
4
4
 
5
- 1. Confirme `transport.apiEndpoint` preenchido
6
- 2. `modules.transport.enabled: true`
7
- 3. `modules.transport.sender.mode: 'api'` (não `mock`)
8
- 4. `identity.pixelId` definido
9
- 5. DevTools → Network: requisições ao endpoint
5
+ 1. Confirme `transport.enabled: true`
6
+ 2. Use `transport.sender.mode: 'internal'` ou `'external'` (`'test'` não acessa a rede)
7
+ 3. Em `internal`, confira o `baseUrl` opcional; sem ele, vale o endpoint público padrão
8
+ 4. Em `external`, confira `endpoints.event` e a política de batch
9
+ 5. Confirme `identity.pixelId`
10
+ 6. DevTools → Network: requisições ao endpoint
10
11
 
11
12
  ## `init()` falha ou trava
12
13
 
@@ -51,5 +52,5 @@ npm run validate:rc-package
51
52
  ## Links úteis
52
53
 
53
54
  - [Configuração](./configuration/overview.md)
54
- - [Transport module](./configuration/modules.md)
55
+ - [Transport](./configuration/transport.md)
55
56
  - [Validação RC](./release-candidate/validation.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@beworke/pixel",
3
- "version": "0.1.0-rc.7",
3
+ "version": "0.1.0-rc.9",
4
4
  "description": "Pixel v2 — SDK de analytics e conversão para API própria e destinos browser",
5
5
  "main": "./dist/index.cjs.js",
6
6
  "module": "./dist/index.esm.js",
@@ -11,8 +11,13 @@
11
11
  "import": "./dist/index.esm.js",
12
12
  "require": "./dist/index.cjs.js"
13
13
  },
14
+ "./browser": {
15
+ "types": "./dist/browser/index.d.ts",
16
+ "import": "./dist/browser/index.esm.js",
17
+ "require": "./dist/browser/index.cjs.js"
18
+ },
14
19
  "./global": {
15
- "default": "./dist/v2/global.global.js"
20
+ "default": "./dist/browser/pixel.global.js"
16
21
  },
17
22
  "./config": {
18
23
  "types": "./dist/config/index.d.ts",
@@ -61,7 +66,7 @@
61
66
  "validate:rc-package": "node ../../scripts/validate-rc-package.mjs",
62
67
  "validate:public-docs": "node ../../scripts/validate-public-docs.mjs",
63
68
  "validate:public-examples": "node ../../scripts/validate-public-examples.mjs",
64
- "publish:rc": "npm publish --tag rc --tag latest",
69
+ "publish:rc": "pnpm publish --access public --tag rc --no-git-checks && node -e \"require('child_process').execSync('npm dist-tag add @beworke/pixel@'+require('./package.json').version+' latest',{stdio:'inherit'})\"",
65
70
  "test:integration": "vitest run src/integration",
66
71
  "test:transport": "vitest run src/transport",
67
72
  "test:full-funnel": "vitest run src/modules/core/url-context src/integration/stage-15b-module-matrix.test.ts",
@@ -1,5 +0,0 @@
1
- import { P as PixelConfig } from './pixel-2uL4LSyC.js';
2
-
3
- declare const DEFAULT_PIXEL_CONFIG: PixelConfig;
4
-
5
- export { DEFAULT_PIXEL_CONFIG as D };
@@ -1,5 +0,0 @@
1
- import { P as PixelConfig } from './pixel-DMwpppf_.mjs';
2
-
3
- declare const DEFAULT_PIXEL_CONFIG: PixelConfig;
4
-
5
- export { DEFAULT_PIXEL_CONFIG as D };