@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/schema.tssomente leitura · abb4ca2

// Tablas de @core/pixels. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core';

/**
 * Atribución guardada al empezar un proceso (p. ej. el checkout) para enviar la conversión desde el servidor cuando
 * llegue el pago: consentimiento vigente e identificadores de primera parte. Caduca a los 7 días.
 */
export const pixelAttributions = pgTable('pixel_attributions', {
  key: text('key').primaryKey(),
  data: jsonb('data').$type<Record<string, unknown>>().notNull(),
  expiresAt: timestamp('expires_at', { withTimezone: true, mode: 'date' }).notNull(),
});

Versão	Commit	Publicado	Análise
1.0.1	abb4ca2	há 3 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á 3 horas · genpm-system

Selo para o README

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