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
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,5 @@ node_modules/
/dist-gallery/
**/test-results/
**/playwright-report/

.private/
19 changes: 19 additions & 0 deletions README-analytics.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Optional 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.

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.

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.

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.

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

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 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).
76 changes: 76 additions & 0 deletions analytics/demo-analytics.js

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

Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
const demoMetric = (action: string, capability = 'document') => { try { window.dispatchEvent(new CustomEvent('superdoc:demo', { detail: { action, capability } })); } catch { /* Analytics must not affect the demo. */ } };
import { FormEvent, KeyboardEvent, PointerEvent, useEffect, useLayoutEffect, useRef, useState } from 'react';
import Markdown from 'react-markdown';
import type { SuperDoc } from 'superdoc';
Expand Down Expand Up @@ -146,7 +147,9 @@ export function ChatPanel({ roomId, disabled, unavailableReason, width, onWidthC

async function finishJob(job: Job) {
onDocumentUpdated?.();
if (job.status === 'failed') demoMetric('ai_failed', 'collaboration');
if (job.status === 'completed') {
demoMetric('ai_succeeded', 'collaboration');
const history = await api.getChatHistory(roomId);
setMessages(history);
setJobs((current) => current.filter((candidate) => candidate.id !== job.id));
Expand Down Expand Up @@ -208,10 +211,12 @@ export function ChatPanel({ roomId, disabled, unavailableReason, width, onWidthC
promptNavigationRef.current = null;
setPrompt('');
try {
demoMetric('ai_started', 'collaboration');
const job = await api.createJob(roomId, message, isSuggesting, selectedText || undefined);
setJobs((current) => [...current, job]);
await watchJob(job);
} catch (caught) {
demoMetric('ai_failed', 'collaboration');
setError(caught instanceof Error ? caught.message : String(caught));
}
}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
const demoMetric = (action: string, capability = 'document') => { try { window.dispatchEvent(new CustomEvent('superdoc:demo', { detail: { action, capability } })); } catch { /* Analytics must not affect the demo. */ } };
import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { SuperDocEditor, type SuperDocEditorProps } from '@superdoc/react';
import type { SuperDoc } from 'superdoc';
Expand Down Expand Up @@ -56,6 +57,7 @@ export const DocumentEditor = memo(function DocumentEditor({ room, mode, onActiv
}, [onConnectedUsersChange]);
const handleConnectionChange = useCallback<NonNullable<SuperDocEditorProps['onCollaborationConnectionChange']>>(({ state }) => {
synced.current = state === 'synced';
if (synced.current) demoMetric('task_succeeded', 'collaboration');
onConnectedUsersChange(synced.current ? presenceCount.current : null);
}, [onConnectedUsersChange]);

Expand Down Expand Up @@ -123,7 +125,7 @@ export const DocumentEditor = memo(function DocumentEditor({ room, mode, onActiv
instance.current = superdoc;
mountedEditor.current = true;
setEditorReady(true);
onReady(superdoc);
onReady(superdoc); demoMetric('ready', 'collaboration');
}}
onException={(event) => {
console.error('SuperDoc error', event);
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
const demoMetric = (action: string, capability = 'document') => { try { window.dispatchEvent(new CustomEvent('superdoc:demo', { detail: { action, capability } })); } catch { /* Optional analytics. */ } };
import { useState } from 'react';
import { useSuperDocCommand } from 'superdoc/ui/react';
import './TrackedChangesControls.css';
Expand All @@ -16,11 +17,14 @@ export function TrackedChangesControls() {
setPending(action);
setError('');
try {
demoMetric('task_started', 'review');
const result = await command.executeAsync();
if (result === false || (typeof result === 'object' && result !== null && 'success' in result && !result.success)) {
demoMetric('task_failed', 'review');
setError(`Could not ${action} all tracked changes.`);
}
} else { demoMetric('task_succeeded', 'review'); }
} catch {
demoMetric('task_failed', 'review');
setError(`Could not ${action} all tracked changes.`);
} finally {
setPending(null);
Expand Down
8 changes: 7 additions & 1 deletion custom-word-editor/src/demo/components/topbar/Topbar.tsx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
const demoMetric = (action: string, capability = 'document') => { try { window.dispatchEvent(new CustomEvent('superdoc:demo', { detail: { action, capability } })); } catch { /* Analytics must not affect the demo. */ } };
import { useRef, useState, type ReactNode } from 'react';
import { BlankDOCX } from 'superdoc';
import { useSuperDocDocument, useSuperDocHost, useSuperDocUI } from 'superdoc/ui/react';
Expand All @@ -20,8 +21,11 @@ export function Topbar({ viewControls, onDocumentReplaced }: { viewControls?: Re
const exportDocument = async (exportedName = 'reviewed-contract') => {
if (!host || !('export' in host) || typeof host.export !== 'function') return;
setSaving(true);
demoMetric('export_requested');
try {
await host.export({ exportType: ['docx'], exportedName });
demoMetric('export_completed');
} catch (error) { demoMetric('export_failed'); throw error;
} finally {
setSaving(false);
}
Expand Down Expand Up @@ -83,13 +87,15 @@ export function Topbar({ viewControls, onDocumentReplaced }: { viewControls?: Re
}],
});
setSaving(true);
demoMetric('export_requested');
const result = await ui.document.export({ exportType: ['docx'], triggerDownload: false });
if (!(result instanceof Blob)) throw new Error('SuperDoc did not return a DOCX file.');
const writable = await handle.createWritable();
await writable.write(result);
await writable.close();
await writable.close(); demoMetric('export_completed');
} catch (error) {
if (error instanceof DOMException && error.name === 'AbortError') return;
demoMetric('export_failed');
console.error(error);
setImportError('The document could not be saved.');
} finally {
Expand Down
5 changes: 3 additions & 2 deletions custom-word-editor/src/superdoc/SuperDocEditor.tsx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
const demoMetric = (action: string, capability = 'document') => { try { window.dispatchEvent(new CustomEvent('superdoc:demo', { detail: { action, capability } })); } catch { /* Optional analytics. */ } };
import { useCallback, useEffect, useRef, useState } from 'react';
import type { RefObject } from 'react';
import { SuperDoc } from 'superdoc';
Expand Down Expand Up @@ -63,15 +64,15 @@ export function SuperDocEditor({
contentControls: true,
},
onReady: ({ superdoc: readySuperDoc }) => {
ready = true;
ready = true; demoMetric('ready');
setError('');
setSuperDoc(readySuperDoc);
},
onException: (exception) => {
// Protected edits are expected rejections, not document-open failures.
if ('code' in exception && exception.code === 'edit-rejected') return;
console.error(exception.error);
if (!ready) setError('The review document could not be opened.');
if (!ready) { demoMetric('load_failed'); setError('The review document could not be opened.'); }
},
});

Expand Down
1 change: 1 addition & 0 deletions dist-landing/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@
try {
await navigator.clipboard.writeText(dialog.querySelector('code').textContent);
copy.textContent = 'Copied';
window.dispatchEvent(new CustomEvent('superdoc:demo', {detail:{action:'build_copied',capability:'none',example:dialog.id.replace(/^build-/, '')}}));
status.textContent = 'Commands copied to clipboard.';
} catch {
status.textContent = 'Could not access the clipboard. Select the commands above and copy them.';
Expand Down
Loading
Loading