Measure with Kentro Pixel

 Browser (your site)                          Your backend
 kentro-pixel.js, data-key = pk_live_...      paid orders, refunds
 page views, product views, leads             signed with a server key (sk_...)
        |                                              |
        v                                              v
 https://pixel.kentro.live/v1/events     https://pixel.kentro.live/v1/server/events
                  \                                   /
                   Kentro Pixel: validate, apply consent, deduplicate
                                      |
              analytics, attribution, audiences, destinations

You are installing Kentro Pixel on the user's website: the browser SDK, wired to the site's consent manager, so page views and the site's key events reach Kentro with each visitor's consent.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/docs/kentro-pixel.md
- https://docs.kentro.io/docs/pixel-quickstart.md
- https://docs.kentro.io/docs/pixel-browser-sdk.md
- https://docs.kentro.io/docs/pixel-events.md
- https://docs.kentro.io/docs/pixel-consent-privacy.md

Ask the user for these before writing code:
1. The site's framework, and where the shared head or root layout is rendered.
2. The Pixel property's public key, from Kentro GO: `Pixel`, the `Properties` tab, the property, the `Install` tab. Production properties have pk_live_ keys; staging and development properties have pk_test_ keys. A public key is meant to be visible in the page.
3. Which Kentro environment the property lives in: production (collector https://pixel.kentro.live) or Kentro staging (collector https://pixel.kentro.dev).
4. The consent manager the site uses, and how its categories map to Kentro's purposes: analytics, marketing and functional.
5. Whether the site sends a Content-Security-Policy, and which events matter beyond page views (sign-ups, add to cart).

Rules:
- Only the public key goes in the page. Never put a Pixel server key (sk_...) or its secret in browser code.
- Install the queue stub before the SDK script, exactly as the snippet on the `Install` tab (or GET https://apis.kentro.live/pixel/v1/properties/:id/snippet) shows. Load https://pixel.kentro.live/sdk/v1/kentro-pixel.js (or the .dev host) with data-key, or call `kentroPixel('init', { key, endpoint })`.
- Report consent at init and on every change with `kentroPixel('consentChanged', { analytics, marketing, functional, policy_version, source })`, with granted or denied for each purpose. Without analytics consent, events are recorded as suppressed by design: never work around it.
- Never send identity claims (subject_ref) from the browser, and never put emails, phone numbers or other personal data in event properties. A signed-in visitor is identified only through an identity token the user's server signs, as the Browser SDK page describes.
- Use only event names and properties from the taxonomy (GET https://apis.kentro.live/pixel/v1/event-schemas), and validate custom events before shipping.
- With a CSP, allow the collector host in script-src and connect-src, and allow the inline stub with a nonce or hash.
- No fingerprinting and no ad-blocker workarounds.

Steps:
1. Add the stub and the SDK script to every page (the root layout), or the script loader with init.
2. Translate the consent manager's state into consentChanged on load and on every change.
3. Single-page apps: after auto-init the SDK tracks route changes. Confirm it, and do not add duplicate page views.
4. Add the site's key events with the event names from the Events page.
5. Ask the user to check that the property's allowed origins (the `Domains` tab) list the site's hosts.

Acceptance checks. Run each one and show the user the evidence:
- In the browser's network tab, POST `<collector>/v1/events` answers 202 with one result per event, status accepted (or suppressed before consent).
- Before consent, the newest events show processing_status suppressed_consent in the property's `Debugger` tab (or GET https://apis.kentro.live/pixel/v1/events/debug?propertyId=...&limit=20 with credentials holding pixel:read). After analytics consent, marketing.page_viewed shows pending or processed.
- The `Health` tab (GET /v1/ingestion/health?propertyId=...) shows no new rejections, and any reason code it lists is fixed.
- Every custom event passes the property's `Validate` tab or POST /v1/event-schemas/validate.
- The browser console shows no CSP violations, and no server key appears in the site's code.

You are sending server-side events from the user's backend to Kentro Pixel: authoritative facts such as commerce.order_paid and refunds. Revenue reporting trusts these facts only when they come from a server source.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/docs/kentro-pixel.md
- https://docs.kentro.io/docs/pixel-server-api.md
- https://docs.kentro.io/docs/pixel-events.md
- https://docs.kentro.io/docs/pixel-consent-privacy.md

Ask the user for these before writing code:
1. The backend language and framework, and where payment success and refunds are recorded.
2. A server key for the Pixel property, created in Kentro GO on the property's `Keys` tab (or with POST https://apis.kentro.live/pixel/v1/properties/:id/server-keys). The secret is shown once. Ask the user to store the key id (sk_...) as KENTRO_PIXEL_KEY_ID and the secret as KENTRO_PIXEL_SECRET in the environment, never in the chat or the browser.
3. The collector: https://pixel.kentro.live for production or https://pixel.kentro.dev for Kentro staging.
4. Which business events to send, mapped to event names from the Events page.

Rules:
- POST each batch to `<collector>/v1/server/events` with Content-Type: application/json and three headers: X-Kentro-Key-Id with the key id; X-Kentro-Timestamp with the current Unix time in seconds; X-Kentro-Signature with sha256= followed by the hex HMAC-SHA256 of `"<timestamp>.<raw body>"` keyed with the secret. Sign the exact bytes you send: serialize the body once.
- The timestamp must be within 300 seconds of Kentro's clock, or the request is refused with TIMESTAMP_STALE. A wrong signature is refused with SIGNATURE_INVALID.
- Give every event a stable event_id derived from the business fact (for example the order id plus the event name), so a retry is deduplicated. Kentro deduplicates event ids for at least 14 days. Never generate a new id for a retry.
- event_name is lowercase and dotted (commerce.order_paid). occurred_at is ISO-8601, no more than 7 days in the past or 5 minutes in the future. Each event stays under 32 KB.
- Money follows the event schema in integer minor units; floating-point money is rejected. Read the schemas from GET https://apis.kentro.live/pixel/v1/event-schemas and check events with POST /v1/event-schemas/validate before sending.
- Send consent and identity fields as the Server API and consent pages describe, and never send personal data the schema does not ask for.
- Send after the database commit, from a queue or outbox, so a crash neither loses nor double-sends an event. Retry network errors, 429 and 5xx with backoff and the same event_id.

Steps:
1. A signer module, with a unit test against a fixed timestamp, body and secret.
2. A sender that batches events, posts them, and logs the receipt_id and each event's status.
3. Hooks on payment success and refunds that enqueue the events.
4. A dead-letter path for events that keep failing, with their reason codes.

Acceptance checks. Run each one against Kentro staging or a test property and show the user the requests and responses, with secrets redacted:
- One signed commerce.order_paid event answers 202 with results[0].status accepted.
- The same event sent again answers status duplicate and creates no second record.
- A request whose timestamp is 10 minutes old is refused with TIMESTAMP_STALE, and one with a wrong signature with SIGNATURE_INVALID.
- The event appears in the property's `Debugger` tab with source_type server.
- No server secret appears in code, logs or client assets.