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/19bac1e

[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.

This PR adds the new React component src/providers/TourProvider/TourTelemetryBridge.tsx, but the compiler config only registers src/providers/TourProvider/tourCompletion.ts. src/providers is not enabled as a directory, so the new bridge component is left outside React Compiler coverage.

Suggestion: Add src/providers/TourProvider/TourTelemetryBridge.tsx to REACT_COMPILER_ENABLED_DIRS as part of this PR, or enable a cleaned-up TourProvider subdirectory if appropriate.

Rule: tangle-ui-review: React Compiler adoption; .claude/skills/review: new components/hooks must be covered by react-compiler.config.js

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

useRecordTourCompletion falls back to {} when the tourCompletions query has not loaded yet, then PATCHes that map as the full completed_tours setting. If a user completes a tour before the settings query resolves, or after it failed, the PATCH can replace previously saved completions with only the current tour.

Suggestion: Do not persist from an empty cache unless the query is known to be loaded. Fetch/ensure the current completed_tours map before merging, move the read-merge-write into the mutation, or gate persistence until the query succeeds and invalidate/refetch after mutation failures.

Rule: .cursorrules: use TanStack Query for server state and proper error/cache handling; tangle-ui-review: General quality