@core / pixels

1.0.1 ▾

1.0.1

인증됨MIT

GitHub

동의 기반 전환 추적: GA4, Meta 픽셀 + Conversions API, TikTok 픽셀 + Events API, 이벤트 중복 제거

코드파일 7개컨텍스트약 702토큰검사 통과

약 702토큰→ src/lib/pixels/AGENTS.md→ .cursor/rules/genpm-core-pixels.mdc

이것이 AI가 src/lib/pixels에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

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

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/lib/pixels/LICENSE읽기 전용 · 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.

버전	커밋	게시일	검사
1.0.1	abb4ca2	4시간 전	검사 통과

$genpm add @core/pixels

주입 위치: src/lib/pixels
커밋
태그: v1.0.1
필요: @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
품질: 100/100
사용처: 1
설치 수: 0 / 30일
게시일: 4시간 전 · genpm-system

README 배지

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