Skip to main content

​
Core Fields

FieldRequiredDescription
site_idYesTracking site identifier
event_idNoUUID for dedupe (auto-generated if omitted)
event_timeNoEvent timestamp (defaults to now)
scan_session_idYes for /server-eventsLinks event to QR scan session
consentNogranted, denied, pending

​
Browser Event Fields (/collect)

FieldRequiredNotes
event_typeYesExample: pageview, click, form_submit
page_urlNoCurrent URL
page_titleNoPage title
referrerNoReferrer URL
deviceNoBrowser/device context
metadataNoMax 10KB, max depth 5, no raw emails

​
Server Event Fields (/server-events)

FieldRequiredNotes
event_nameYesExample: purchase, signup, lead
user_identifiersNoHashed IDs (email_hash, phone_hash, external_id)
conversion_valueNoamount + currency
propertiesNoMax 10KB, no raw emails

​
Idempotency and Dedupe

  • Prefer sending a stable event_id from your backend.
  • Re-sending the same event_id helps prevent duplicate counting downstream.

​
ClickHouse Storage Shape (events.valid_events)

The analytics pipeline stores/enriches event rows with fields such as:
ColumnMeaning
event_idUnique event UUID
event_timeClient/server event timestamp
received_timeIngestion receive timestamp
site_idTracking site identifier
scan_session_idSession for QR attribution
qr_code_idQR ID (resolved from session where available)
user_idUser identity (resolved/enriched where available)
event_typeBrowser auto/custom type (for example click, pageview)
event_nameServer/custom semantic name (for example purchase)
sourcebrowser or server
page_urlPage URL
referrerReferrer URL
device_typeDevice class
browser_familyBrowser family
os_familyOS family
country_codeCountry code
cityCity
conversion_valueNumeric conversion amount
conversion_currencyISO currency code
metadataJSON metadata string
is_duplicateDuplicate marker (0/1)
is_fraudFraud marker (0/1)

​
Example Browser Event Row

{
  "event_id": "98a9ef62-92fa-4a12-a92e-f61b62662da4",
  "event_time": "2026-03-09T12:13:42.582Z",
  "received_time": "2026-03-09T12:13:42.804Z",
  "site_id": "BYVAMGWSC9o9NbeV9ozNAU6Odvz27bWVFMFB7fwMwixFnHmMF2bI0KmwDkelb4HR",
  "scan_session_id": "35117f06-b3ad-4513-ab83-e37ba396eb22",
  "qr_code_id": "Q0630719e138346b8",
  "user_id": 1390,
  "event_type": "click",
  "event_name": null,
  "source": "browser",
  "page_url": "https://snug-start-web.lovable.app/about",
  "referrer": "",
  "device_type": "pc",
  "browser_family": "Chrome",
  "os_family": "Mac OS X",
  "country_code": "IN",
  "city": "Bengaluru",
  "conversion_value": null,
  "conversion_currency": null,
  "metadata": "{\"element_type\": \"A\", \"element_text\": \"About\"}",
  "is_duplicate": 0,
  "is_fraud": 0
}

​
Privacy Guardrails

  • Do not send raw emails in browser metadata or server properties.
  • Send hashed identifiers in user_identifiers for server events.