` with `contenteditable="true"`. It’s available synchronously after `new Quill()`. ## Cleanup [Section titled “Cleanup”](#cleanup) Quill does not have a built-in destroy lifecycle, so the WriteTrack module’s `destroy()` method must be called manually before unmounting the editor: ```ts const mod = quill.getModule('writetrack'); mod.destroy(); ``` ## TypeScript [Section titled “TypeScript”](#typescript) ```ts import type { WriteTrackModuleOptions } from 'writetrack/quill'; ``` # Slate Integration > Using WriteTrack with the Slate rich text framework WriteTrack includes a first-party Slate integration, compatible with Slate v0.94+. ## Installation [Section titled “Installation”](#installation) Install WriteTrack alongside Slate: * npm ```sh npm i writetrack slate slate-react ``` * pnpm ```sh pnpm add writetrack slate slate-react ``` * yarn ```sh yarn add writetrack slate slate-react ``` * bun ```sh bun add writetrack slate slate-react ``` ## Basic Usage [Section titled “Basic Usage”](#basic-usage) ```tsx import { useEffect, useMemo, useRef } from 'react'; import { createEditor } from 'slate'; import { Slate, Editable, withReact, ReactEditor } from 'slate-react'; import { createWriteTrackSlate } from 'writetrack/slate'; function Editor() { const editor = useMemo(() => withReact(createEditor()), []); const handleRef = useRef(null); useEffect(() => { const domNode = ReactEditor.toDOMNode(editor, editor); const handle = createWriteTrackSlate(editor, domNode, { license: 'your-license-key', }); handleRef.current = handle; return () => handle.destroy(); }, [editor]); return ( ); } ``` ## Configuration [Section titled “Configuration”](#configuration) Pass options as the third argument: ```ts const handle = createWriteTrackSlate(editor, domNode, { license: 'your-license-key', userId: 'user-123', contentId: 'document-456', metadata: { formName: 'signup' }, autoStart: true, // default }); ``` | Option | Type | Default | Description | | ----------- | ------------------------- | ----------- | ----------------------------------------------------------- | | `license` | `string` | `undefined` | WriteTrack license key | | `userId` | `string` | `undefined` | User identifier included in metadata | | `contentId` | `string` | `undefined` | Content identifier included in metadata | | `metadata` | `Record` | `undefined` | Additional metadata | | `autoStart` | `boolean` | `true` | Start tracking when created | | `wasmUrl` | `string` | `undefined` | URL to WASM binary for analysis | | `persist` | `boolean` | `false` | Enable IndexedDB session persistence (requires `contentId`) | ## Accessing Data [Section titled “Accessing Data”](#accessing-data) ```ts // Get the tracker instance const tracker = handle.tracker; // Get typing data const data = tracker?.getData(); // Check tracking status const isTracking = handle.isTracking; ``` ## Cleanup [Section titled “Cleanup”](#cleanup) Slate does not have a built-in destroy lifecycle, so `destroy()` must be called manually — typically in a React `useEffect` cleanup: ```ts useEffect(() => { const handle = createWriteTrackSlate(editor, domNode, options); return () => handle.destroy(); }, [editor]); ``` ## TypeScript [Section titled “TypeScript”](#typescript) ```ts import type { WriteTrackSlateOptions, WriteTrackSlateHandle, } from 'writetrack/slate'; ``` # TinyMCE Integration > Using WriteTrack with TinyMCE rich text editor WriteTrack includes a first-party TinyMCE integration, compatible with TinyMCE v6+. ## Installation [Section titled “Installation”](#installation) Install WriteTrack alongside TinyMCE: * npm ```sh npm i writetrack tinymce ``` * pnpm ```sh pnpm add writetrack tinymce ``` * yarn ```sh yarn add writetrack tinymce ``` * bun ```sh bun add writetrack tinymce ``` ## Basic Usage [Section titled “Basic Usage”](#basic-usage) ```ts import tinymce from 'tinymce'; import { createWriteTrackTinyMCE } from 'writetrack/tinymce'; tinymce.init({ selector: '#editor', inline: true, // recommended for full WriteTrack support setup: (editor) => { const handle = createWriteTrackTinyMCE(editor, { license: 'your-license-key', }); // Access WriteTrack data after editor init editor.on('init', () => { const data = handle.tracker?.getData(); }); }, }); ``` Inline mode recommended TinyMCE’s default iframe mode isolates the editor in a separate document context. WriteTrack’s focus and selection tracking relies on `window` and `document` listeners, which only work correctly when the editor is in the same document. Use `inline: true` in your TinyMCE configuration for full WriteTrack support. In iframe mode, keystroke and clipboard tracking will work, but focus loss detection and selection change tracking may be degraded. ## Configuration [Section titled “Configuration”](#configuration) Pass options as the second argument: ```ts const handle = createWriteTrackTinyMCE(editor, { license: 'your-license-key', userId: 'user-123', contentId: 'document-456', metadata: { formName: 'signup' }, autoStart: true, // default }); ``` | Option | Type | Default | Description | | ----------- | ------------------------- | ----------- | ----------------------------------------------------------- | | `license` | `string` | `undefined` | WriteTrack license key | | `userId` | `string` | `undefined` | User identifier included in metadata | | `contentId` | `string` | `undefined` | Content identifier included in metadata | | `metadata` | `Record` | `undefined` | Additional metadata | | `autoStart` | `boolean` | `true` | Start tracking when editor initializes | | `wasmUrl` | `string` | `undefined` | URL to WASM binary for analysis | | `persist` | `boolean` | `false` | Enable IndexedDB session persistence (requires `contentId`) | ## Accessing Data [Section titled “Accessing Data”](#accessing-data) The tracker is available after TinyMCE’s `init` event fires: ```ts tinymce.init({ selector: '#editor', inline: true, setup: (editor) => { const handle = createWriteTrackTinyMCE(editor, { license: 'your-license-key', }); editor.on('init', () => { const tracker = handle.tracker; const data = tracker?.getData(); const isTracking = handle.isTracking; }); }, }); ``` ## Manual DOM Attachment [Section titled “Manual DOM Attachment”](#manual-dom-attachment) If you prefer not to use the integration, you can attach WriteTrack directly in inline mode: ```ts import WriteTrack from 'writetrack'; import tinymce from 'tinymce'; tinymce.init({ selector: '#editor', inline: true, setup: (editor) => { editor.on('init', () => { const tracker = new WriteTrack({ target: editor.getBody(), license: 'your-license-key', }); tracker.start(); }); }, }); ``` ## Cleanup [Section titled “Cleanup”](#cleanup) The integration automatically cleans up when TinyMCE’s `remove` event fires. You can also call `destroy()` manually: ```ts handle.destroy(); ``` ## TypeScript [Section titled “TypeScript”](#typescript) ```ts import type { WriteTrackTinyMCEOptions, WriteTrackTinyMCEHandle, } from 'writetrack/tinymce'; ``` # TipTap Integration > Using WriteTrack with TipTap rich text editor WriteTrack includes a first-party TipTap extension, compatible with `@tiptap/core` v2.0+ and tested against v3.19. See [React](#react) and [Vue](#vue) examples below. ## Installation [Section titled “Installation”](#installation) Install WriteTrack alongside your TipTap packages: * npm ```sh npm i writetrack @tiptap/core @tiptap/starter-kit ``` * pnpm ```sh pnpm add writetrack @tiptap/core @tiptap/starter-kit ``` * yarn ```sh yarn add writetrack @tiptap/core @tiptap/starter-kit ``` * bun ```sh bun add writetrack @tiptap/core @tiptap/starter-kit ``` ## Basic Usage [Section titled “Basic Usage”](#basic-usage) ```ts import { Editor } from '@tiptap/core'; import StarterKit from '@tiptap/starter-kit'; import { WriteTrackExtension } from 'writetrack/tiptap'; const editor = new Editor({ element: document.querySelector('#editor'), extensions: [ StarterKit, WriteTrackExtension.configure({ license: 'your-license-key', }), ], }); // Access WriteTrack data when needed const data = editor.storage.writetrack.tracker.getData(); ``` ## Configuration [Section titled “Configuration”](#configuration) Pass options via `.configure()`: ```ts WriteTrackExtension.configure({ license: 'your-license-key', userId: 'user-123', contentId: 'document-456', metadata: { formName: 'signup' }, autoStart: true, // default }); ``` | Option | Type | Default | Description | | ----------- | ------------------------- | ----------- | ----------------------------------------------------------- | | `license` | `string` | `undefined` | WriteTrack license key | | `userId` | `string` | `undefined` | User identifier included in metadata | | `contentId` | `string` | `undefined` | Content identifier included in metadata | | `metadata` | `Record` | `undefined` | Additional metadata | | `autoStart` | `boolean` | `true` | Start tracking when editor is created | | `wasmUrl` | `string` | `undefined` | URL to WASM binary for analysis | | `persist` | `boolean` | `false` | Enable IndexedDB session persistence (requires `contentId`) | ## Accessing Data [Section titled “Accessing Data”](#accessing-data) The extension stores the WriteTrack instance in TipTap’s storage system: ```ts // Get the tracker instance const tracker = editor.storage.writetrack.tracker; // Get typing data const data = tracker.getData(); // Check tracking status const isTracking = editor.storage.writetrack.isTracking; ``` ## React [Section titled “React”](#react) ```tsx import { useEditor, EditorContent } from '@tiptap/react'; import StarterKit from '@tiptap/starter-kit'; import { WriteTrackExtension } from 'writetrack/tiptap'; const writetrack = WriteTrackExtension.configure({ license: 'your-license-key', }); function FormEditor() { const editor = useEditor({ extensions: [StarterKit, writetrack], }); const handleSubmit = () => { const data = editor?.storage.writetrack.tracker?.getData(); console.log('Typing data:', data); }; return (

Submit

); } ``` ## Vue [Section titled “Vue”](#vue) ```vue ``` ## Manual DOM Attachment [Section titled “Manual DOM Attachment”](#manual-dom-attachment) If you prefer not to use the extension, you can attach WriteTrack directly to TipTap’s editable element: ```ts import WriteTrack from 'writetrack'; import { Editor } from '@tiptap/core'; import StarterKit from '@tiptap/starter-kit'; const editor = new Editor({ element: document.querySelector('#editor'), extensions: [StarterKit], onCreate({ editor }) { const tracker = new WriteTrack({ target: editor.view.dom, license: 'your-license-key', }); tracker.start(); }, }); ``` Note The editable element is `editor.view.dom` — a `

