Sandcastle Amplitude

[Guillar1]

Description

Adds Amplitude analytics to Sandcastle.

Analytics only run when VITE_AMPLITUDE_API_KEY is set at build time. Builds without a key send no data, so local development and forks are unaffected by default. Session start/end are captured automatically by Amplitude; everything else is an explicit trackEvent call.

The catalog lives in three places that describe the same set: the AnalyticsEventName type in src/analytics/amplitude.ts, src/analytics/tracking-plan.csv (Amplitude CSV import format), and src/analytics/README.md.

Events

Event	When it fires	Properties
Sandcastle Shared	Share popover is opened, generating a share link	demo_id
Gallery Item Opened	A gallery demo is loaded into the editor	demo_id, labels, method (browse / search / url)
Gallery Searched	Gallery search text settles, after a 2s debounce rather than per keystroke	term, result_count
Code Edited	First manual edit after a sandcastle is loaded or reset	none
New Sandcastle Created	New blank sandcastle created from the app bar	none
Standalone Opened	Standalone viewer opened from the header	demo_id
Copilot Panel Opened	Chat panel goes from closed to open	source (nav_button / console_action)
Copilot Panel Closed	Chat panel goes from open to closed	source (nav_button / close_button)
Copilot Settings Opened	Settings panel opened from the chat panel header	none
Copilot API Key Dialog Opened	API key configuration dialog opens	none
Copilot API Key Saved	Provider credentials pass validation and are saved	provider (anthropic / gemini / vertex)
Copilot Message Sent	User submits a chat message (automatic error-fix retries excluded)	model, provider, message_length
Copilot Code Applied	Copilot-produced code is applied to the editor, once per applied edit	none

Plus [Amplitude] Start Session and [Amplitude] End Session, which Amplitude generates on its own and are not part of the tracking plan CSV.

No credential values, code contents, or message text are recorded. Gallery Searched records the search term, and Copilot Message Sent records only the message's character count.

Requests before this can merge

I need help from someone with the right access:

1. Create a production Amplitude project for Sandcastle (there is a dev project already), and import packages/sandcastle/src/analytics/tracking-plan.csv into both the prod and dev projects so the events show up with descriptions and typed properties.
2. Set schema enforcement to block unplanned data in both projects, once the tracking plan is imported. In Amplitude Data under the project's schema settings, set unexpected events and unexpected event properties to be rejected rather than allowed or warned. That keeps the CSV in this repo as the source of truth: anything not in the tracking plan gets dropped instead of quietly creating new event types in the project.
3. Add the API keys as GitHub Actions secrets on this repo:
   • PROD_AMPLITUDE_API_KEY: the new prod project key, used by .github/workflows/prod.yml for the sandcastle.cesium.com build.
   • DEV_AMPLITUDE_API_KEY: the dev project key, used by .github/workflows/sandcastle-dev.yml for the dev-sandcastle.cesium.com build.

Until the secrets exist the workflows still build and deploy fine, the key just resolves to an empty string and no analytics are sent.

Issue number and link

Testing plan

1. On Amplitude: grab an API key from a project.
2. Copy packages/sandcastle/.env.example to packages/sandcastle/.env.local and set VITE_AMPLITUDE_API_KEY to that key.
3. Import packages/sandcastle/src/analytics/tracking-plan.csv into the project.
4. Run Sandcastle, exercise each event in the table above, and confirm they land in Amplitude with the expected properties.
5. Unset the key and confirm no network requests go to Amplitude.

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

AI acknowledgment

• I used AI to generate content in this PR
• If yes, I have reviewed the AI-generated content before submitting

If yes, I used the following Tools(s) and/or Service(s):

If yes, I used the following Model(s):

[github-actions]

Thank you for the pull request, @Guillar1!

✅ We can confirm we have a CLA on file for you.

[ggetz]

@Guillar1 Would you mind listing out any config setup we need to do for this PR? Thanks!

[lukemckinstry]

Took an initial pass and this looks good. Still working on getting access to test the dev setup. And understood we are waiting on more setup and OKs for prod down the line.