Read the signal clearly.

1. 01

   Create a project

   Open the dashboard, choose New project, give it a recognisable product name, then select the first source platform.

2. 02

   Configure the source

   For web, add the production domain and any allowed alternates. For apps or extensions, add the exact bundle, package, add-on, or extension identifier.

3. 03

   Install the collector

   Copy the source-specific setup shown in Settings → Data sources. App and extension collection must receive an explicit consent state.

4. 04

   Verify the signal

   Generate a test visit or event. The source rail and Settings show the last event plus accepted and rejected ingestion counts. Realtime and headline readings update in place while the tab is visible.

The source signal rail beneath the dashboard navigation shows every configured platform, its last signal, and the active source filter. Select a source to scope compatible reports; choose all sources for a project-wide view. Acquisition, SEO, and heatmaps only appear when the project contains a web source.

Website

Put the script before the closing </head> tag. Replace the host and project ID with the values shown by your source. The legacy endpoint and existing snippets remain supported.

<script
  defer
  src="https://YOUR-MU-HOST/script.js"
  data-website-id="PROJECT_ID"
></script>

The web collector is cookie-free and storage-free. It records page views and privacy-safe engagement signals; it does not need an app write key in page markup.

Browser extensions

Bundle the TypeScript SDK into the extension worker. Popup, options, side-panel, and content-script clients proxy to that worker, which owns the IndexedDB queue. No extra storage permission is required.

const mu = await MuExtension.configure({
  endpoint: "https://YOUR-MU-HOST",
  writeKey: "mu_…",
  appId: chrome.runtime.id,
  collectionEnabled: consent.analytics,
  runtime: chrome.runtime,
  incognito: chrome.extension.inIncognitoContext,
});

await mu.capture("upgrade_clicked", { plan: "pro" });

Mobile and cross-platform apps

Mobile queues flush every 10 seconds or 20 events, flush again when the app backgrounds, retry with exponential jitter, and cap themselves at 1,000 events or 5 MB. The default foreground inactivity boundary is five minutes.

Every event also has a client-generated event ID, occurrence time, anonymous install ID, optional external user ID, session ID, platform, SDK, environment, and optional release, screen, surface, OS, device, browser, locale, and timezone context.

Standard SDK surface

curl https://YOUR-MU-HOST/api/v1/batch \
  -H "Authorization: Bearer mu_…" \
  -H "Content-Type: application/json" \
  --data '{
    "sentAt": 1786000000000,
    "events": [{
      "eventId": "evt_01JEXAMPLE",
      "kind": "event",
      "name": "upgrade_clicked",
      "occurredAt": 1786000000000,
      "anonymousId": "install_01JEXAMPLE",
      "sessionId": "session_01JEXAMPLE",
      "context": {
        "platform": "ios",
        "sdk": "swift",
        "environment": "production",
        "appId": "studio.selfhood.example",
        "appVersion": "2.4.0"
      },
      "properties": { "plan": "pro" }
    }]
  }'

• reset() ends the identified context and begins a fresh anonymous identity.
• setCollectionEnabled(false) clears the durable queue, persistent install identity, and identified user.
• User properties describe the person; event properties describe one action. Secret-like and common PII property keys are removed.
• Settings can delete a person and their events from an external user ID without storing that raw external ID in Mu.

Explore

Choose event totals, unique users, sessions, revenue, or average duration. Filter by event, source, platform, environment, app version, and typed property values; then add up to two breakdown dimensions. Save a useful configuration as a report so it can be reopened without rebuilding the query.

Date ranges use the project timezone. Event occurrence time—not upload time—places offline events in a report, subject to clock and retention validation.

Built-in filtering removes known bots, referrer spam, and data centre traffic from web readings. Allowed domains are configured per source; add preview or alternate domains deliberately rather than weakening origin validation.

• Releases shows adoption, sessions, errors, and crash-free sessions by application or extension version and build.
• Stability groups matching errors from type, scrubbed message, and a normalized raw-stack fingerprint. Mark groups open, resolved, or ignored as work progresses.
• Timings cover cold/warm app start, screen duration, and manually captured work, with percentile summaries instead of misleading averages alone.
• Abnormal-termination markers improve crash-free session estimates when the platform cannot submit a crash immediately.

Settings → Data sources shows request, accepted, and rejected totals for the last 24 hours plus the last event time. Requests with only duplicates are healthy and count as processed; rejected events point to validation, identity, source, time, or rate-limit problems.

• Extensions and apps require an explicit collection state at initialization. Disabled collection performs no network or persistent-identity writes.
• Public share links expose aggregate reports only. User profiles, raw events, write keys, error stacks, source health, and settings remain private.
• CSV and JSON exports contain up to 50,000 privacy-scrubbed events. External identity hashes and raw error stacks are omitted.
• A project retention window rejects data older than its policy. Run cleanup in Settings to remove existing expired events, sessions, source-health windows, and inactive identities.

Production libSQL/Turso uses the database URL and auth token in the server environment. Keep JWT_SECRET and preferably a dedicated ANALYTICS_IDENTITY_SECRET stable across deploys: changing the identity secret changes future hashes and breaks continuity with existing people.

Send POST /api/v1/batch with Authorization: Bearer WRITE_KEY. The response reports accepted, duplicates, a rejected-event list with reason codes, and serverTime. Event IDs are deduplicated per source, so retry the same batch instead of generating new IDs.

POST /api/e, existing web snippets, dashboard URLs, share URLs, and the current stats API remain available through compatibility adapters.