@core / pixels

1.0.1 ▾

1.0.1

vérifiéMIT

Suivi des conversions avec consentement : GA4, Meta Pixel + Conversions API, TikTok Pixel + Events API, dédoublonnés

Code7 fichiersContexte~702 tokensanalyse réussie

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

Voici exactement ce que lit votre IA quand elle travaille dans src/lib/pixels. Rien d’autre n’est ajouté à son contexte.

@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.

L’arborescence exacte qui sera injectée, après .genpmignore. Épinglée à

src/lib/pixels/schema.tslecture seule · 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(),
});

Version	Commit	Publié	Analyse
1.0.1	abb4ca2	il y a 3 heures	analyse réussie

$genpm add @core/pixels

Injecte: src/lib/pixels
Commit
Tag: v1.0.1
Requiert: @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
Qualité: 100/100
Utilisé par: 1
Installations: 0 / 30 j
Publié: il y a 3 heures · genpm-system

Badge pour le README

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