Skip to main content
SuperDoc collects lightweight telemetry to track document opens for usage-based billing. Telemetry is enabled by default and runs silently in the background — it never blocks rendering or breaks your app.

​
What gets collected

Each time a document is opened or imported, SuperDoc sends a single event containing:
FieldDescriptionExample
documentIdA hashed document identifier (not the content itself)a1b2c3d4...
documentCreatedAtThe document’s original creation timestamp2024-01-15T10:30:00Z
superdocVersionThe version of the SuperDoc library1.15.0
browserInfoUser agent, hostname, and screen size{ hostname: "app.example.com", ... }
metadataCustom key-value pairs you optionally provide{ customerId: "123" }
SuperDoc does not collect:
  • Document content or text
  • User identities or personal data
  • Keystrokes, edits, or change history
  • Cookies or session tokens (credentials: 'omit')

​
How it works

  1. You open or import a document
  2. SuperDoc generates a document identifier — a hash derived from the file’s metadata (not its content)
  3. A single POST request fires to the telemetry endpoint
  4. If the request fails (network error, blocked by firewall), it fails silently
Document opened → Generate identifier hash → POST to endpoint → Done
The telemetry request is non-blocking and fire-and-forget. Your editor loads regardless of the outcome.

​
Configuration

Pass licenseKey and telemetry in your SuperDoc or SuperEditor config: 
import { SuperDoc } from 'superdoc';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  licenseKey: 'your-license-key',
  telemetry: {
    enabled: true,
  },
});

​
Options

​
licenseKey
string
Your organization’s license key. Links document opens to your account for billing. Defaults to community-and-eval-agplv3 if not provided.
​
telemetry.enabled
boolean
Enable or disable telemetry. Default: true.
​
telemetry.endpoint
string
Override the telemetry endpoint. Default: https://ingest.superdoc.dev/v1/collect. Useful for proxying through your own infrastructure.
​
telemetry.metadata
Record<string, unknown>
Custom key-value pairs included with every event. Use this to attach your own identifiers (customer ID, environment, etc.).

​
Disabling telemetry

Set enabled: false to turn telemetry off entirely: 
const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  telemetry: {
    enabled: false,
  },
});
No network requests will be made. Document metadata (GUID and timestamp) is still generated locally so files export correctly.

​
License key

The license key identifies your organization. It’s sent as an X-License-Key header with every telemetry request.
License typeKeyHow to get it
Community / evaluationcommunity-and-eval-agplv3 (default)No action needed — used automatically
CommercialYour organization keyEmail [email protected]
If you’re evaluating SuperDoc or using it under AGPLv3, you don’t need to configure a license key. The community key is applied automatically. For a commercial license key, email [email protected]. You’ll receive a key tied to your organization that unlocks usage tracking for your account.

​
How document uniqueness works

SuperDoc needs to identify each document uniquely so that opening the same file twice counts as one document, not two. This matters for accurate billing.

​
Identifier strategies

SuperDoc uses two strategies depending on what metadata the file contains: 1. Metadata hash — file already has a GUID and timestamp DOCX files created by Microsoft Word (and other tools) typically contain a unique GUID and a creation timestamp in their internal metadata (docProps/ and word/settings.xml). When both are present, SuperDoc hashes them together: 
documentId = hash(GUID | creationTimestamp)   →   "HASH-A1B2C3D4"
This is the most stable strategy. The same file always produces the same identifier regardless of content edits, because the hash is derived from metadata, not content. 2. Generated identifier — file is missing metadata Some tools produce DOCX files without a GUID or timestamp. When either is missing, SuperDoc does two things:
  1. For the current open: generates a content hash of the raw file bytes so the same file still produces a consistent identifier
  2. For future opens: generates the missing GUID and/or timestamp and embeds them into the document’s metadata
The generated metadata is saved when you export. On the next import, the file now has both a GUID and timestamp, so SuperDoc switches to the stable metadata hash automatically. 
First open:  no GUID in file → content hash used, GUID + timestamp generated
Export:      GUID + timestamp written into the file
Next open:   GUID + timestamp found → metadata hash (stable from now on)
This self-healing behavior means document identification improves automatically as files pass through SuperDoc. After one export cycle, every document gets a permanent, edit-resistant identifier.

​
Payload example

Here’s what a telemetry request looks like on the wire: 
POST https://ingest.superdoc.dev/v1/collect
Content-Type: application/json
X-License-Key: your-license-key

{
  "superdocVersion": "1.15.0",
  "browserInfo": {
    "userAgent": "Mozilla/5.0...",
    "currentUrl": "https://app.example.com/doc/123",
    "hostname": "app.example.com",
    "screenSize": { "width": 1920, "height": 1080 }
  },
  "metadata": {
    "customerId": "cust-456"
  },
  "events": [
    {
      "timestamp": "2026-02-12T14:30:00.000Z",
      "documentId": "a1b2c3d4e5f6...",
      "documentCreatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Try it: document counting demo

See document uniqueness in action. Upload a DOCX file and watch the counter — then try the steps below.
1

Upload a DOCX file

Click Upload DOCX and pick any .docx file. The counter goes to 1. SuperDoc reads the file’s internal metadata and generates a document identifier.
2

Edit the document

Make some changes in the editor — add text, delete a paragraph, change formatting. The identifier stays the same because it’s based on metadata, not content.
3

Export and re-import

Click Export & re-import. SuperDoc exports the document to DOCX and immediately re-imports it. The counter stays at 1 — same metadata, same identifier.
4

Upload a different file

Upload a second DOCX file. The counter goes to 2. Each file with distinct metadata gets its own identifier.
5

Re-upload the first file

Upload the original file again. The counter stays at 2. SuperDoc recognizes it as the same document.
The event log at the bottom shows exactly what SuperDoc sees: the identifier hash, whether a document is new or recognized, and how many times each has been opened.

​
FAQ

No. The request is non-blocking and fire-and-forget. Your editor loads and renders regardless of the telemetry outcome.
Nothing. Errors are caught silently. No retries, no queuing, no user-visible errors. Your app continues to work normally.
Yes. Set telemetry.endpoint to your proxy URL. The payload format stays the same.
Not if it has metadata. SuperDoc hashes the document’s GUID and creation timestamp, so the same file produces the same identifier every time. See How document uniqueness works above.
No. The community key (community-and-eval-agplv3) is applied automatically when you don’t provide one.