` with `contenteditable="true"` managed by ProseMirror under the hood. ## TypeScript [Section titled “TypeScript”](#typescript) ```ts import type { WriteTrackExtensionOptions, WriteTrackExtensionStorage, } from 'writetrack/tiptap'; ``` # Licensing > License keys for production use ## Getting a License Key [Section titled “Getting a License Key”](#getting-a-license-key) You can get a license key from the [web portal](/portal/signup) or via the CLI. Run the CLI to register a free 28-day trial: ```bash npx writetrack init ``` The CLI will prompt for your email and production domain, then save the license key to `.env`: ```plaintext WriteTrack — Set up a free 28-day trial Email address: you@example.com Production domain (e.g. example.com): example.com Registering you@example.com for example.com... Done — license key saved to .env Trial expires: 3/10/2026 ``` Then pass the key when initializing: ```typescript const tracker = new WriteTrack({ target: textarea, license: process.env.WRITETRACK_LICENSE_KEY, }); ``` Tip The CLI writes `WRITETRACK_LICENSE_KEY` to your `.env` file and checks that `.env` is in `.gitignore`. If you already have a key configured, it will show the existing key instead of registering again. ## Evaluation Mode [Section titled “Evaluation Mode”](#evaluation-mode) On localhost, WriteTrack runs with full analysis enabled — no license key required. Use this to evaluate the SDK during development and testing. A license key is required for production deployments. ```typescript // Evaluation mode — localhost only, no license required const tracker = new WriteTrack({ target: textarea }); ``` # Next.js > Using WriteTrack with Next.js applications WriteTrack uses browser APIs and must run client-side only. Here’s how to integrate it with Next.js. ## App Router (Next.js 13+) [Section titled “App Router (Next.js 13+)”](#app-router-nextjs-13) Add the `'use client'` directive to components using WriteTrack: ```tsx 'use client'; import { useRef, useEffect } from 'react'; import { WriteTrack } from 'writetrack'; export function ResponseForm() { const textareaRef = useRef(null); const trackerRef = useRef(null); useEffect(() => { if (textareaRef.current) { trackerRef.current = new WriteTrack({ target: textareaRef.current }); trackerRef.current.start(); } return () => { trackerRef.current?.stop(); }; }, []); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (trackerRef.current) { const data = trackerRef.current.getData(); const events = trackerRef.current.getRawEvents(); console.log(`Captured ${events.length} events`, data.quality); } }; return (

