Product Analytics Instrumentation and Event Tracking Questions

Policy overview: a concise, consistent naming convention for events and properties to make instrumentation discoverable, queryable, and reliable for analysts and engineers.

Event naming (pattern)

• Use: domain.action.object.context
• Lower_snake_case, no spaces, max 4 segments.
• Examples: checkout.start_cart, product.view_detail, auth.success_web
• Action verbs: start/complete/click/view/submit/error

Property naming (types & units)

• Lower_snake_case. Use a type-signaling convention: identifier fields end with an id suffix (user_id, session_id, order_id), not an id prefix; boolean fields start with an is_ prefix (is_logged_in); count fields start with a num_ prefix (num_items).
• Types: string, integer, float, boolean, timestamp, enum.
• Units: append the actual stored unit to the name, and never let the name claim a different unit than what is stored: price_cents (integer, USD cents), not price_usd, since price_usd would imply a dollar-denominated value; duration_ms (integer, ms); distance_km (float, km).
• Example properties: user_id (string), session_id (string), price_cents (integer), duration_ms (integer), is_logged_in (boolean), plan_tier (enum: free/premium)

Versioning

• Add event_version integer property (event_version: 1). Increment when schema changes incompatibly.
• For minor additive changes, keep same version and document optional fields.

Deprecation

• Mark deprecated in catalog with deprecation_date and replacement_event.
• Keep emitting deprecated events for a grace period (e.g., 90 days) while consumers migrate.
• After grace period, stop emitting and archive schema.

Governance & docs

• Maintain a searchable catalog (with examples, owners, versions).
• Require instrumentation review before release.

How this helps

• Predictable names speed SQL discovery and joins.
• Typed properties reduce interpretation errors and ensure correct aggregations.
• Versioning + deprecation avoids silent schema breaks, gives analysts time to adapt.

High-level approach: define a small consistent event envelope (common fields + event-specific payload). Include versioning, unique event_id for idempotency, minimal PII, and identifiers to support cross-device stitching.

Common envelope (required for all events)

• event_id: string (UUIDv4) - unique per emission
• version: string (e.g., "1.0")
• event_type: string (search, listing_view, add_to_cart, checkout, booking_confirm, cancel)
• occurred_at: string (ISO 8601 UTC)
• user_id: string | null (internal stable user id when authenticated)
• anonymous_id: string (UUID per-install/per-browser)
• session_id: string
• device_id: string | null
• platform: string (web, ios, android)
• context: object (geo: {country, region}, locale, app_version)
• client_ts: integer (ms since epoch)
• revenue: object | null {amount: decimal, currency: string}
• metadata: object (freeform for A/B or experiment tags)

Event-specific required fields

• search: {query: string|null, checkin: date|null, checkout: date|null, guests: int, filters: object}
• listing_view: {listing_id: string, host_id: string|null, price: decimal, currency: string, availability_snapshot: object|null}
• add_to_cart / checkout: {listing_id: string, nights: int, price: decimal, currency: string, fees: decimal}
• booking_confirm: {booking_id: string, listing_id: string, price_total: decimal, currency: string, payment_method: string (token_id), checkin, checkout}
• cancel: {booking_id: string, listing_id: string, cancel_reason: string|null, refund_amount: decimal|null, currency: string|null}

Idempotency & deduplication

• Use event_id (UUID) as primary dedupe key on ingestion. Keep short TTL dedupe cache (e.g., 7–30 days) in ingestion layer (Kafka dedupe, or DB/Redis).
• For critical downstream operations (e.g., transactional booking_confirm), also include business_id (booking_id) + event_type to enforce idempotency in transactional systems.
• Producers should persist last-sent event_id to retry safely.

Cross-device user linking

• Prefer server-side stable user_id when authenticated.
• For anonymous linking, use deterministic identity graph: capture hashed identifiers (email_hash, phone_hash) only after consent. Use salted HMAC with service key (never send raw PII).
• Stitch by user_id primarily; fallback to deterministic hashed identifiers + device fingerprinting + gradual merge rules (merge after successful login).
• Record link events (identity.link) that map anonymous_id -> user_id (with timestamp) to enable historical stitching.

PII minimization & security

• Never store raw email/phone in event payload. Use one-way HMAC(email, salt_key) as email_hash if needed for de-dup/linking.
• Limit free-text fields; redact any user-entered text on client-side before send.
• Store sensitive tokens (payment_method) as token_id only; actual payment details live in PCI-compliant vault.
• Encrypt event payloads in transit (TLS) and at rest; enforce RBAC in analytics DBs and mask PII columns in BI tools.

Versioning

• Use top-level version field. When schema changes (add/remove fields, semantics) increment major/minor. Maintain backward-compatible parsers; emit migration metadata.

Example event JSON (listing_view)

{
  "event_id": "5f2a4b8e-9d3c-4a1f-b2c1-0a1b2c3d4e5f",
  "version": "1.0",
  "event_type": "listing_view",
  "occurred_at": "2025-12-05T14:22:31Z",
  "client_ts": 1733451751000,
  "user_id": "user_12345",
  "anonymous_id": "anon_98765",
  "session_id": "sess_abc123",
  "device_id": "device_xyz",
  "platform": "web",
  "context": {"country":"US","locale":"en-US","app_version":"web-2025.12"},
  "payload": {
    "listing_id": "lst_54321",
    "host_id": "host_999",
    "price": 135.00,
    "currency": "USD",
    "availability_snapshot": {"2026-01-01": true, "2026-01-02": false}
  },
  "metadata": {"experiment":"homepage_redesign"}
}

Why this fits BI needs

