Instrument the Toronto voter survey for PostHog

[mikaalnaik]

Completion and stage drop-off for the Toronto voter survey were both invisible: the only event the survey sent was survey_submitted, which says how many finished and nothing about how many started or where the rest went.

Adds useSurveyAnalytics (src/app/toronto/vote/2026/survey/analytics.ts), which holds every event in one place so each carries the same identity — survey, survey_version, election, step_count — plus seconds_elapsed.

Events

Event	Fires when	Key props
survey_viewed	questionnaire mounts	—
survey_started	first non-empty answer (once per run)	step props
survey_step_completed	a step validates and they move on, including the last step on submit	step_index, step_id, answered_on_step
survey_step_blocked	validation holds them on the step	fields, field_count
survey_step_back	Back pressed	step props
survey_submitted	API accepted the response	ward
survey_submit_failed	submit threw	step props
survey_abandoned	tab hidden or unloaded mid-run	last-seen step props
survey_results_viewed	comparison resolves after completion	has_comparison, ward, races

How to read it in PostHog

• Completion:survey_viewed → survey_started → survey_submitted.
• Stage drop-off: a funnel of survey_step_completed repeated per step, filtered on step_index 0, 1, 2… It fires on clearing a step rather than on being shown one, so someone who lands on step 3 and leaves never emits it — that is the drop.
• survey_step_blocked separates "couldn't get past validation" from "gave up" on the same step.
• survey_results_viewed separates completions shown a real candidate comparison from wards whose candidates have not answered.

Notes for review

• survey_submitted moves out of submitSurvey.ts into the hook, keeping its name and existing properties, so one place emits it with the step and timing properties the funnel is built on. posthog.identify stays in submitSurvey, where the email is known to have been accepted.
• survey_abandoned is a best-effort last-seen marker, not a verdict: someone who backgrounds the tab and returns to finish emits both it and survey_submitted. It is capped at one per run and sent via sendBeacon. Read completion from survey_submitted, not as the inverse of this.

Testing

tsc --noEmit and eslint pass. The events themselves are not verified against a live project — there is no NEXT_PUBLIC_POSTHOG_TOKEN locally, so posthog.init never runs and captures are no-ops in dev. Worth a look at the PostHog live event feed on the preview deploy before relying on the funnel.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

The PR centralizes Toronto voter-survey analytics in a new hook and instruments views, starts, step transitions, submission outcomes, abandonment, and result rendering.

• Adds consistent survey identity, progress, and elapsed-time properties to PostHog events.
• Moves successful submission capture into the analytics hook while retaining accepted-email identification in submitSurvey.
• Tracks result availability after candidate comparison data resolves.

Confidence Score: 5/5

The PR appears safe to merge; no concrete blocking or independently actionable non-blocking defect remains.

The instrumentation follows the existing survey lifecycle, successful submissions are captured after API acceptance, and result reporting waits for the comparison data state that controls what the voter sees.

Important Files Changed

Filename	Overview
src/app/toronto/vote/2026/survey/SurveyClient.tsx	Integrates lifecycle, step, submission, and comparison-result analytics without changing the survey’s user-facing control flow.
src/app/toronto/vote/2026/survey/analytics.ts	Introduces a centralized PostHog hook with consistent event properties and documented best-effort abandonment semantics.
src/app/toronto/vote/2026/survey/submitSurvey.ts	Removes duplicate submission capture while preserving PostHog identification after the API accepts the response.

Sequence Diagram

sequenceDiagram
participant V as Voter
participant S as SurveyClient
participant A as Survey analytics
participant API as Survey API
participant PH as PostHog
V->>S: Open questionnaire
S->>A: Mount
A->>PH: survey_viewed
V->>S: Enter first answer
S->>A: started(progress)
A->>PH: survey_started
V->>S: Complete or fail validation
S->>A: stepCompleted / stepBlocked
A->>PH: Step event
V->>S: Submit
S->>API: submitSurvey
API-->>S: Accepted response
S->>A: submitted(progress, response)
A->>PH: survey_submitted
S->>A: resultsViewed(comparison)
A->>PH: survey_results_viewed

Loading

_{Reviews (1): Last reviewed commit: "Instrument the Toronto voter survey for ..." | Re-trigger Greptile}