@core / pixels

1.0.1 ▾

1.0.1

verifiedMIT

GitHub

Conversion tracking with consent: GA4, Meta Pixel + Conversions API, TikTok Pixel + Events API, deduplicated event ids

Code7 filesContext~702 tokensscan passed

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

This is exactly what your AI reads when it works in src/lib/pixels. Nothing else is added to its context.

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

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/pixels/index.tsread-only · abb4ca2

// @core/pixels — API pública del servidor. Cliente (PixelScripts, track, newEventId) en `./client.js`.
export {
  type Attribution,
  attributionFromRequest,
  browserCalls,
  ga4,
  meta,
  type PixelPlatform,
  pruneAttributions,
  registerPixelPlatform,
  saveAttribution,
  takeAttribution,
  type TrackResult,
  tiktok,
  trackServer,
} from './pixels.ts';
export { pixelAttributions } from './schema.ts';