@core / pixels

1.0.1 ▾

1.0.1

verificadoMIT

GitHub

Medição de conversões com consentimento: GA4, Meta Pixel + Conversions API, TikTok Pixel + Events API, sem duplicados

Código7 arquivosContexto~702 tokensanálise aprovada

~702 tokens→ src/lib/pixels/AGENTS.md→ .cursor/rules/genpm-core-pixels.mdc

Isto é exatamente o que sua IA lê quando trabalha em src/lib/pixels. Nada mais é adicionado ao contexto dela.

@core/pixels — rules for AI agents

Purpose

One place to measure business events (view_item, add_to_cart, begin_checkout, purchase, lead from @core/contracts) in GA4, Meta and TikTok: browser pixels loaded only inside ConsentGate (@core/consent) and server-side events (GA4 Measurement Protocol, Meta Conversions API, TikTok Events API) sent only with consent, with the same eventId on both sides so platforms deduplicate. Emails/phones are SHA-256 hashed. Never throws on vendor errors.

Map

index.ts — server: trackServer, attributionFromRequest, saveAttribution, takeAttribution, browserCalls, registerPixelPlatform.
client.ts — client: PixelScripts, track, newEventId. browser.ts — browserCalls (no server code; safe in the browser).
schema.ts — pixel_attributions (consent + first-party ids kept until the payment webhook, 7 days).

Integration

Env (all optional; a platform is active only with both of its vars): GA4_MEASUREMENT_ID + GA4_API_SECRET, META_PIXEL_ID + META_CAPI_TOKEN (optional META_GRAPH_VERSION, META_TEST_EVENT_CODE), TIKTOK_PIXEL_ID + TIKTOK_EVENTS_TOKEN. Check each platform's current API version and event names before going live.
Layout: <ConsentGate category="analytics"><PixelScripts ga4MeasurementId=… /></ConsentGate> and <ConsentGate category="marketing"><PixelScripts metaPixelId=… tiktokPixelId=… /></ConsentGate>. PixelScripts renders nothing: once mounted (i.e. with consent) it injects each platform's loader into <head> once per page, so re-mounts don't repeat config/PageView. A CSP must allow those script and connect origins.
Browser events: const eventId = newEventId(); track({ type: 'add_to_cart', eventId, … }) and send the same eventId to the server if it also tracks it.
Purchases: after startCheckout returns { sessionId }, saveAttribution("checkout:" + sessionId, attributionFromRequest(req)); when the order is paid (@core/orders onOrderEvent('paid')), trackServer(purchaseEvent(order), await takeAttribution("checkout:" + order.cartId)) (@core/checkout stores the Stripe session id in order.cartId; purchaseEvent comes from @core/checkout).
Verify with each platform's test tools (GA4 DebugView, Meta Test Events, TikTok Test Events).

Conventions

List in the privacy policy what each platform receives (events, hashed email, IP, user agent, click ids).
Use real values only; purchase uses the order total and the order id.

Don't

Don't load pixels or call trackServer without the matching consent category.
Don't send raw emails, phones, names or addresses to ad platforms.
Don't invent events (fake purchases to "train" campaigns) or fire purchase from the success page without an order.

# @core/pixels — rules for AI agents

## Purpose
One place to measure business events (`view_item`, `add_to_cart`, `begin_checkout`, `purchase`, `lead` from
@core/contracts) in GA4, Meta and TikTok: browser pixels loaded only inside `ConsentGate` (@core/consent) and
server-side events (GA4 Measurement Protocol, Meta Conversions API, TikTok Events API) sent only with consent, with
the same `eventId` on both sides so platforms deduplicate. Emails/phones are SHA-256 hashed. Never throws on vendor errors.

## Map
- `index.ts` — server: `trackServer`, `attributionFromRequest`, `saveAttribution`, `takeAttribution`, `browserCalls`, `registerPixelPlatform`.
- `client.ts` — client: `PixelScripts`, `track`, `newEventId`. `browser.ts` — `browserCalls` (no server code; safe in the browser).
- `schema.ts` — `pixel_attributions` (consent + first-party ids kept until the payment webhook, 7 days).

## Integration
1. Env (all optional; a platform is active only with both of its vars): `GA4_MEASUREMENT_ID` + `GA4_API_SECRET`,
   `META_PIXEL_ID` + `META_CAPI_TOKEN` (optional `META_GRAPH_VERSION`, `META_TEST_EVENT_CODE`), `TIKTOK_PIXEL_ID` + `TIKTOK_EVENTS_TOKEN`.
   Check each platform's current API version and event names before going live.
2. Layout: `<ConsentGate category="analytics"><PixelScripts ga4MeasurementId=… /></ConsentGate>` and
   `<ConsentGate category="marketing"><PixelScripts metaPixelId=… tiktokPixelId=… /></ConsentGate>`.
   `PixelScripts` renders nothing: once mounted (i.e. with consent) it injects each platform's loader into `<head>` once
   per page, so re-mounts don't repeat `config`/`PageView`. A CSP must allow those script and connect origins.
3. Browser events: `const eventId = newEventId(); track({ type: 'add_to_cart', eventId, … })` and send the same `eventId` to the server if it also tracks it.
4. Purchases: after `startCheckout` returns `{ sessionId }`, `saveAttribution("checkout:" + sessionId, attributionFromRequest(req))`;
   when the order is paid (@core/orders `onOrderEvent('paid')`), `trackServer(purchaseEvent(order), await takeAttribution("checkout:" + order.cartId))`
   (@core/checkout stores the Stripe session id in `order.cartId`; `purchaseEvent` comes from @core/checkout).
5. Verify with each platform's test tools (GA4 DebugView, Meta Test Events, TikTok Test Events).

## Conventions
- List in the privacy policy what each platform receives (events, hashed email, IP, user agent, click ids).
- Use real values only; `purchase` uses the order total and the order id.

## Don't
- Don't load pixels or call `trackServer` without the matching consent category.
- Don't send raw emails, phones, names or addresses to ad platforms.
- Don't invent events (fake purchases to "train" campaigns) or fire `purchase` from the success page without an order.

A árvore exata que será injetada, após o .genpmignore. Fixada em

src/lib/pixels/LICENSEsomente leitura · abb4ca2

MIT License

Copyright (c) 2026 GenPM

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Versão	Commit	Publicado	Análise
1.0.1	abb4ca2	há 5 horas	análise aprovada

$genpm add @core/pixels

Injeta: src/lib/pixels
Commit
Tag: v1.0.1
Requer: @core/antispam ^1.0.0 @core/consent ^1.0.0 @core/contracts ^1.0.0 @core/db ^1.0.0 @core/money ^1.0.0
npm: react ^19.0.0
Env: GA4_MEASUREMENT_ID GA4_API_SECRET META_PIXEL_ID META_CAPI_TOKEN TIKTOK_PIXEL_ID TIKTOK_EVENTS_TOKEN
Qualidade: 100/100
Usado por: 1
Instalações: 0 / 30d
Publicado: há 5 horas · genpm-system

Selo para o README

[![genpm](https://api.genpm.net/v1/badge/@core/pixels.svg)](https://genpm.net/p/@core/pixels)