Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 17 additions & 10 deletions README-analytics.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Optional demo analytics
# Demo analytics

Production release assembly installs one shared, consented GA4 adapter for the gallery and all five demo apps. Local quickstarts and preview hosts do not transmit measurements. A cross-origin frame on www.superdoc.dev runs the Google tag, so the vendor cannot read the demo document, its title or room URL. Only bounded event categories cross the frame boundary. The adapter reuses SuperDoc's existing `G-E4T80WRJGS` property and preference format. It never loads identified CRM tracking.
Production release assembly installs one shared, bounded GA4 adapter for the gallery and all five demo apps. Local quickstarts and preview hosts do not transmit measurements. A cross-origin frame on www.superdoc.dev runs the Google tag, so the vendor cannot read the demo document, its title or room URL. Only bounded event categories cross the frame boundary. The adapter reuses SuperDoc's existing `G-E4T80WRJGS` property and preference format. It never loads identified CRM tracking.

Public events use fixed demo/action/capability values only. Query values, rooms, filenames, documents, prompts, error text and citation text are excluded. Refusal, withdrawal, DNT, GPC, opt-out and incoming private URLs suppress transport. Later private navigation removes the measurement frame without changing application navigation. Auto-created demo rooms remain measurable only from a clean public entry. Change or withdraw the choice through Privacy settings. Events deduplicate per page and action category, rather than counting keystrokes or polling.
Public events use fixed demo/action/capability values only. Query values, rooms, filenames, documents, prompts, error text and citation text are excluded. Refusal, withdrawal, DNT, GPC, opt-out and incoming private URLs suppress transport. Later private navigation removes the measurement frame without changing application navigation. Auto-created demo rooms remain measurable only from a clean public entry. The adapter does not inject a consent prompt, floating settings button or other visible controls. On supported public routes, bounded analytics runs without a prompt unless a saved decline or browser opt-out blocks it. Saved declines remain effective even after the normal preference age window; this adapter does not enable visitor identification. Events deduplicate per page and action category, rather than counting keystrokes or polling.

Readiness comes from the editor callback. Review, fields, agent jobs, Q&A and saved versions use actual completion/failure callbacks. Browser export completion does not establish successful Word rendering or a completed developer evaluation. Gallery cards and source/Build this use measure discovery and implementation interest separately. Do not sum per-demo users or compare new collection with an untracked baseline.

`node --test scripts/*.test.mjs` checks the release scripts and bounded consent contract. Build all affected apps and verify actual deployed ingestion before calling tracking live. Growth's existing Analytics and weekly metrics report own reporting; this adds no schedule or provider. Public content and private room semantics are unchanged.
`node --test scripts/*.test.mjs` checks the release scripts and bounded preference and opt-out contract. Build all affected apps and verify actual deployed ingestion before calling tracking live. Growth's existing Analytics and weekly metrics report own reporting; this adds no schedule or provider. Public content and private room semantics are unchanged.

Release order: deploy homepage PR235 and verify its inert frame route first, then merge this gallery PR through the trusted maintainer workflow. The new transport has no historical baseline.

Expand All @@ -18,10 +18,13 @@ custom event, an outgoing Google request, then a received event in GA4.
1. Open `https://demos.superdoc.dev/` without a query or fragment. Open DevTools,
select **Network**, enable **Preserve log**, and reload. Confirm
`/demo-analytics.js` returns JavaScript rather than the gallery HTML fallback.
2. Allow optional analytics through the gallery consent control. Wait for the
2. Analytics starts automatically on eligible public routes; there is no consent
prompt or floating settings button. Wait for the
`www.superdoc.dev/demo-analytics-frame.html` frame and Google tag to load.
Declined consent, DNT/GPC, opt-out, private links and blocked Google requests
prevent collection; do not bypass those controls to make a check pass.
Saved declines (including older declines), DNT/GPC, explicit opt-out, private
links and blocked Google requests prevent collection. Query strings other than
`demo_entry=homepage|gallery`, including UTM parameters, also block collection;
use the clean public URL when verifying and preserve opt-out controls.
3. Filter Network by `collect` (all request types). Page activation should produce
`superdoc_demo_event` with `load_started` and, after about one visible second,
`exposed`. Click a demo card or source/docs link to check an actual user action.
Expand All @@ -35,7 +38,7 @@ custom event, an outgoing Google request, then a received event in GA4.
source observation, so it is not the immediate smoke-test surface.

For an optional synthetic smoke test, run this once in the gallery page's console
after consent and frame initialization:
after the analytics frame and Google tag have initialized:

```js
window.dispatchEvent(new CustomEvent('superdoc:demo', {
Expand Down Expand Up @@ -73,8 +76,12 @@ is mocked and does not send synthetic activity to production.

## Every future published demo and example

Josh's November 15 direction applies to every future demo and example, including public customer follow-ups and launches outside this gallery. Before readiness, record the stable resource ID, canonical public destination, developer task, meaningful action and expected result, native social/video metrics where relevant, reporting coverage and collection start date. Reuse the existing consented GA4 transport, Growth Analytics and weekly metrics publisher.
Josh's November 15 direction applies to every future demo and example, including public customer follow-ups and launches outside this gallery. Before readiness, record the stable resource ID, canonical public destination, developer task, meaningful action and expected result, native social/video metrics where relevant, reporting coverage and collection start date. Reuse the existing bounded GA4 transport, Growth Analytics and weekly metrics publisher.

For a gallery addition, CI executes the real adapter against every `demos.json` route and requires its stable ID plus consent/refusal behavior. A new manifest entry with no registered tracking fails the existing release tests. Update the adapter, isolated homepage frame allowlist and Growth labels/queries together, add actual readiness/success/failure callbacks and verify production ingestion after the normal reviewed releases. Never add a generic arbitrary-event or arbitrary-URL escape hatch to make coverage pass.
For a gallery addition, CI executes the real adapter against every `demos.json` route and requires its stable ID plus default collection and saved-refusal behavior. A new manifest entry with no registered tracking fails the existing release tests. Update the adapter, isolated homepage frame allowlist and Growth labels/queries together, add actual readiness/success/failure callbacks and verify production ingestion after the normal reviewed releases. Never add a generic arbitrary-event or arbitrary-URL escape hatch to make coverage pass.

For a new public host or standalone example, prepare the same coverage through its owning repository and normal review before posting. A local quickstart or downloaded source example must remain free of analytics by default. Native video views, link clicks, example downloads and successful interactive actions are different measures. Unsupported platform metrics remain explicitly unavailable, never zero or invented. Do not alter old posts, customer links or private rooms to manufacture attribution. Follow the existing content worker's [future demo measurement standard](https://github.com/superdoc/sales-engine/blob/main/docs/demo-analytics.md#future-demos-and-examples).

## Visible demo UI

The shared measurement adapter must not add a modal, banner, floating privacy control or other unsolicited demo UI. Keep developer-facing UI changes separate and visible in normal review; adding measurement is not authority to introduce a new visitor interaction. The existing adapter regression executes fresh, declined and granted preferences on the gallery and every published demo route and rejects injected visible controls. Preserve saved declines, DNT/GPC/explicit opt-out, withdrawal, private-room guards and the bounded payload contract. The gallery default is measurement without a prompt; do not infer permission to change tracking on another host or in local/downloaded examples.
22 changes: 5 additions & 17 deletions analytics/demo-analytics.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading