Reference for the TanStack.com event taxonomy in Google Analytics 4.

GA4 property: G-JMT1Z50SPS First-party proxy: all hits route through /_a/g/collect on tanstack.com (see netlify.toml) Implementation: src/utils/analytics.ts, src/utils/analytics/events.ts

1. Event names describe what happened. Properties carry context. Adding a new partner placement is an enum value, not a new event.
2. One event per outcome, not per intent. No _clicked/_attempted events when an outcome event is going to fire anyway.
3. No per-row events. Counts and joined-string arrays as properties, not N rows per generation.
4. Session context propagates. Slow-changing props like mode_used and idea_used are stamped on every builder event so any breakdown works without joins.
5. Typed registry. Wrong props for an event = TypeScript error, not silent bad data.

Application Builder, four steps. No OR conditions, no overlapping event names.

Drop-off between any two steps is unambiguous.

Failure rates are separate explorations, not branches off the funnel:

• Analysis failure rate = builder_failed[stage=analysis] ÷ (builder_analyzed + builder_failed[stage=analysis])
• Generation failure rate = builder_failed[stage=generation] ÷ (builder_generated + builder_failed[stage=generation])
• Login wall rate = builder_failed[stage=login_blocked] ÷ page_view[page_type=application_builder]

Every event automatically receives page_location, page_path, page_title, page_type from the analytics utility.

Fires on initial load (auto from gtag config) and on every SPA navigation.

A partner UI element scrolled ≥50% into the viewport. Fires once per element-mount per session (the underlying IntersectionObserver disconnects after first fire).

Note on inflation: when filters change on the partners directory, cards unmount/remount and partner_viewed re-fires. Treat session-unique impressions as the dedup'd metric (compute in BigQuery with FIRST_VALUE(... PARTITION BY session_id, partner_id)).

User clicked a partner UI element to navigate somewhere.

CTR per placement = partner_clicked ÷ partner_viewed filtered to same placement.

User changed the filter state on the partners directory.

User clicked a "get in touch", "let's chat", or "become a partner" CTA.

Analysis API call succeeded. Outcome event — always preceded by user intent, no separate _requested event.

Generation API call succeeded.

Single umbrella event for analysis failures, generation failures, and login-wall blocks. Use the stage prop to distinguish.

User took an action on the generated result. Single event with action prop covers all post-generation actions.

Important: automatic prompt-copies that fire as a side-effect of generation do NOT emit builder_activated. Only user-driven actions count as activation.

mode_used and idea_used are tracked in the builder hook and stamped on every builder event. This means any builder event can be sliced by mode or idea without session joins.

mode_used transitions:

• none → lucky when user clicks "I'm feeling lucky"
• none → confident when user clicks "I'm feeling confident"

idea_used transitions:

• none → idea label string when user picks a suggested idea
• Reset back to none if user clears or types fresh input (TBD — currently sticks for the session)

Admin → Custom definitions → Create custom dimension. Event scope for all of these. Without registration, they're stored in BigQuery export but invisible in the GA4 UI.

12 dimensions. Well under the 50-dimension event-scoped limit.

Don't register: error_message, library_ids, partner_ids, addon_ids, destination_host. High cardinality. Query in BigQuery.

Explore → Funnel exploration, four steps as defined above. Open funnel. Show elapsed time.

Same funnel, breakdown dropdown = mode_used. Compare side by side.

Explore → Free-form, dimension = final_deployment, metric = event count of builder_generated.

Free-form, filter event_name = builder_failed, breakdown by stage.

Free-form, filter event_name = partner_clicked OR partner_viewed, breakdown by placement. Compute CTR yourself: clicks ÷ views per placement.

Requires BigQuery — library_ids is high-cardinality. Sample query:

SELECT
  library_id,
  COUNT(*) AS generations
FROM `tanstack.analytics_*.events_*`,
UNNEST(SPLIT((SELECT value.string_value
              FROM UNNEST(event_params)
              WHERE key = 'library_ids'), ',')) AS library_id
WHERE event_name = 'builder_generated'
  AND _TABLE_SUFFIX BETWEEN '20260101' AND '20260131'
GROUP BY library_id
ORDER BY generations DESC
LIMIT 10

Strongly recommended. Free at our event volume. Without it, anything beyond stock reports is painful.

Setup:

1. GA4 Admin → BigQuery Links → Link
2. Pick a GCP project, daily export, US multi-region
3. Tables appear at tanstack.analytics_<property_id>.events_YYYYMMDD after ~24h

Once enabled, all event properties are queryable — including the ones not registered as custom dimensions. Use SQL for everything dimensional or aggregate-heavy. Use the GA4 UI for funnel exploration and headline numbers.

Anything additive should not require schema migration of the existing taxonomy.

Add a new partner placement:

1. Add the value to PartnerPlacement in src/utils/analytics/events.ts
2. Use it at the call site
3. (Optional) update the placement table in this doc

Add a new builder action:

1. Add the value to BuilderAction
2. Use it at the builder_activated call site

Add a new event:

1. Add a new union member to AnalyticsEvent with its prop interface
2. Call trackEvent({ name: '...', props: { ... } })
3. Register relevant breakdown props as custom dimensions in GA4 admin
4. Document the event in this file

Don't: add new properties to existing events without updating both the type definition and this doc. Schema drift in analytics events is the slowest bug to detect.

Collapsed 28 events into 9. Removed application_starter_* event family. Replaced with builder_* events. Mode and idea selection moved from standalone events into session-context props on every builder event.

Events removed entirely (no replacement):

• application_starter_library_toggled, _integration_toggled, _package_manager_toggled, _toolchain_toggled — config exploration depth no longer tracked. Final config is on builder_generated.
• application_starter_continue_clicked, _generate_clicked — intent implied by outcome events.
• application_starter_login_clicked, _value_copied (auto), _builder_result_applied, _final_partner_in_prompt, _final_addon_in_prompt.

Events folded into others:

• application_starter_action_clicked (mode_selected) → mode_used prop on subsequent events
• application_starter_idea_selected → idea_used prop on subsequent events
• application_starter_login_required → builder_failed[stage=login_blocked]
• application_starter_value_copied (user trigger) → builder_activated[action=copy_prompt]
• All other application_starter_action_clicked calls → builder_activated
• partner_card_clicked, partner_click → partner_clicked
• partner_impression, partner_detail_viewed → partner_viewed
• partners_filter_changed → partner_filter_applied
• partner_inquiry_clicked, become_partner_clicked → partner_inquiry_started

Historical data with old event names is still queryable in GA4 and BigQuery. Cutover date: see git log for the migration commit.