동의 기반 전환 추적: GA4, Meta 픽셀 + Conversions API, TikTok 픽셀 + Events API, 이벤트 중복 제거
설치
genpm add @core/pixels포함 내용
- src/lib/pixels/에 소스 코드, 파일 7개. (21.2kB)
- src/lib/pixels/AGENTS.md에 AI 규칙, 그리고 IDE 규칙 파일.
- .env.example에 추가되는 환경 변수: GA4_MEASUREMENT_ID, GA4_API_SECRET, META_PIXEL_ID, META_CAPI_TOKEN, TIKTOK_PIXEL_ID, TIKTOK_EVENTS_TOKEN.
- @core/antispam, @core/consent, @core/contracts, @core/db, @core/money을(를) 자동으로 해결합니다.
README
이 패키지에는 README가 없습니다.
이것이 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(optionalMETA_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>.PixelScriptsrenders nothing: once mounted (i.e. with consent) it injects each platform's loader into<head>once per page, so re-mounts don't repeatconfig/PageView. A CSP must allow those script and connect origins. - Browser events:
const eventId = newEventId(); track({ type: 'add_to_cart', eventId, … })and send the sameeventIdto the server if it also tracks it. - Purchases: after
startCheckoutreturns{ sessionId },saveAttribution("checkout:" + sessionId, attributionFromRequest(req)); when the order is paid (@core/ordersonOrderEvent('paid')),trackServer(purchaseEvent(order), await takeAttribution("checkout:" + order.cartId))(@core/checkout stores the Stripe session id inorder.cartId;purchaseEventcomes 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;
purchaseuses the order total and the order id.
Don't
- Don't load pixels or call
trackServerwithout 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
purchasefrom 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 적용 후 주입될 정확한 트리입니다. 고정 대상:
// Parte de los píxeles sin servidor ni base de datos: la usan el navegador (`client.ts`) y el servidor.
import type { TrackedEvent } from '../contracts/index.ts';
import { toDecimalString } from '../money/index.ts';
export const META_NAMES = { view_item: 'ViewContent', add_to_cart: 'AddToCart', begin_checkout: 'InitiateCheckout', purchase: 'Purchase', lead: 'Lead' } as const;
export const TIKTOK_NAMES = { view_item: 'ViewContent', add_to_cart: 'AddToCart', begin_checkout: 'InitiateCheckout', purchase: 'CompletePayment', lead: 'SubmitForm' } as const;
export const value = (e: TrackedEvent) => ('value' in e && e.value ? e.value : null);
export const items = (e: TrackedEvent) => ('items' in e ? e.items : []);
/** Llamadas equivalentes de gtag, fbq y ttq para un evento (mismo `eventId` que el servidor). */
export function browserCalls(e: TrackedEvent) {
const v = value(e);
const common = { ...(v && { currency: v.currency, value: Number(toDecimalString(v)) }) };
return {
gtag: ['event', e.type === 'lead' ? 'generate_lead' : e.type, { ...common, event_id: e.eventId, ...(e.type === 'purchase' && { transaction_id: e.orderId }) }] as const,
fbq: ['track', META_NAMES[e.type], { ...common, ...(items(e).length && { content_ids: items(e).map((i) => i.id), content_type: 'product' }) }, { eventID: e.eventId }] as const,
ttq: [TIKTOK_NAMES[e.type], { ...common, event_id: e.eventId }] as const,
};
}
이 패키지는 MCP 서버를 선언하지 않습니다.
| 버전 | 커밋 | 게시일 | 검사 |
|---|---|---|---|
| 1.0.1 | abb4ca2 | 3시간 전 | 검사 통과 |
- genpm
- @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
- 제안됨
- GenPM은 npm 명령을 제안하고, 동의한 경우에만 실행합니다.
- 사용하는 패키지 (1)
- @core/kit-landing ^1.0.0
- 검사
- 검사 통과 · 문제 0건
- 커밋
- v1.0.1 → abb4ca25745fd3d140e351fc27ecbcccb9f334f4 · 가져온 뒤 검증됨
- 스크립트
- 없음. GenPM은 패키지 코드를 절대 실행하지 않습니다.
- 라이선스
- MIT
- 품질
- 100/100
- 인정된 라이선스충족
- AGENTS.md에 목적 설명충족
- AGENTS.md에 통합 단계충족
- AGENTS.md에 규칙 또는 금지 사항충족
- 테스트 포함충족
- 보안 검사 통과충족
- 최근 6개월 내 게시충족
- 인증된 게시자충족
- 요약과 키워드충족
- 신고
- 문제가 있나요?