Pixel quickstart

curl -sS https://apis.kentro.live/pixel/v1/properties \
  -H "Authorization: Bearer $KENTRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main website",
    "type": "website",
    "environment": "production",
    "allowed_origins": ["www.example.com", "*.example.com"],
    "privacy_mode": "standard"
  }'

{
  "property": {
    "id": "0192f0c4-6d1e-7a52-9c1f-3b1f2c7f9a10",
    "name": "Main website",
    "type": "website",
    "environment": "production",
    "allowed_origins": ["www.example.com", "*.example.com"],
    "settings": {
      "consent": { "requireForAnalytics": true, "requireForMarketing": true, "defaultWhenUnknown": "denied", "honorGpc": true },
      "tracking": { "autoPageviews": true, "spaRoutes": true, "clicks": false, "forms": false, "formFieldAllowlist": [], "performance": true, "errors": false },
      "sensitivePathPatterns": [],
      "privacy": { "healthVertical": null },
      "lead": { "rawEmail": false },
      "session": { "idleMinutes": 30, "maxHours": 12 },
      "retention": { "journalMonths": 13, "errorsDays": 30 }
    },
    "privacy_mode": "standard",
    "status": "active",
    "verified_at": null,
    "created_at": "2026-10-09T17:00:00.000Z",
    "updated_at": "2026-10-09T17:00:00.000Z"
  },
  "public_key": {
    "id": "0192f0c4-6d1f-7b33-8d2e-5a9e0b1c2d3e",
    "key": "pk_live_Xq3M9b2LkV7tR1sNw8YhC4Ze",
    "label": "default",
    "status": "active",
    "last_used_at": null,
    "created_at": "2026-10-09T17:00:00.000Z",
    "revoked_at": null
  }
}

curl -sS https://apis.kentro.live/pixel/v1/properties/$PROPERTY_ID/snippet \
  -H "Authorization: Bearer $KENTRO_TOKEN"

{
  "property_id": "0192f0c4-6d1e-7a52-9c1f-3b1f2c7f9a10",
  "public_key": "pk_live_Xq3M9b2LkV7tR1sNw8YhC4Ze",
  "snippet": "<script>window.kentroPixel=window.kentroPixel||function(){(window.kentroPixel.q=window.kentroPixel.q||[]).push(arguments)};</script>\n<script async src=\"https://pixel.kentro.live/sdk/v1/kentro-pixel.js\" data-key=\"pk_live_Xq3M9b2LkV7tR1sNw8YhC4Ze\"></script>",
  "sdk_url": "https://pixel.kentro.live/sdk/v1/kentro-pixel.js",
  "endpoint": "https://pixel.kentro.live"
}

<script>window.kentroPixel=window.kentroPixel||function(){(window.kentroPixel.q=window.kentroPixel.q||[]).push(arguments)};</script>
<script async src="https://pixel.kentro.live/sdk/v1/kentro-pixel.js" data-key="pk_live_Xq3M9b2LkV7tR1sNw8YhC4Ze"></script>

// Queue stub first, so calls made before the SDK loads are kept and replayed in order.
window.kentroPixel = window.kentroPixel || function () {
  (window.kentroPixel.q = window.kentroPixel.q || []).push(arguments);
};

// Without a data-key attribute, pass both key and endpoint to init.
window.kentroPixel('init', {
  key: 'pk_live_Xq3M9b2LkV7tR1sNw8YhC4Ze',
  endpoint: 'https://pixel.kentro.live'
});

var script = document.createElement('script');
script.async = true;
script.src = 'https://pixel.kentro.live/sdk/v1/kentro-pixel.js';
document.head.appendChild(script);

kentroPixel('consentChanged', {
  analytics: 'granted',
  marketing: 'denied',
  functional: 'granted',
  policy_version: '2026-10',
  source: 'cmp'
});

curl -sS "https://apis.kentro.live/pixel/v1/events/debug?propertyId=$PROPERTY_ID&limit=20" \
  -H "Authorization: Bearer $KENTRO_TOKEN"

{
  "events": [
    {
      "id": "0192f0c5-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "property_id": "0192f0c4-6d1e-7a52-9c1f-3b1f2c7f9a10",
      "event_id": "evt_192f0c51a2b9f3c7d1e5a2b4c6d8e0f",
      "event_name": "marketing.page_viewed",
      "schema_version": 1,
      "source_type": "browser",
      "environment": "production",
      "occurred_at": "2026-10-09T17:05:00.000Z",
      "received_at": "2026-10-09T17:05:00.412Z",
      "processing_status": "pending",
      "data_classification": "standard",
      "anonymous_id": "anon_6f1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
      "session_id": "sess_0a1b2c3d4e5f60718293a4b5",
      "refs": { "subject_ref": null, "commerce_subject_ref": null, "order_ref": null, "campaign_ref": null, "creative_ref": null, "landing_page_ref": null, "experiment_ref": null, "experiment_variant_ref": null },
      "context": { "page_url": "https://www.example.com/pricing?utm_source=google", "page_path": "/pricing", "page_title": "Pricing", "referrer_domain": "www.google.com", "utm": { "source": "google" }, "device_class": "desktop", "bot": false, "locale": "en-US", "sdk": { "name": "kentro-pixel-js", "version": "1.3.0" } },
      "consent": { "analytics": "granted", "marketing": "denied", "functional": "unknown", "policy_version": "2026-10", "source": "cmp", "recorded_at": "2026-10-09T17:04:58.000Z", "region": null, "gpc": false },
      "properties_shape": { "page_path": "string", "title": "string" },
      "provenance": { "source_type": "browser", "source_id": "pk_live_Xq3M9b2LkV7tR1sNw8YhC4Ze", "schema": "builtin", "is_authoritative": true, "consent_effective": { "analytics": "granted", "marketing": "denied", "functional": "granted" }, "consent_purpose": "analytics", "sdk": { "name": "kentro-pixel-js", "version": "1.3.0" } },
      "renamed_from": null
    }
  ]
}

curl -sS "https://apis.kentro.live/pixel/v1/ingestion/health?propertyId=$PROPERTY_ID" \
  -H "Authorization: Bearer $KENTRO_TOKEN"

{
  "window_hours": 24,
  "since": "2026-10-08T17:10:00.000Z",
  "receipts": 42,
  "accepted": 120,
  "duplicates": 3,
  "rejected": 2,
  "quarantined": 0,
  "suppressed": 15,
  "freshness": { "last_received_at": "2026-10-09T17:09:58.000Z", "age_seconds": 2 },
  "last_errors": [
    { "received_at": "2026-10-09T16:40:00.000Z", "source_type": "browser", "event_name": "marketing.page_viewed", "reason_code": "SCHEMA_VIOLATION", "reason": "properties must NOT have additional properties", "property_id": "0192f0c4-6d1e-7a52-9c1f-3b1f2c7f9a10" }
  ]
}

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.