feat: Guided Tours Completion Metrics

[camielvs]

Description

Tours can now be marked as completed and restarted, and we capture progression telemetry so we can see how tours are used and where people bounce off.

Completion state is persisted per user on the backend via /api/users/me/settings (key: completed_tours) — read with TanStack Query and updated with a read-modify-write PATCH, so it survives across sessions/devices and sits alongside any other user settings without overwriting them. There is no local-storage layer: when no backend is available (e.g. offline / GitHub Pages) completion state simply doesn't surface, which is acceptable for this low-stakes feature and can be revisited later.

We deliberately do not resume partially-finished tours — restarting always begins from the first step — so no in-progress state is surfaced.

User-facing

• Completed tours show a "Completed" badge and their action relabels to "Restart" (in both the Tours library and Featured tours).
• Restarting starts the tour fresh.

Telemetry (analytics events, independent of the settings store)

• learning_hub.tours.start — now carries is_restart to distinguish redos from first runs.
• learning_hub.tours.step_viewed — fired once per step reached (step_index, step_count, interaction); gives a step-by-step drop-off funnel.
• learning_hub.tours.completed — on reaching the final step (step_count, completion_count, previously_completed, duration_ms).
• learning_hub.tours.exited — on leaving before completion (furthest_step, percent_complete, duration_ms, previously_completed) — the "bounce" signal.

Together these cover issue 640's item 2 (how many started/completed, and how far users get before exiting).

Related Issue and Pull requests

Closes https://github.com/Shopify/oasis-frontend/issues/640

Note

Cross-device persistence depends on the backend /api/users/me/settings route doing a key-level merge of the settings dict (confirmed) so completed_tours is appended alongside other keys rather than replacing them.

Type of Change

• New feature

Checklist

• I have tested this does not break current pipelines / runs functionality
• I have tested the changes on staging

Screenshots (if applicable)

Test Instructions

1. With a backend configured, go to Learning Hub → Guided Tours and complete a tour through to the final step.
2. Return to the library: the tour shows a Completed badge and a Restart button.
3. Reload the page — completion persists (it's read from /api/users/me/settings). In DevTools, the GET .../api/users/me/settings?setting_names=completed_tours returns the completed_tours map; completing a tour fires a PATCH that includes the full map under settings.completed_tours.
4. Start a tour and navigate away before finishing → a learning_hub.tours.exited event fires with furthest_step. Walk a tour to the end → learning_hub.tours.completed fires; each step emits step_viewed.
5. (Offline / no backend) Tours still run; completion badges just don't surface — nothing errors.

Additional Comments

completed_tours write is last-write-wins against the cached map within a session — a completion added by another tab/device between our GET and PATCH could be missed. Negligible here; true per-entry safety would require the backend to deep-merge completed_tours.

[github-actions]

🎩 Preview

A preview build has been created at: 06-11-feat_guided_tours_completion_metrics/3bfbe19

[camielvs]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: Onboarding Welcome Page #2435
• feat: Onboarding Pill #2440
• feat: Onboarding Checklist #2421
• feat: Learning Hub - Milestone 2 #2416
• feat: Guided Tours Cleanup #2417
• feat: Guided Tours E2E Tests #2415
• feat: Guided Tours Completion Metrics #2412 👈 (View in Graphite)
• feat: Guided Tour - Secrets #2406
• feat: Guided Tours Framework (Secrets) #2405
• feat: Guided Tour - Subgraphs #2366
• feat: Guided Tours Framework (Subgraphs) #2365
• feat: Guided Tour - First Pipeline #2312
• feat: Guided Tours Framework (First Pipeline) #2347
• feat: Guided Tour - Navigating the Editor #2306 : 1 other dependent PR (#2307 )
• feat: Guided Tours Framework (Navigating the Editor) #2299
• feat: Guided Tours End Screen #2339
• feat: Guided Tours Ephemeral Pipelines #2334
• feat: Guided Tours Custom Navigation #2340
• feat: Guided Tours Foundation #2348
• feat: Learning Hub Guided Tours #2297
• feat: Learning Hub - Milestone 1 #2341
• feat: Learning Hub Tip of the Day #2292
• feat: Learning Hub Tip Browser #2291
• feat: Learning Hub Example Pipelines #2283
• feat: Learning Hub Documentation & FAQ #2282
• feat: Learning Hub Dashboard #2281
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

useRecordTourCompletion returns completionCount and previouslyCompleted from the current React Query cache before the mutation fetches and merges the authoritative settings map. When the cache is cold, stale, or still loading, TourTelemetryBridge immediately emits learning_hub.tours.completed with completion_count: 1 and previously_completed: false even if the server record already has prior completions. The PATCH later writes the correct merged count, but the analytics event for this completion is already wrong.

Suggestion: Make recording return the authoritative result used by the mutation (for example, expose an async mutateAsync/recordCompletion that resolves after ensureQueryData, then track completed from that result), or synchronously seed/update the cache before building the analytics payload so the emitted metrics match the persisted value.

Rule: tangle-ui-review: General quality / proper server-state handling for user-facing analytics