<button type="submit">Submit</button> </form> ); } ``` ## Using the React Hook [Section titled “Using the React Hook”](#using-the-react-hook) The `writetrack/react` hook handles client-side concerns automatically: ```tsx 'use client'; import { useRef } from 'react'; import { useWriteTrack } from 'writetrack/react'; export function ResponseForm() { const textareaRef = useRef<HTMLTextAreaElement>(null); const { isTracking, tracker } = useWriteTrack(textareaRef); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (tracker) { const data = tracker.getData(); console.log('Session:', data.quality); } }; return ( <form onSubmit={handleSubmit}> <textarea ref={textareaRef} rows={10} /> <button type="submit">Submit</button> </form> ); } ``` ## Pages Router [Section titled “Pages Router”](#pages-router) For the Pages Router, either use the `'use client'` approach above, or use dynamic imports: ```tsx import dynamic from 'next/dynamic'; const ResponseForm = dynamic(() => import('../components/ResponseForm'), { ssr: false, }); export default function Page() { return <ResponseForm />; } ``` ## Server Actions [Section titled “Server Actions”](#server-actions) Send captured data to Server Actions: ```tsx 'use client'; import { useRef } from 'react'; import { useWriteTrack } from 'writetrack/react'; import { submitResponse } from './actions'; export function ResponseForm() { const textareaRef = useRef<HTMLTextAreaElement>(null); const { tracker } = useWriteTrack(textareaRef); async function handleSubmit(formData: FormData) { if (tracker) { formData.set('keystrokeCount', String(tracker.getKeystrokeCount())); } await submitResponse(formData); } return ( <form action={handleSubmit}> <textarea ref={textareaRef} name="content" rows={10} /> <button type="submit">Submit</button> </form> ); } ``` actions.ts ```typescript 'use server'; export async function submitResponse(formData: FormData) { const content = formData.get('content') as string; const keystrokeCount = formData.get('keystrokeCount') as string; // Store or process the submission await db.responses.create({ content, keystrokeCount: Number(keystrokeCount), }); } ``` ## API Routes [Section titled “API Routes”](#api-routes) Alternatively, send data to API routes: ```tsx const handleSubmit = async () => { if (!tracker) return; const data = tracker.getData(); await fetch('/api/submit', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ content: textareaRef.current?.value, typingData: data, }), }); }; ``` # Output Sinks > Route WriteTrack session data to your existing systems with .pipe() Output sinks route session data from `getData()` to external destinations like webhooks, analytics platforms, or custom backends. **Available sinks:** [Webhook](/docs/sink-webhook/) | [Datadog](/docs/sink-datadog/) | [Segment](/docs/sink-segment/) | [OpenTelemetry](/docs/sink-opentelemetry/) | [Custom](/docs/sink-custom/) ## How It Works [Section titled “How It Works”](#how-it-works) ```typescript import { WriteTrack, webhook } from 'writetrack'; const tracker = new WriteTrack({ target: textarea, userId: 'u_abc123', contentId: 'post_draft_42', }); tracker.pipe(webhook({ url: 'https://api.example.com/typing' })); tracker.start(); // Data flows to all registered sinks on each getData() call const data = tracker.getData(); // also dispatches to webhook ``` ### Data Flow [Section titled “Data Flow”](#data-flow) Sinks receive data when `getData()` is called — typically on form submit or when you’re done capturing. Every `getData()` call dispatches to all registered sinks. There is no once-only guard — if you call `getData()` three times, sinks receive data three times. ### Sink Lifecycle [Section titled “Sink Lifecycle”](#sink-lifecycle) 1. **Registration** — Call `.pipe(sink)` to register a sink. You can register multiple sinks, and `.pipe()` returns `this` for chaining. 2. **Dispatch** — When `getData()` is called, all registered sinks receive the full `WriteTrackDataSchema` object in parallel. 3. **Isolation** — Each sink runs independently. If one sink fails, the others still receive data. 4. **Error handling** — Failed sinks emit a `pipe:error` event. ```typescript // Register multiple sinks tracker .pipe(webhook({ url: 'https://api.example.com/typing' })) .pipe(webhook({ url: 'https://backup.example.com/typing' })); // Handle errors tracker.on('pipe:error', (err, sink) => { console.error('Sink failed:', err); }); ``` ## Context Fields Optional [Section titled “Context Fields ”](#context-fields) Pass context fields in the constructor to tag sessions with user and content identifiers. These flow through to `getData()` output and to all sinks. ```typescript const tracker = new WriteTrack({ target: textarea, license: 'wt_live_...', userId: 'u_abc123', // who is typing contentId: 'post_draft_42', // what they're typing into metadata: { formName: 'signup' }, // arbitrary tags }); ``` | Field | Type | Description | | ----------- | ------------------------- | --------------------------------------------------------- | | `userId` | `string` | User identifier. Passed through to sinks as-is. | | `contentId` | `string` | Content or document identifier. | | `metadata` | `Record<string, unknown>` | Arbitrary key-value pairs. Appears as `custom` in output. | These fields appear in the `metadata` section of `getData()` output: ```json { "version": "2.1.0", "metadata": { "tool": { "name": "writetrack", "version": "0.5.0" }, "targetElement": "textarea", "timestamp": "2026-02-11T12:00:00.000Z", "duration": 45000, "userId": "u_abc123", "contentId": "post_draft_42", "custom": { "formName": "signup" } } } ``` ## The WriteTrackSink Interface [Section titled “The WriteTrackSink Interface”](#the-writetracksink-interface) A sink is any object with a `send` method: ```typescript interface WriteTrackSink { send(data: WriteTrackDataSchema): Promise<void>; } ``` WriteTrack ships named sink factories for common destinations. You can also pass any object that implements this interface. ## Available Sinks [Section titled “Available Sinks”](#available-sinks) | Sink | Destination | Min version | | ------------------------------------------ | ----------------------- | --------------------------------- | | [Webhook](/docs/sink-webhook/) | Any HTTP endpoint | — | | [Datadog](/docs/sink-datadog/) | Datadog RUM | `@datadog/browser-rum >=3.0.0` | | [Segment](/docs/sink-segment/) | Segment Analytics | `@segment/analytics-next >=1.8.0` | | [OpenTelemetry](/docs/sink-opentelemetry/) | OpenTelemetry traces | `@opentelemetry/api >=1.0.0` | | [Custom](/docs/sink-custom/) | Your own implementation | — | ## Error Handling [Section titled “Error Handling”](#error-handling) Listen for errors with the `pipe:error` event: ```typescript tracker.on('pipe:error', (err, sink) => { // err: the Error thrown or rejected by the sink // sink: the WriteTrackSink that failed console.error('Sink delivery failed:', err); }); ``` Sink errors are caught via promise rejection and emitted as `pipe:error` events. Since the `send` method returns a `Promise<void>`, throwing inside an `async send()` produces a rejected promise that WriteTrack handles automatically. ## Next Steps [Section titled “Next Steps”](#next-steps) * [Webhook Sink](/docs/sink-webhook/) — Send data to any HTTP endpoint * [Datadog](/docs/sink-datadog/) — Send to Datadog RUM * [Segment](/docs/sink-segment/) — Send to Segment Analytics * [OpenTelemetry](/docs/sink-opentelemetry/) — Send as OpenTelemetry spans * [Custom Sink](/docs/sink-custom/) — Build your own sink for any backend # Session Persistence > Save and restore typing sessions across page reloads with IndexedDB By default, session data lives only in memory and is lost on page reload. Enable persistence to automatically save and restore sessions via IndexedDB. ## Setup [Section titled “Setup”](#setup) Pass `persist: true` with a `contentId` to the constructor: ```typescript const tracker = new WriteTrack({ target: textarea, contentId: 'post_draft_42', // Required with persist persist: true, }); // Wait for any prior session data to load from IndexedDB await tracker.ready; // start() will auto-resume the prior session if one exists tracker.start(); ``` When a session is resumed, all previously captured events are restored and new events are appended. The `sessionId` stays the same across resumes, and a `segment` counter in the metadata tracks how many times the session was resumed. ## How It Works [Section titled “How It Works”](#how-it-works) * **Storage key**: Sessions are stored by `contentId:fieldId`, where `fieldId` is derived from `data-writetrack-field`, `id`, or `name` on the target element. * **Page unload**: On `beforeunload`, the current session is synchronously saved to `localStorage` as a fallback (IndexedDB transactions don’t survive page unload). On the next load, this is promoted back to IndexedDB. * **`ready` promise**: Resolves when IndexedDB has loaded any prior session. Always `await tracker.ready` before calling `start()` when persistence is enabled. * **`stop()`**: Saves the session to IndexedDB. After calling `stop()`, `ready` resolves again once the save completes. * **Cleanup**: Call `clearPersistedData()` to remove the stored session for this field (e.g., after successful form submission). ## Multi-Field Forms [Section titled “Multi-Field Forms”](#multi-field-forms) Each field gets its own persisted session, keyed by `contentId:fieldId`. Give each tracked element a distinct `id` or `data-writetrack-field` attribute: ```typescript const trackers = ['#title', '#body', '#summary'].map((sel) => { const el = document.querySelector<HTMLTextAreaElement>(sel)!; const t = new WriteTrack({ target: el, contentId: 'post_42', persist: true }); return t; }); await Promise.all(trackers.map((t) => t.ready)); trackers.forEach((t) => t.start()); ``` ## Cleanup After Submission [Section titled “Cleanup After Submission”](#cleanup-after-submission) After the user submits the form, clear persisted data so the next visit starts fresh: ```typescript form.addEventListener('submit', async (e) => { e.preventDefault(); const data = tracker.getData(); tracker.stop(); await tracker.ready; // wait for final save await tracker.clearPersistedData(); // remove from IndexedDB await fetch('/api/submit', { method: 'POST', body: JSON.stringify(data) }); }); ``` ## Managing Persisted Sessions [Section titled “Managing Persisted Sessions”](#managing-persisted-sessions) For multi-document applications, use the static methods to list and delete persisted sessions without creating a WriteTrack instance: ```typescript // List all persisted sessions const sessions = await WriteTrack.listPersistedSessions(); // [{ contentId: 'doc_1', fieldId: 'default', keystrokeCount: 42, ... }] // Delete all sessions for a document (e.g., when user deletes it) await WriteTrack.deletePersistedSession('doc_1'); // Delete a specific field's session await WriteTrack.deletePersistedSession('doc_1', 'body'); ``` ## Related [Section titled “Related”](#related) * [`persist` option](/docs/api-reference/#writetrackoptions) — Constructor option reference * [`ready` promise](/docs/api-reference/#ready) — Await persistence loading * [`clearPersistedData()`](/docs/api-reference/#clearpersisteddata) — Remove stored sessions * [`listPersistedSessions()`](/docs/api-reference/#static-listpersistedsessions) — List all stored sessions * [`deletePersistedSession()`](/docs/api-reference/#static-deletepersistedsession) — Delete sessions by contentId * [Privacy & Security](/docs/privacy/) — How persistence affects data storage # Privacy & Security > What WriteTrack collects, what it doesn't, and how it fits into your security posture All processing happens client-side. The SDK makes no network requests unless you configure [output sinks](/docs/output-sinks/) — in which case data goes only where you send it. ## What WriteTrack Collects [Section titled “What WriteTrack Collects”](#what-writetrack-collects) ### Timing Data [Section titled “Timing Data”](#timing-data) * **Key press timestamps** — when keys are pressed and released * **Dwell times** — how long each key is held * **Flight times** — intervals between keystrokes * **Mouse activity timing** — time since last mouse movement (not position) * **Focus events** — when the window gains/loses focus * **Composition events** — when IME composition sequences complete (duration and character count, not the composed text) ### Event Metadata [Section titled “Event Metadata”](#event-metadata) * **Key codes** — which keys were pressed (e.g., `KeyA`, `Backspace`) * **Key names** — character or key name (e.g., `a`, `Enter`) * **Cursor position** — position in text where events occurred * **Selection ranges** — start/end positions of selections ### Content Fields [Section titled “Content Fields”](#content-fields) These fields capture actual text content: * **Clipboard content** — pasted text * **Selected text** — text that was selected * **Before/after text states** — text content around edits Caution If you store raw event data server-side, content fields may contain personally identifiable information. See [Sensitive Fields](#sensitive-fields) below. ## What WriteTrack Does NOT Collect [Section titled “What WriteTrack Does NOT Collect”](#what-writetrack-does-not-collect) * **IP addresses** — no network requests by default * **User identifiers** — no tracking or fingerprinting * **Browsing history** — no access to other tabs or pages * **System information** — no device fingerprinting * **Persistent state** — no localStorage or cookies. IndexedDB is used only when `persist: true` is explicitly enabled (see [Session Persistence](/docs/persistence/)) ## Data Lifecycle [Section titled “Data Lifecycle”](#data-lifecycle) By default, data exists only in memory for the duration of a session. Calling `start()` clears previous data. When the tracker is dereferenced, all data is garbage collected. When `persist: true` is enabled, session data is also stored in IndexedDB so it can be restored after page reloads. Call `clearPersistedData()` to remove persisted data explicitly. ## License Validation [Section titled “License Validation”](#license-validation) License keys contain embedded cryptographic signatures and are validated entirely client-side. No network requests are made during validation. Evaluation mode (no license key) works fully offline on localhost. ## Sensitive Fields [Section titled “Sensitive Fields”](#sensitive-fields) When exporting data server-side, these are the fields that may contain user-authored text: | Event type | Sensitive fields | | ---------------- | ------------------------------------ | | Keystroke events | `key`, `code` | | Clipboard events | `content`, `beforeText`, `afterText` | | Selection events | `selectedText` | | Undo/redo events | `beforeText`, `afterText` | | Session export | `session.rawText` | The `getData().quality` score and all timing fields (`timestamp`, `dwellTime`, `flightTime`) contain no user content and are always safe to store. ## Zero Runtime Dependencies [Section titled “Zero Runtime Dependencies”](#zero-runtime-dependencies) The SDK has no npm dependencies — the published package contains only first-party code. There is no transitive dependency tree and no supply chain attack surface. ## Content Security Policy [Section titled “Content Security Policy”](#content-security-policy) ### Capture Only (`getData()`) [Section titled “Capture Only (getData())”](#capture-only-getdata) The capture layer works under strict CSP with no relaxation: * No `unsafe-eval` — the SDK never uses `eval()` or `new Function()` * No `unsafe-inline` — no inline styles or scripts are injected * No workers, blob URLs, or `document.write` ### With WASM Analysis (`getAnalysis()`) [Section titled “With WASM Analysis (getAnalysis())”](#with-wasm-analysis-getanalysis) If you call `getAnalysis()` or `getSessionReport()`, the SDK lazy-loads a WebAssembly module. You must add `wasm-unsafe-eval` to your `script-src` directive: ```plaintext Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; ``` Capture-only usage (`getData()`) does not require this directive. ### connect-src [Section titled “connect-src”](#connect-src) If using the [webhook sink](/docs/sink-webhook/), add your endpoint to `connect-src`. ## Analysis Processing [Section titled “Analysis Processing”](#analysis-processing) When using `getAnalysis()`, all analysis runs **entirely client-side** in the browser via WebAssembly. No data is transmitted to Anthropic, WriteTrack, or any third party. The WASM module computes SHA-256 hashes of text content for integrity verification — the hashes are included in the analysis output but the original text is not stored or transmitted by the analysis module. # Quickstart > Capture typing behavior from a text input and send it to your server Install WriteTrack, attach it to a text input, and send captured typing data to your server. ## Installation [Section titled “Installation”](#installation) * npm ```sh npm i writetrack ``` * pnpm ```sh pnpm add writetrack ``` * yarn ```sh yarn add writetrack ``` * bun ```sh bun add writetrack ``` Tip Using React or Vue? See [React Integration](/docs/react/) or [Vue Integration](/docs/vue/) for framework-specific hooks. First-party plugins are also available for [TipTap](/docs/integrations/tiptap/), [CKEditor 5](/docs/integrations/ckeditor/), [ProseMirror](/docs/integrations/prosemirror/), [Quill](/docs/integrations/quill/), [Lexical](/docs/integrations/lexical/), [Slate](/docs/integrations/slate/), and [TinyMCE](/docs/integrations/tinymce/). ## Capture Typing Data [Section titled “Capture Typing Data”](#capture-typing-data) Attach WriteTrack to any `<textarea>`, `<input>`, or `contenteditable` element: ```typescript import { WriteTrack, webhook } from 'writetrack'; const textarea = document.querySelector<HTMLTextAreaElement>('#response-field')!; const tracker = new WriteTrack({ target: textarea }); // Session data is POSTed to your endpoint when getData() is called tracker.pipe(webhook({ url: 'https://api.example.com/writetrack' })); // Start recording before the user begins typing tracker.start(); ``` ## Collect and Submit [Section titled “Collect and Submit”](#collect-and-submit) Call `getData()` on form submit — registered sinks deliver the data automatically: ```typescript document.getElementById('response-form')!.addEventListener('submit', (e) => { e.preventDefault(); // getData() dispatches to all registered sinks const data = tracker.getData(); tracker.stop(); }); ``` WriteTrack also ships sinks for [Datadog](/docs/sink-datadog/), [Segment](/docs/sink-segment/), and [OpenTelemetry](/docs/sink-opentelemetry/). See [Output Sinks](/docs/output-sinks/) for details. `getData()` returns a structured object with the full session: ```json { "version": "2.1.0", "metadata": { "tool": { "name": "writetrack", "version": "0.7.0" }, "targetElement": "textarea", "fieldId": "response-field", "sessionId": "wt_a1b2c3d4e5f6", "timestamp": "2026-02-15T12:00:00.000Z", "duration": 8432 }, "session": { "events": [{ "type": "keydown", "key": "H", "timestamp": 1012.5 }], "clipboardEvents": [], "undoRedoEvents": [], "selectionEvents": [], "programmaticInsertionEvents": [], "compositionEvents": [], "rawText": "Hello world", "sessionStartTime": 1000.0, "sessionEndTime": 9432.0 }, "quality": { "overallScore": 0.85, "completeness": 0.92, "sequenceValid": true, "timingValid": true, "sessionDuration": 8432, "eventCount": 142, "qualityLevel": "GOOD", "issues": [], "validatedAt": "2026-02-15T12:00:08.432Z" } } ``` The `quality.qualityLevel` field (`POOR`, `FAIR`, `GOOD`, `EXCELLENT`) reflects whether enough behavioral data was captured for meaningful analysis. Short sessions or sessions with few keystrokes will score lower. ## Full HTML Example [Section titled “Full HTML Example”](#full-html-example) A complete, self-contained page using the browser bundle: ```html <form id="response-form"> <textarea id="response-field" rows="10" placeholder="Type your response..." > Submit

``` ## Cleanup [Section titled “Cleanup”](#cleanup) Always stop the tracker when you’re done to remove event listeners: ```typescript tracker.stop(); ``` Caution Failing to call `stop()` can result in memory leaks from orphaned event listeners. ## Context Fields [Section titled “Context Fields”](#context-fields) Tag sessions with identifiers that flow through to `getData()` output and all sinks: ```typescript const tracker = new WriteTrack({ target: textarea, userId: 'u_abc123', contentId: 'post_draft_42', metadata: { formName: 'signup', variant: 'B' }, }); ``` | Field | Type | Description | | ----------- | ------------------------- | ---------------------------------------------------------- | | `userId` | `string` | Who is typing. Appears in `metadata.userId`. | | `contentId` | `string` | What they’re typing into. Appears in `metadata.contentId`. | | `metadata` | `Record` | Arbitrary key-value pairs. Appears as `metadata.custom`. | ## Analyze the Session (Optional) [Section titled “Analyze the Session (Optional)”](#analyze-the-session-optional) If you have a license key (or are running on localhost), you can analyze the captured session for authenticity signals: ```typescript import { formatIndicator } from 'writetrack'; const analysis = await tracker.getAnalysis(); if (analysis) { console.log(formatIndicator(analysis.contentOrigin.indicator)); console.log(formatIndicator(analysis.timingAuthenticity.indicator)); } ``` Or combine capture data with analysis in one call: ```typescript const report = await tracker.getSessionReport(); // report.data — captured events (same as getData()) // report.analysis — authenticity analysis (same as getAnalysis()) ``` See the [Analysis guide](/docs/analysis/) for full details. ## Next Steps [Section titled “Next Steps”](#next-steps) * [Session Persistence](/docs/persistence/) — Save and resume sessions across page reloads * [Licensing](/docs/license/) — License keys for production use * [React Integration](/docs/react/) — `useWriteTrack` hook with automatic lifecycle management * [Vue Integration](/docs/vue/) — `useWriteTrack` composable for Vue 3 * [Output Sinks](/docs/output-sinks/) — Route data to webhooks, Datadog, Segment, or OpenTelemetry * [API Reference](/docs/api-reference/) — Complete method and type reference # React Integration > Using WriteTrack with React applications WriteTrack provides a React hook for easy integration with React applications. ## Installation [Section titled “Installation”](#installation) * npm ```sh npm i writetrack ``` * pnpm ```sh pnpm add writetrack ``` * yarn ```sh yarn add writetrack ``` * bun ```sh bun add writetrack ``` React is an optional peer dependency - non-React users won’t have it in their bundle. Note The React hook uses `autoStart: true` by default. The tracker begins recording as soon as the element is mounted and the ref is attached. Set `autoStart: false` if you need to control when tracking begins. ## Basic Usage [Section titled “Basic Usage”](#basic-usage) ResponseForm.tsx ```tsx import React, { useRef } from 'react'; import { useWriteTrack } from 'writetrack/react'; export function ResponseForm() { const textareaRef = useRef(null); const { tracker, isTracking } = useWriteTrack(textareaRef); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (tracker) { const data = tracker.getData(); console.log('Session data:', data); } }; return (

{isTracking && <p>Tracking keystrokes...</p>} <button type="submit">Submit</button> </form> ); } ``` ## API Reference [Section titled “API Reference”](#api-reference) ### useWriteTrack [Section titled “useWriteTrack”](#usewritetrack) ```tsx function useWriteTrack( ref: RefObject<HTMLElement | null>, options?: UseWriteTrackOptions ): UseWriteTrackReturn; ``` #### Parameters [Section titled “Parameters”](#parameters) | Parameter | Type | Description | | ------------------- | ------------------------- | ----------------------------------------------------------- | | `ref` | `RefObject<HTMLElement>` | React ref attached to the input element | | `options.license` | `string` | WriteTrack license key | | `options.userId` | `string` | User identifier included in metadata | | `options.contentId` | `string` | Content identifier included in metadata | | `options.metadata` | `Record<string, unknown>` | Additional metadata | | `options.autoStart` | `boolean` | Auto-start tracking when element mounts (default: `true`) | | `options.wasmUrl` | `string` | URL to WASM binary for analysis | | `options.persist` | `boolean` | Enable IndexedDB session persistence (requires `contentId`) | Caution Options are read once when the element mounts. Changing options after mount (e.g., a new `license` or `contentId`) will not recreate the tracker. Call `reset()` to apply new options. #### Return Value [Section titled “Return Value”](#return-value) | Property | Type | Description | | ------------ | -------------------- | ----------------------------------------- | | `start` | `() => void` | Start tracking (if `autoStart` was false) | | `stop` | `() => void` | Stop tracking | | `reset` | `() => void` | Reset tracker and clear state | | `isTracking` | `boolean` | Whether tracker is active | | `tracker` | `WriteTrack \| null` | Underlying WriteTrack instance | Tip Access the underlying `tracker` instance to call data methods like `tracker.getData()` and `tracker.getRawEvents()`. ## Examples [Section titled “Examples”](#examples) ### Manual Start/Stop [Section titled “Manual Start/Stop”](#manual-startstop) ControlledForm.tsx ```tsx import React, { useRef } from 'react'; import { useWriteTrack } from 'writetrack/react'; export function ControlledForm() { const inputRef = useRef<HTMLInputElement>(null); const { start, stop, tracker, isTracking } = useWriteTrack(inputRef, { autoStart: false, }); return ( <div> <input ref={inputRef} type="text" /> <button onClick={isTracking ? stop : start}> {isTracking ? 'Stop' : 'Start'} Tracking </button> <button onClick={() => tracker && console.log(tracker.getData())}> Get Data </button> </div> ); } ``` ### With Multiple Inputs [Section titled “With Multiple Inputs”](#with-multiple-inputs) ```tsx function MultiFieldForm() { const nameRef = useRef<HTMLInputElement>(null); const emailRef = useRef<HTMLInputElement>(null); const messageRef = useRef<HTMLTextAreaElement>(null); // Track the main content field const { tracker } = useWriteTrack(messageRef); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (tracker) { const data = tracker.getData(); console.log('Session:', data.quality); } }; return ( <form onSubmit={handleSubmit}> <input ref={nameRef} placeholder="Name" /> <input ref={emailRef} placeholder="Email" /> <textarea ref={messageRef} placeholder="Message (tracked)" /> <button type="submit">Send</button> </form> ); } ``` ## TypeScript [Section titled “TypeScript”](#typescript) ```tsx import type { UseWriteTrackReturn, UseWriteTrackOptions, } from 'writetrack/react'; ``` # Custom Sink > Build your own WriteTrack output sink for any backend Any object with a `send` method can be a WriteTrack sink. This lets you route session data to any destination without waiting for an official integration. ## The Interface [Section titled “The Interface”](#the-interface) ```typescript interface WriteTrackSink { send(data: WriteTrackDataSchema): Promise<void>; } ``` The `send` method receives the full `WriteTrackDataSchema` object and should return a `Promise<void>`. Throw or reject the promise to signal failure — WriteTrack will emit a `pipe:error` event. ## Inline Sink [Section titled “Inline Sink”](#inline-sink) The simplest approach — pass an object literal to `.pipe()`: ```typescript import { WriteTrack } from 'writetrack'; const tracker = new WriteTrack({ target: textarea }); tracker.pipe({ send: async (data) => { await fetch('/api/typing-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data), }); }, }); tracker.start(); ``` ## Sink Factory Pattern [Section titled “Sink Factory Pattern”](#sink-factory-pattern) For reusable sinks, write a factory function that returns a `WriteTrackSink`: ```typescript import type { WriteTrackSink } from 'writetrack'; function supabaseSink(options: { client: SupabaseClient; table?: string; }): WriteTrackSink { const { client, table = 'typing_sessions' } = options; return { async send(data) { const { error } = await client.from(table).insert({ user_id: data.metadata.userId, content_id: data.metadata.contentId, quality_level: data.quality.qualityLevel, duration_ms: data.metadata.duration, keystroke_count: data.session.events.length, raw_data: data, created_at: data.metadata.timestamp, }); if (error) throw error; }, }; } // Usage tracker.pipe(supabaseSink({ client: supabase })); ``` ## More Examples [Section titled “More Examples”](#more-examples) ### Firebase Firestore [Section titled “Firebase Firestore”](#firebase-firestore) ```typescript function firestoreSink(options: { db: Firestore; collectionName?: string; }): WriteTrackSink { const { db, collectionName = 'writetrack_sessions' } = options; return { async send(data) { await addDoc(collection(db, collectionName), { ...data.metadata, qualityLevel: data.quality.qualityLevel, keystrokeCount: data.session.events.length, rawData: data, createdAt: serverTimestamp(), }); }, }; } ``` ### BigQuery [Section titled “BigQuery”](#bigquery) ```typescript function bigquerySink(options: { client: BigQuery; dataset: string; table?: string; }): WriteTrackSink { const { client, dataset, table = 'typing_sessions' } = options; return { async send(data) { await client .dataset(dataset) .table(table) .insert([ { user_id: data.metadata.userId, quality_level: data.quality.qualityLevel, duration_ms: data.metadata.duration, event_count: data.session.events.length, timestamp: data.metadata.timestamp, payload: JSON.stringify(data), }, ]); }, }; } ``` ### Console Logger (for Development) [Section titled “Console Logger (for Development)”](#console-logger-for-development) ```typescript tracker.pipe({ send: async (data) => { console.log('[WriteTrack]', { quality: data.quality.qualityLevel, keystrokes: data.session.events.length, duration: `${(data.metadata.duration / 1000).toFixed(1)}s`, }); }, }); ``` ## Error Handling [Section titled “Error Handling”](#error-handling) If your `send` method returns a rejected promise (including throws inside `async send()`), WriteTrack catches it and emits a `pipe:error` event. Other sinks still receive data normally. ```typescript tracker.on('pipe:error', (err, sink) => { console.error('Custom sink failed:', err); }); ``` ## Next Steps [Section titled “Next Steps”](#next-steps) * [Output Sinks Overview](/docs/output-sinks/) — How the pipe system works * [Webhook Sink](/docs/sink-webhook/) — Pre-built HTTP sink # Datadog Sink > Send WriteTrack session data to Datadog RUM as custom actions The Datadog sink sends session data as a custom RUM action using your existing `@datadog/browser-rum` client. WriteTrack doesn’t bundle the Datadog SDK — you provide your initialized client. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) You need `@datadog/browser-rum` **v3.0.0 or later** already initialized in your application. * npm ```sh npm i @datadog/browser-rum ``` * pnpm ```sh pnpm add @datadog/browser-rum ``` * yarn ```sh yarn add @datadog/browser-rum ``` * bun ```sh bun add @datadog/browser-rum ``` ## Setup [Section titled “Setup”](#setup) ```typescript import { WriteTrack, datadog } from 'writetrack'; import { datadogRum } from '@datadog/browser-rum'; // Initialize Datadog RUM (your existing setup) datadogRum.init({ applicationId: '...', clientToken: '...', site: 'datadoghq.com', }); const tracker = new WriteTrack({ target: textarea, userId: 'u_abc123', }); tracker.pipe( datadog({ client: datadogRum, }) ); tracker.start(); ``` ## Options [Section titled “Options”](#options) | Option | Type | Default | Description | | ------------ | ------------------------ | ---------------------- | ------------------------------------------- | | `client` | `DatadogClient` | — | Initialized Datadog RUM client Required | | `actionName` | `string` | `'writetrack_session'` | Custom action name | | `tags` | `Record<string, string>` | `{}` | Extra tags to include in the action context | ## Data Mapping [Section titled “Data Mapping”](#data-mapping) The sink calls `client.addAction(actionName, context)` with the following context: | Context Field | Source | Description | | ---------------- | ------------------------ | -------------------------------------- | | `duration` | `metadata.duration` | Session duration in ms | | `keystrokeCount` | `session.events.length` | Total keystroke events | | `qualityLevel` | `quality.qualityLevel` | `POOR` / `FAIR` / `GOOD` / `EXCELLENT` | | `targetElement` | `metadata.targetElement` | Element type (e.g. `textarea`) | | `schemaVersion` | `version` | Schema version | | `userId` | `metadata.userId` | User ID (if provided) | | `contentId` | `metadata.contentId` | Content ID (if provided) | | `custom` | `metadata.custom` | Custom metadata (if provided) | Any `tags` you pass in options are merged into the context object. ## Examples [Section titled “Examples”](#examples) ### With Custom Action Name and Tags [Section titled “With Custom Action Name and Tags”](#with-custom-action-name-and-tags) ```typescript tracker.pipe( datadog({ client: datadogRum, actionName: 'typing_session_captured', tags: { team: 'content-integrity', env: 'production', }, }) ); ``` ### Querying in Datadog [Section titled “Querying in Datadog”](#querying-in-datadog) Once data flows, you can find sessions in the Datadog RUM Explorer: * **Action name**: `writetrack_session` (or your custom name) * **Filter by quality**: `@context.qualityLevel:EXCELLENT` * **Filter by user**: `@context.userId:u_abc123` ## Error Handling [Section titled “Error Handling”](#error-handling) ```typescript tracker.on('pipe:error', (err, sink) => { console.error('Datadog sink failed:', err); }); ``` The Datadog `addAction` call is synchronous under the hood. If the client throws, the error is caught and emitted as a `pipe:error` event without affecting other sinks. # OpenTelemetry Sink > Send WriteTrack session data as OpenTelemetry spans The OpenTelemetry sink creates a span for each session using your existing `@opentelemetry/api` tracer. WriteTrack doesn’t bundle the OpenTelemetry SDK — you provide your initialized tracer. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) You need `@opentelemetry/api` **v1.0.0 or later** (and a configured exporter) already initialized in your application. * npm ```sh npm i @opentelemetry/api @opentelemetry/sdk-trace-web ``` * pnpm ```sh pnpm add @opentelemetry/api @opentelemetry/sdk-trace-web ``` * yarn ```sh yarn add @opentelemetry/api @opentelemetry/sdk-trace-web ``` * bun ```sh bun add @opentelemetry/api @opentelemetry/sdk-trace-web ``` ## Setup [Section titled “Setup”](#setup) ```typescript import { WriteTrack, opentelemetry } from 'writetrack'; import { trace } from '@opentelemetry/api'; // Get your tracer (from your existing OTel setup) const tracer = trace.getTracer('writetrack'); const tracker = new WriteTrack({ target: textarea, userId: 'u_abc123', }); tracker.pipe( opentelemetry({ tracer, }) ); tracker.start(); ``` ## Options [Section titled “Options”](#options) | Option | Type | Default | Description | | ---------- | ------------ | ---------------------- | ----------------------------------------- | | `tracer` | `OTelTracer` | — | Initialized OpenTelemetry tracer Required | | `spanName` | `string` | `'writetrack.session'` | Custom span name | ## Data Mapping [Section titled “Data Mapping”](#data-mapping) The sink creates a span and sets the following attributes: | Attribute | Source | Type | Description | | ---------------------------- | ------------------------ | -------- | ------------------------ | | `writetrack.duration` | `metadata.duration` | `number` | Session duration in ms | | `writetrack.keystroke_count` | `session.events.length` | `number` | Total keystroke events | | `writetrack.quality_level` | `quality.qualityLevel` | `string` | Quality assessment | | `writetrack.target_element` | `metadata.targetElement` | `string` | Element type | | `writetrack.schema_version` | `version` | `string` | Schema version | | `writetrack.user_id` | `metadata.userId` | `string` | User ID (if provided) | | `writetrack.content_id` | `metadata.contentId` | `string` | Content ID (if provided) | The span status is set to `OK` (code `1`) on success. ## Examples [Section titled “Examples”](#examples) ### With Custom Span Name [Section titled “With Custom Span Name”](#with-custom-span-name) ```typescript tracker.pipe( opentelemetry({ tracer, spanName: 'typing.session.captured', }) ); ``` ### Viewing Traces [Section titled “Viewing Traces”](#viewing-traces) The span appears in your tracing backend (Jaeger, Zipkin, Honeycomb, Grafana Tempo, etc.) under the tracer name you configured. Filter by: * **Span name**: `writetrack.session` * **Attribute**: `writetrack.quality_level = EXCELLENT` * **Attribute**: `writetrack.user_id = u_abc123` ## Error Handling [Section titled “Error Handling”](#error-handling) The span is always ended in a `finally` block, even if setting attributes fails. Errors are caught and emitted as `pipe:error` events. ```typescript tracker.on('pipe:error', (err, sink) => { console.error('OpenTelemetry sink failed:', err); }); ``` # Segment Sink > Send WriteTrack session data to Segment Analytics as track events The Segment sink sends session data as a track event using your existing `@segment/analytics-next` client. WriteTrack doesn’t bundle the Segment SDK — you provide your initialized client. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) You need `@segment/analytics-next` **v1.8.0 or later** already initialized in your application. * npm ```sh npm i @segment/analytics-next ``` * pnpm ```sh pnpm add @segment/analytics-next ``` * yarn ```sh yarn add @segment/analytics-next ``` * bun ```sh bun add @segment/analytics-next ``` ## Setup [Section titled “Setup”](#setup) ```typescript import { WriteTrack, segment } from 'writetrack'; import { AnalyticsBrowser } from '@segment/analytics-next'; // Initialize Segment (your existing setup) const analytics = AnalyticsBrowser.load({ writeKey: 'YOUR_WRITE_KEY', }); const tracker = new WriteTrack({ target: textarea, userId: 'u_abc123', }); tracker.pipe( segment({ client: analytics, }) ); tracker.start(); ``` ## Options [Section titled “Options”](#options) | Option | Type | Default | Description | | ----------- | --------------- | ---------------------- | --------------------------------------------- | | `client` | `SegmentClient` | — | Initialized Segment analytics client Required | | `eventName` | `string` | `'WriteTrack Session'` | Custom track event name | ## Data Mapping [Section titled “Data Mapping”](#data-mapping) The sink calls `client.track(eventName, properties)` with the following properties: | Property | Source | Description | | ---------------- | ------------------------ | -------------------------------------- | | `duration` | `metadata.duration` | Session duration in ms | | `keystrokeCount` | `session.events.length` | Total keystroke events | | `qualityLevel` | `quality.qualityLevel` | `POOR` / `FAIR` / `GOOD` / `EXCELLENT` | | `targetElement` | `metadata.targetElement` | Element type (e.g. `textarea`) | | `schemaVersion` | `version` | Schema version | | `userId` | `metadata.userId` | User ID (if provided) | | `contentId` | `metadata.contentId` | Content ID (if provided) | | `custom` | `metadata.custom` | Custom metadata (if provided) | Tip If you set `userId` in WriteTrack options, Segment will include it as a property. To also set Segment’s built-in user identity, call `analytics.identify()` separately as part of your existing Segment setup. ## Examples [Section titled “Examples”](#examples) ### With Custom Event Name [Section titled “With Custom Event Name”](#with-custom-event-name) ```typescript tracker.pipe( segment({ client: analytics, eventName: 'Typing Session Captured', }) ); ``` ### Viewing in Segment [Section titled “Viewing in Segment”](#viewing-in-segment) Track events appear in the Segment Debugger with: * **Event name**: `WriteTrack Session` (or your custom name) * **Properties**: duration, keystrokeCount, qualityLevel, etc. From Segment, the data flows to any connected destination (warehouses, analytics tools, marketing platforms). ## Error Handling [Section titled “Error Handling”](#error-handling) ```typescript tracker.on('pipe:error', (err, sink) => { console.error('Segment sink failed:', err); }); ``` # Webhook Sink > Send WriteTrack session data to any HTTP endpoint The webhook sink POSTs session data as JSON to any URL. It’s the most universal sink — works with any backend that accepts HTTP requests. ## Setup [Section titled “Setup”](#setup) ```typescript import { WriteTrack, webhook } from 'writetrack'; const tracker = new WriteTrack({ target: textarea }); tracker.pipe( webhook({ url: 'https://api.example.com/writetrack', }) ); tracker.start(); ``` When `getData()` is called, the sink sends a `POST` request with `Content-Type: application/json` and the full `WriteTrackDataSchema` as the body. ## Options [Section titled “Options”](#options) | Option | Type | Default | Description | | ----------- | ------------------------ | ------- | ------------------------------------------------------------------------------- | | `url` | `string` | — | URL to POST session data to Required | | `headers` | `Record<string, string>` | `{}` | Additional headers to include | | `retries` | `number` | `0` | Number of retries on failure | | `keepalive` | `boolean` | `false` | Use `fetch` keepalive so delivery completes after page close (64 KB body limit) | ## Examples [Section titled “Examples”](#examples) ### With Authentication [Section titled “With Authentication”](#with-authentication) ```typescript tracker.pipe( webhook({ url: 'https://api.example.com/writetrack', headers: { Authorization: 'Bearer sk_live_...', }, }) ); ``` ### With Retries [Section titled “With Retries”](#with-retries) ```typescript tracker.pipe( webhook({ url: 'https://api.example.com/writetrack', retries: 2, // up to 3 total attempts }) ); ``` Retries fire immediately on non-2xx responses. The sink throws after all attempts are exhausted. ### Server-Side Handler [Section titled “Server-Side Handler”](#server-side-handler) The webhook delivers the full `WriteTrackDataSchema` object. Here’s a minimal Express handler: ```typescript app.post('/writetrack', (req, res) => { const data = req.body; console.log('Session from:', data.metadata.userId); console.log('Quality:', data.quality.qualityLevel); console.log('Duration:', data.metadata.duration, 'ms'); console.log('Keystrokes:', data.session.events.length); // Store or process the session data db.sessions.insert(data); res.sendStatus(200); }); ``` ### Error Handling [Section titled “Error Handling”](#error-handling) ```typescript tracker.on('pipe:error', (err, sink) => { console.error('Webhook delivery failed:', err.message); // e.g. "Webhook failed: 500 Internal Server Error" }); ``` ## Request Format [Section titled “Request Format”](#request-format) The webhook sends: * **Method**: `POST` * **Content-Type**: `application/json` * **Body**: The complete `WriteTrackDataSchema` object (see [Data Schema](/docs/data-schema/)) A non-2xx response is treated as a failure and triggers retries (if configured) or a `pipe:error` event. # Support > Get help integrating and using WriteTrack ## Pilot Programme [Section titled “Pilot Programme”](#pilot-programme) We’re working with a small group of early integrators. If you’re interested in hands-on integration support, get in touch. [Apply for the Pilot Programme](mailto:support@writetrack.dev) ## Contact [Section titled “Contact”](#contact) * **Technical support:** <support@writetrack.dev> * **General enquiries:** <hello@writetrack.dev> # Testing > How to test applications that use WriteTrack WriteTrack can be mocked or used directly in tests depending on your needs. ## Mocking WriteTrack [Section titled “Mocking WriteTrack”](#mocking-writetrack) For unit tests, mock the WriteTrack class to avoid DOM dependencies: ### Jest / Vitest [Section titled “Jest / Vitest”](#jest--vitest) \_\_mocks\_\_/writetrack.ts ```typescript export class WriteTrack { start = vi.fn(); stop = vi.fn(); getRawEvents = vi.fn(() => [ { key: 'h', code: 'KeyH', type: 'keydown', timestamp: 100, windowFocused: true, timeSinceLastMouse: 0, }, { key: 'i', code: 'KeyI', type: 'keydown', timestamp: 220, flightTime: 120, windowFocused: true, timeSinceLastMouse: 0, }, ]); getData = vi.fn(() => ({ version: '2.1.0', metadata: { tool: { name: 'writetrack', version: '0.5.0' } }, session: { events: [] }, quality: { qualityLevel: 'GOOD', overallScore: 0.8 }, })); getKeystrokeCount = vi.fn(() => 100); } ``` If your component uses the React or Vue hook, mock the sub-path export separately: ```typescript // __mocks__/writetrack/react.ts (or writetrack/vue.ts) export const useWriteTrack = vi.fn(() => ({ start: vi.fn(), stop: vi.fn(), reset: vi.fn(), isTracking: true, tracker: null, })); ``` your-component.test.tsx ```typescript vi.mock('writetrack'); vi.mock('writetrack/react'); // Mock the hook's sub-path export import { render, screen, fireEvent } from '@testing-library/react'; import { ResponseForm } from './ResponseForm'; test('submits form with typing data', async () => { render(<ResponseForm />); fireEvent.click(screen.getByText('Submit')); expect(screen.getByText('Submitted successfully')).toBeInTheDocument(); }); ``` ### Testing Different Scenarios [Section titled “Testing Different Scenarios”](#testing-different-scenarios) Control mock return values per test: ```typescript import { WriteTrack } from 'writetrack'; vi.mock('writetrack'); const mockWriteTrack = vi.mocked(WriteTrack); test('shows message when keystroke count is low', () => { mockWriteTrack.prototype.getKeystrokeCount.mockReturnValue(5); render(<ResponseForm />); fireEvent.click(screen.getByText('Submit')); expect(screen.getByText('Please type more before submitting')).toBeInTheDocument(); }); ``` ## Integration Testing [Section titled “Integration Testing”](#integration-testing) For integration tests, use WriteTrack with a real DOM: ### With jsdom [Section titled “With jsdom”](#with-jsdom) vitest.config.ts ```typescript export default { test: { environment: 'jsdom', }, }; ``` ```typescript import { WriteTrack } from 'writetrack'; test('captures keystrokes', () => { document.body.innerHTML = '<textarea id="input">'; const textarea = document.getElementById('input') as HTMLTextAreaElement; const tracker = new WriteTrack({ target: textarea }); tracker.start(); // Simulate keystrokes textarea.focus(); fireEvent.keyDown(textarea, { key: 'a', code: 'KeyA' }); fireEvent.keyUp(textarea, { key: 'a', code: 'KeyA' }); fireEvent.keyDown(textarea, { key: 'b', code: 'KeyB' }); fireEvent.keyUp(textarea, { key: 'b', code: 'KeyB' }); const events = tracker.getRawEvents(); expect(events.length).toBeGreaterThan(0); tracker.stop(); }); ``` ### Simulating Typing Patterns [Section titled “Simulating Typing Patterns”](#simulating-typing-patterns) Create helpers to simulate realistic typing: ```typescript async function simulateTyping( element: HTMLElement, text: string, options: { avgDelay?: number; variance?: number } = {} ) { const { avgDelay = 100, variance = 30 } = options; element.focus(); for (const char of text) { const delay = avgDelay + (Math.random() - 0.5) * variance * 2; await new Promise((r) => setTimeout(r, delay)); const code = `Key${char.toUpperCase()}`; fireEvent.keyDown(element, { key: char, code }); await new Promise((r) => setTimeout(r, 50 + Math.random() * 30)); fireEvent.keyUp(element, { key: char, code }); } } test('captures keystroke events from typing', async () => { const textarea = document.createElement('textarea'); document.body.appendChild(textarea); const tracker = new WriteTrack({ target: textarea }); tracker.start(); await simulateTyping(textarea, 'hello world', { avgDelay: 120 }); const events = tracker.getRawEvents(); expect(events.length).toBeGreaterThan(0); tracker.stop(); }); ``` ## E2E Testing [Section titled “E2E Testing”](#e2e-testing) ### Playwright [Section titled “Playwright”](#playwright) ```typescript import { test, expect } from '@playwright/test'; test('captures typing data on form submit', async ({ page }) => { await page.goto('/form'); const textarea = page.locator('#response-field'); // Type with realistic delays await textarea.focus(); await textarea.pressSequentially('This is my response content.', { delay: 100, }); await page.click('button[type="submit"]'); // Check submission succeeded await expect(page.locator('.success-message')).toBeVisible(); }); ``` ### Cypress [Section titled “Cypress”](#cypress) ```typescript describe('Response Form', () => { it('captures typing data', () => { cy.visit('/form'); cy.get('#response-field') .focus() .type('This is typed content.', { delay: 100 }); cy.get('button[type="submit"]').click(); cy.contains('Submitted successfully').should('be.visible'); }); }); ``` ## Testing Utilities [Section titled “Testing Utilities”](#testing-utilities) ### Factory Function [Section titled “Factory Function”](#factory-function) test/factories.ts ```typescript import type { KeystrokeEvent } from 'writetrack'; export function createKeystrokeEvent( overrides: Partial = {} ): KeystrokeEvent { return { key: 'a', code: 'KeyA', type: 'keydown', timestamp: Date.now(), windowFocused: true, timeSinceLastMouse: 0, ...overrides, }; } // Usage const event = createKeystrokeEvent({ key: 'Backspace', code: 'Backspace', isCorrection: true, }); ``` # Troubleshooting > Common issues and solutions when using WriteTrack ## Tracker Not Capturing Keystrokes [Section titled “Tracker Not Capturing Keystrokes”](#tracker-not-capturing-keystrokes) For rich text editors (TipTap, ProseMirror, CKEditor, Quill), make sure you’re targeting the actual editable element, not a wrapper: ```typescript // Wrong: targeting a container div new WriteTrack({ target: document.querySelector('.editor')! }); // Right: targeting the actual contenteditable element new WriteTrack({ target: document.querySelector('.editor .ProseMirror')!, }); ``` Use the framework-specific bindings (`useWriteTrack`, `WriteTrackExtension`, etc.) to avoid this — they handle element targeting automatically. If events still aren’t captured, check whether other code is calling `event.stopPropagation()` on keyboard events. *** ## POOR Session Quality [Section titled “POOR Session Quality”](#poor-session-quality) Session quality is a composite score (0–1) based on four factors: whether keystroke events exist, whether text content exists, whether timestamps are valid, and whether the session lasted more than 1 second. | Score | Quality Level | | ------ | ------------- | | >= 0.9 | EXCELLENT | | >= 0.7 | GOOD | | >= 0.4 | FAIR | | < 0.4 | POOR | A session with many keystrokes can still be FAIR or POOR if timestamps are out of order or the session duration is under 1 second. If the user pasted most of the content, there won’t be enough keystroke data for analysis. Check `tracker.getClipboardEvents()` to see if paste events dominate the session. *** ## Mobile / Swipe Typing [Section titled “Mobile / Swipe Typing”](#mobile--swipe-typing) Swipe/gesture typing produces unusual patterns — fewer distinct keydown/keyup events and different timing. This may result in FAIR quality or unexpected analysis results. Note Mobile keyboard detection is best-effort. Consider the input context when interpreting results from mobile users. *** ## React / Vue Issues [Section titled “React / Vue Issues”](#react--vue-issues) ### Ref not attached [Section titled “Ref not attached”](#ref-not-attached) The hook/composable won’t work if the ref isn’t attached to a DOM element: ```tsx // Wrong: ref not assigned to element const { tracker } = useWriteTrack(textareaRef); return ; // Missing ref={textareaRef} // Right return <textarea ref={textareaRef} />; ``` ### Component unmounted before getData [Section titled “Component unmounted before getData”](#component-unmounted-before-getdata) Retrieve data before the component unmounts: ```tsx const handleSubmit = () => { if (tracker) { const data = tracker.getData(); // Call before unmount submitForm(data); } }; ``` *** ## WASM Loading / Analysis Returns Null {#wasm-loading} [Section titled “WASM Loading / Analysis Returns Null {#wasm-loading}”](#wasm-loading--analysis-returns-null-wasm-loading) `getAnalysis()` returns `null` when the WASM module can’t be loaded. Check the browser console for a warning with details. ### Most bundlers work by default [Section titled “Most bundlers work by default”](#most-bundlers-work-by-default) Vite (production), webpack 5, Rollup, and Next.js all resolve the WASM file automatically. You shouldn’t need any configuration unless you see a console warning. ### Vite dev mode [Section titled “Vite dev mode”](#vite-dev-mode) Vite’s dev server pre-bundles dependencies, which breaks `import.meta.url`-based WASM resolution. Add this to your Vite config: vite.config.js ```js import { defineConfig } from 'vite'; export default defineConfig({ optimizeDeps: { exclude: ['writetrack'], }, }); ``` This is only needed for dev mode — Vite production builds handle WASM correctly. ### Custom WASM location [Section titled “Custom WASM location”](#custom-wasm-location) If your bundler or hosting setup doesn’t serve the WASM file at the default URL, pass `wasmUrl` pointing to the file: ```typescript const tracker = new WriteTrack({ target: textarea, wasmUrl: '/static/writetrack.wasm', }); ``` Copy the WASM file from `node_modules/writetrack/dist/writetrack.wasm` to your public/static directory. *** ## Content Security Policy [Section titled “Content Security Policy”](#content-security-policy) If your site uses a strict CSP and you’re using the [analysis module](/docs/analysis/), you’ll need to allow WebAssembly compilation. Add `wasm-unsafe-eval` to your `script-src` directive: ```plaintext Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; ``` This is narrower than `unsafe-eval` — it only permits WebAssembly compilation, not `eval()` or `new Function()`. # Verification > Verify that analysis output is authentic and untampered When a licensed WriteTrack instance runs analysis, the output is cryptographically signed. The `outputSignature` and `signedPayload` fields on [`SessionAnalysis`](/docs/api-reference/#sessionanalysis) carry this signature. You can verify it in any environment that supports the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) — Node.js 16+, modern browsers, Deno, Cloudflare Workers, etc. ## What verification proves [Section titled “What verification proves”](#what-verification-proves) A valid signature confirms two things: 1. **Authentic** — the analysis was produced by a genuine WriteTrack WASM module with a valid license key 2. **Untampered** — the analysis output has not been modified since it was generated ## Usage [Section titled “Usage”](#usage) ```typescript import { verifyAnalysisSignatureAsync } from 'writetrack/verify'; // analysis is a SessionAnalysis object from getAnalysis() or analyzeEvents() const isValid = await verifyAnalysisSignatureAsync( analysis, analysis.outputSignature ); if (isValid) { // Analysis is authentic and untampered } else { // Signature missing, invalid, or data was modified } ``` ### Server-side example [Section titled “Server-side example”](#server-side-example) A common pattern: the client captures typing and runs analysis, then sends the result to your server for verification. ```typescript // Client const analysis = await tracker.getAnalysis(); await fetch('/api/submit', { method: 'POST', body: JSON.stringify(analysis), }); // Server (Node.js, Deno, Cloudflare Workers, etc.) import { verifyAnalysisSignatureAsync } from 'writetrack/verify'; app.post('/api/submit', async (req, res) => { const analysis = req.body; const verified = await verifyAnalysisSignatureAsync( analysis, analysis.outputSignature ); if (!verified) { return res.status(400).json({ error: 'Invalid analysis signature' }); } // Process verified analysis... }); ``` Note Server-side verification provides the strongest tamper-resistance guarantee, since the verification code runs outside the user’s control. ## When signatures are present [Section titled “When signatures are present”](#when-signatures-are-present) Signatures are only generated when: * The tracker was created with a valid `licenseKey` * Analysis was run via `getAnalysis()` or `analyzeEvents()` Without a license key, `outputSignature` will be an empty string and `signedPayload` will be undefined. `verifyAnalysisSignatureAsync` returns `false` in this case. ## API [Section titled “API”](#api) ### `verifyAnalysisSignatureAsync(analysis, outputSignature)` [Section titled “verifyAnalysisSignatureAsync(analysis, outputSignature)”](#verifyanalysissignatureasyncanalysis-outputsignature) | Parameter | Type | Description | | ----------------- | ----------------- | --------------------------------------------------------- | | `analysis` | `SessionAnalysis` | The analysis object to verify | | `outputSignature` | `string` | Hex-encoded DER signature from `analysis.outputSignature` | **Returns:** `Promise<boolean>` — `true` if the signature is valid, `false` otherwise. Never throws; returns `false` on any error. ## Next Steps [Section titled “Next Steps”](#next-steps) * [Analysis](/docs/analysis/) — Run typing analysis on captured sessions * [API Reference](/docs/api-reference/) — Full method signatures and type definitions # Visualization > Pre-canned visualizations to explain the writing process WriteTrack ships chart components as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) powered by [Observable Plot](https://observablehq.com/plot/). Each chart is a custom element with Shadow DOM encapsulation, responsive sizing, and dark/light theme support. Note Observable Plot is an **optional peer dependency**. Install it alongside WriteTrack to use visualization components. * npm ```sh npm i @observablehq/plot ``` * pnpm ```sh pnpm add @observablehq/plot ``` * yarn ```sh yarn add @observablehq/plot ``` ## Quick Start [Section titled “Quick Start”](#quick-start) ```typescript import { SpeedTimeline, CompositionTimeline } from 'writetrack/viz'; // Register the custom elements (call once) SpeedTimeline.register(); CompositionTimeline.register(); // After running analysis: const analysis = await tracker.getAnalysis(); // Pass analysis data to the charts document.querySelector('wt-speed-timeline').setData(analysis); document.querySelector('wt-composition-timeline').setData(analysis); ``` ```html <!-- Add the elements to your page --> <wt-speed-timeline style="width: 100%; height: 200px;"></wt-speed-timeline> <wt-composition-timeline style="width: 100%; height: 80px;" ></wt-composition-timeline> ``` ## Available Components [Section titled “Available Components”](#available-components) Charts fall into two groups based on data source: * **[Analysis charts](/docs/analysis-charts/)** — SpeedTimeline, CompositionTimeline, RhythmHeatmap, PauseDistribution. Consume a [`SessionAnalysis`](/docs/api-reference/#sessionanalysis) from `getAnalysis()` (requires WASM). * **[Event-detail charts](/docs/event-detail-charts/)** — Sparkline, DocumentGrowth, DocumentRibbon, EditWaterfall, CorrectionsBubble. Consume raw [`WriteTrackDataSchema`](/docs/api-reference/#writetrackdataschema) from `getData()` (no WASM needed). ## Theming [Section titled “Theming”](#theming) Charts use CSS custom properties for colors, fonts, and spacing. They automatically adapt to dark/light themes via three mechanisms (in priority order): 1. **`theme` attribute** on the element: `<wt-speed-timeline theme="light">` 2. **`data-theme` attribute** on an ancestor: `<body data-theme="light">` 3. **`prefers-color-scheme`** media query (automatic) ### Custom Properties [Section titled “Custom Properties”](#custom-properties) Override these on the host element or a parent container: ```css wt-speed-timeline { --wt-color-primary: #3b82f6; /* Chart line/fill color */ --wt-color-secondary: #22d3ee; /* Accent color (paste events) */ --wt-color-text: #fafafa; /* Axis labels */ --wt-color-text-muted: #a1a1aa; /* Secondary text */ --wt-color-border: #27272a; /* Grid lines */ --wt-font-data: 'JetBrains Mono', monospace; /* Data labels */ } ``` | Property | Default (dark) | Default (light) | Used for | | ----------------------- | -------------- | --------------- | --------------------- | | `--wt-color-primary` | `#fbbf24` | `#f59e0b` | Lines, fills, bars | | `--wt-color-secondary` | `#22d3ee` | `#06b6d4` | Paste events, accents | | `--wt-color-bg` | `#111113` | `#ffffff` | Component background | | `--wt-color-surface` | `#1a1a1d` | `#f5f5f4` | Panel backgrounds | | `--wt-color-text` | `#fafafa` | `#1a1a1a` | Axis labels, text | | `--wt-color-text-muted` | `#a1a1aa` | `#6b7280` | Secondary labels | | `--wt-color-border` | `#27272a` | `#e5e5e5` | Grid lines, rules | | `--wt-font-data` | JetBrains Mono | JetBrains Mono | Chart labels | | `--wt-font-ui` | DM Sans | DM Sans | Legends, UI text | ### Sizing [Section titled “Sizing”](#sizing) Control chart dimensions with CSS custom properties. These take priority over `clientWidth`/`clientHeight`: | Property | Description | | ------------------- | ----------------------------------- | | `--wt-chart-width` | SVG width in pixels (e.g. `800px`) | | `--wt-chart-height` | SVG height in pixels (e.g. `200px`) | ### Chart-Specific Properties [Section titled “Chart-Specific Properties”](#chart-specific-properties) Individual charts expose additional custom properties for fine-grained color control: **`wt-edit-beeswarm`** — keystroke colors: | Property | Default | Used for | | ---------------------- | --------- | ----------------- | | `--wt-beeswarm-insert` | `#22c55e` | Typed keystrokes | | `--wt-beeswarm-delete` | muted | Delete keystrokes | | `--wt-beeswarm-paste` | secondary | Paste events | | `--wt-beeswarm-cut` | `#f97316` | Cut events | **`wt-corrections-bubble`** — edit type colors: | Property | Default | Used for | | -------------------- | --------- | ------------ | | `--wt-bubble-insert` | `#22c55e` | Insert runs | | `--wt-bubble-delete` | `#ef4444` | Delete runs | | `--wt-bubble-paste` | secondary | Paste events | | `--wt-bubble-cut` | `#f97316` | Cut events | **`wt-edit-waterfall`** — cut event color: | Property | Default | Used for | | ---------------- | --------- | -------------- | | `--wt-color-cut` | `#f97316` | Cut event dots | ## Declarative Usage [Section titled “Declarative Usage”](#declarative-usage) Charts also accept data via a `data` attribute (JSON string), useful for server-rendered pages: ```html <wt-speed-timeline data="..." style="width: 100%; height: 200px;"> </wt-speed-timeline> ``` The attribute value should be a JSON-serialized `SessionAnalysis` (for analysis charts) or `WriteTrackDataSchema` (for event-detail charts). ## Extract Functions [Section titled “Extract Functions”](#extract-functions) Each chart exports a standalone data-extraction function so you can use the data without the web components: ```typescript import { extractSeries, // Sparkline: raw capture → [timestamps[], speeds[]] extractSpeedData, // Speed timeline: analysis → SpeedPoint[] extractSegments, // Composition: analysis → SegmentDatum[] extractPasteMarkers, // Composition: analysis → PasteDatum[] extractRhythmPairs, // Rhythm heatmap: analysis → RhythmPoint[] extractPauseHistogram, // Pause distribution: analysis → PauseBin[] extractGrowthData, // Document growth: raw capture → GrowthPoint[] extractRibbonData, // Document ribbon: raw capture → RibbonDatum[] extractWaterfallData, // Edit waterfall: raw capture → WaterfallData extractCorrectionBubbles, // Corrections bubble: raw capture → BubbleDatum[] } from 'writetrack/viz'; ``` The `BaseChart` class is also exported for building custom chart components. # Vue Integration > Using WriteTrack with Vue 3 applications WriteTrack provides a Vue 3 composable for easy integration with Vue applications. ## Installation [Section titled “Installation”](#installation) * npm ```sh npm i writetrack ``` * pnpm ```sh pnpm add writetrack ``` * yarn ```sh yarn add writetrack ``` * bun ```sh bun add writetrack ``` Vue is an optional peer dependency - non-Vue users won’t have it in their bundle. Note The Vue composable uses `autoStart: true` by default. The tracker begins recording when the component is mounted and the template ref is attached. Set `autoStart: false` if you need to control when tracking begins. ## Basic Usage [Section titled “Basic Usage”](#basic-usage) ResponseForm.vue ```vue <script setup lang="ts"> import { ref } from 'vue'; import { useWriteTrack } from 'writetrack/vue'; const textareaRef = ref<HTMLTextAreaElement | null>(null); const { tracker, isTracking } = useWriteTrack(textareaRef); function handleSubmit() { if (tracker.value) { const data = tracker.value.getData(); console.log('Session data:', data); } } </script> <template> <form @submit.prevent="handleSubmit"> <textarea ref="textareaRef" placeholder="Type your response..." /> <p v-if="isTracking">Tracking keystrokes...</p> <button type="submit">Submit</button> </form> </template> ``` ## API Reference [Section titled “API Reference”](#api-reference) ### useWriteTrack [Section titled “useWriteTrack”](#usewritetrack) ```ts function useWriteTrack( elementRef: Ref<HTMLElement | null>, options?: UseWriteTrackOptions ): UseWriteTrackReturn; ``` #### Parameters [Section titled “Parameters”](#parameters) | Parameter | Type | Description | | ------------------- | ------------------------- | ----------------------------------------------------------- | | `elementRef` | `Ref<HTMLElement>` | Vue ref attached to the input element | | `options.license` | `string` | WriteTrack license key | | `options.userId` | `string` | User identifier included in metadata | | `options.contentId` | `string` | Content identifier included in metadata | | `options.metadata` | `Record<string, unknown>` | Additional metadata | | `options.autoStart` | `boolean` | Auto-start tracking when element mounts (default: `true`) | | `options.wasmUrl` | `string` | URL to WASM binary for analysis | | `options.persist` | `boolean` | Enable IndexedDB session persistence (requires `contentId`) | Caution Options are read once when the component mounts. Changing options after mount will not recreate the tracker. To use different options, unmount and remount the component. #### Return Value [Section titled “Return Value”](#return-value) | Property | Type | Description | | ------------ | -------------------------------- | ----------------------------------------- | | `start` | `() => void` | Start tracking (if `autoStart` was false) | | `stop` | `() => void` | Stop tracking | | `reset` | `() => void` | Reset tracker and clear state | | `isTracking` | `Ref<boolean>` | Whether tracker is active | | `tracker` | `ShallowRef<WriteTrack \| null>` | Underlying WriteTrack instance | Tip Access the underlying `tracker` instance to call data methods like `tracker.value.getData()` and `tracker.value.getRawEvents()`. ## Examples [Section titled “Examples”](#examples) ### Manual Start/Stop [Section titled “Manual Start/Stop”](#manual-startstop) ControlledForm.vue ```vue <script setup lang="ts"> import { ref } from 'vue'; import { useWriteTrack } from 'writetrack/vue'; const inputRef = ref<HTMLInputElement | null>(null); const { start, stop, tracker, isTracking } = useWriteTrack(inputRef, { autoStart: false, }); function toggleTracking() { if (isTracking.value) { stop(); } else { start(); } } </script> <template> <div> <input ref="inputRef" type="text" /> <button @click="toggleTracking"> {{ isTracking ? 'Stop' : 'Start' }} Tracking </button> <button @click="() => tracker && console.log(tracker.getData())"> Get Data </button> </div> </template> ``` ### With Multiple Inputs [Section titled “With Multiple Inputs”](#with-multiple-inputs) ```vue <script setup lang="ts"> import { ref } from 'vue'; import { useWriteTrack } from 'writetrack/vue'; const nameRef = ref<HTMLInputElement | null>(null); const emailRef = ref<HTMLInputElement | null>(null); const messageRef = ref<HTMLTextAreaElement | null>(null); // Track the main content field const { tracker } = useWriteTrack(messageRef); function handleSubmit() { if (tracker.value) { const data = tracker.value.getData(); console.log('Session:', data.quality); } } </script> <template> <form @submit.prevent="handleSubmit"> <input ref="nameRef" placeholder="Name" /> <input ref="emailRef" placeholder="Email" /> <textarea ref="messageRef" placeholder="Message (tracked)" /> <button type="submit">Send</button> </form> </template> ``` ## TypeScript [Section titled “TypeScript”](#typescript) ```ts import type { UseWriteTrackReturn, UseWriteTrackOptions } from 'writetrack/vue'; ```