• Consistent envelope simplifies ingestion, schema registry, and transforms for dashboards.
• event_id + booking_id enable accurate funnel metrics and deduplication.
• Minimal PII and hashed identifiers allow cross-device stitching while complying with privacy rules.
• Versioning lets BI pipelines evolve without breaking historical reports.

Data model

• UA: session-centric (hits grouped into sessions), pageview/transaction as primary. Good for web-traffic KPIs.
• GA4: event-centric (every interaction is an event with parameters). More flexible for product events and funnel analysis.

User identification

• UA: cookie + clientId; UserId optional but limited. Cross-device stitching weak.
• GA4: combines UserId, Google signals, and deviceId to build a more unified user profile (better cross-device attribution when available).

Cross-platform measurement

• UA: designed for websites; mobile SDKs existed but fragmented.
• GA4: built for web + app from the ground up, identical event model across platforms → easier unified funnels and lifecycle analysis.

Retention & privacy

• UA: longer retention options, less native privacy controls. Heavier use of cookies.
• GA4: more privacy-first - shorter default retention, cookieless strategies, consent mode, and parameter controls to minimize PII. Better compliance posture for GDPR/CCPA but fewer persistent identifiers.

Sampling

• UA: often samples large reports (esp. standard GA) which can skew product analyses.
• GA4: reduces sampling for many explorations, but limits exist in free tier; big query export allows unsampled analysis.

When to recommend GA4 vs Product Analytics (Amplitude/Mixpanel)

• Recommend GA4 when: you need consolidated marketing + basic product telemetry across web+app, free/low-cost solution, strong integration with Google Ads and BigQuery for downstream modeling.
• Recommend Amplitude/Mixpanel when: product team needs event-level, unsampled, behavioral analytics (complex funnels, retroactive event properties, cohorting, user-paths), fast iteration, advanced cohort/behavioral querying, and product-led experimentation. These tools offer richer product-centric features and retention analysis out of the box; use them alongside GA4 if you need both marketing attribution and deep product analytics.

Use GA4 for acquisition attribution and aggregated metrics; use product analytics or BigQuery-exported GA4 data for rigorous, unsampled modeling and feature engineering.

An "event" in product analytics is a discrete, instrumented record of a user action or system occurrence (e.g., "Clicked Sign Up" at timestamp T by userID X). It captures raw, contextual data (event name, properties like page, variant, device) and is the primary input for analysis. An aggregated metric is a computed summary (e.g., daily sign-ups = 1,234) derived from many events - useful for reporting but lossy for detailed analysis.

Three concrete event examples for onboarding:

• sign_up_submitted {user_id, method:email|google, timestamp, utm_campaign}
• onboarding_step_completed {user_id, step_id, duration_seconds, timestamp}
• welcome_email_opened {user_id, email_id, timestamp, client}

Two example metrics derived from those events for an onboarding funnel:

• Conversion rate by step = count(onboarding_step_completed step_n) / count(onboarding_step_completed step_n-1)
• Median time-to-complete onboarding = median(sum(duration_seconds) per user from first step to final step)

Why choice matters:

• Events preserve granularity and enable cohort, funnel, and root-cause analyses (filter by channel, device, or property). Aggregated metrics are efficient for dashboards and SLA tracking but hide heterogeneity (e.g., slow sub-cohort). Instrument the right events so analysts can recompute metrics, slice by dimensions, and avoid re-instrumentation later.

Plan overview: instrument the new checkout-promotion feature end-to-end so business KPIs (AOV, conversion) are reliable and auditable. Phases: design, implement, test/QA, rollout with sampling, monitor & report.

1. Event schema design (single source of truth)
   Provide consistent, minimal events with clear IDs and types. Example canonical events:

{
  "event_type": "promotion_applied",
  "timestamp": "ISO8601",
  "user_id": "anon|<hashed_id>",
  "session_id": "<uuid>",
  "order_id": "<nullable>",
  "product_ids": ["p1","p2"],
  "price_cents": 1999,
  "discount_cents": 300,
  "promotion_id": "PROMO123",
  "channel": "web|ios|android",
  "metadata": {"ab_variant":"B"}
}

Also send order_created and order_completed events with identical order_id and price/line-item breakdown.

2. Sampling strategy

• Default: capture 100% of conversion-critical events (order_created/completed, promotion_applied).
• For high-volume exploratory events (page_views), sample at 5–10% and annotate sampled=true and sampling_rate. Ensure sampled events still include session_id to link to full events.

3. QA checks

• Schema validation at ingestion (reject/log malformed events).
• Synthetic test suite: replay deterministic test users through feature to assert sequence: promotion_applied → order_created → order_completed with same order_id.
• Consistency checks: price math validation (sum(line_items) - discount == order_total).
• Duplicate detection: same event signature within short window flagged.
• Instrumentation smoke dashboards: event counts per minute, drop-off funnel (applied→created→completed).
• Canary rollout: enable for 1% of users, verify metrics before scaling.

4. Reporting to product & analytics

• Provide a rollout brief with event dictionary, sampling notes, and known caveats.
• Build 3 dashboards: funnel conversion (applied→completed), AOV by cohort (variant/channel), and anomaly charts with alerts (5% change or p < 0.01).
• Weekly sync for first month with product and analytics to review metrics, edge cases, and iterate.
• Deliver reproducible SQL queries and notebooks that join events on order_id/session_id so analysts can validate.

Rationale: explicit schema + 100% capture for critical events ensures KPI accuracy; sampling saves cost for noisy events; QA and canary reduce risk; clear reporting and reproducible artifacts make results actionable.