@clocsy/track 1.1.0 (prepared release)

Website page and named-event analytics for Clocsy. This repository version uses the same v1.1 protocol as the installation script. Publication of this version and verification of the registry artifact are separate release steps; do not assume the public registry already contains it.

Setup

Use your project ID and public tracking token from My Business → Website tracking. Save the correct HTTPS website in My Business. The token identifies the site; it is not a secret.

import { init, track, setConsent } from '@clocsy/track';

init({ projectId: 'YOUR_PROJECT_ID', token: 'YOUR_TOKEN', consent: false });
// After your own site's consent flow permits analytics:
setConsent(true);
// At a completed action:
track('signup_complete');

For a bundled installation, put the dashboard's verification tag in server-rendered HTML:

<meta name="clocsy-verification" content="YOUR_TOKEN">

Alternatively add the dashboard's DNS TXT record and select Check DNS record. Initial beacons cannot certify ownership by presenting a token alone. The API checks the saved website for the challenge or verifies DNS. HTTP page verification is bounded to public IPv4 HTTPS destinations on the configured host (including its www variant), with a DNS TXT alternative for other installations.

The standalone sdk.js script is also available from the dashboard. Use only one installation method on a page. Script usage is window.clocsy.track('signup_complete'), an object method, not a callable command queue.

Behavior

• Initial page view, history push/replace and popstate navigation are supported.
• pageview() records a manual page view.
• setConsent(false) stops recording and discards pending unsent events. No cookies or persistent visitor identifiers are created. Global Privacy Control or Do Not Track disables collection.
• Browser URL queries/fragments, page titles and referrer paths are omitted. Only named UTM campaign fields are retained; obvious sensitive values and paths are redacted. Avoid personal data in site paths, campaign values and event names.
• Custom events store a short name and timestamp. Legacy metadata arguments are ignored. identify() is deprecated and sends nothing.
• Events are untrusted analytics, not verified sales revenue, user identities, confirmed business facts, payout requests or instructions to the Sales engine.
• Page/event samples are capped at 100/50. The dashboard shows the last seven days; stale samples are removed on subsequent ingestion. Aggregate lifetime counts remain. Retry IDs are retained for up to seven days, bounded to the newest 1,000 accepted IDs; this is a bounded duplicate-suppression window, not an indefinite event ledger.
• The server limits project activity to 600 accepted events/minute in addition to IP limits. It serializes writes per project so simultaneous page/custom events cannot overwrite one another.
• Up to 20 events wait in memory for installation verification. Failed verification sends no activity; another page view/event can retry verification. Reloading clears this in-memory buffer.
• No paid AI, mail, enrichment or conversion payout is triggered by analytics.

Protocol

Default API host: https://clocsy.com. apiBase overrides the origin for controlled environments.

| Operation | Endpoint | Core fields | |---|---|---| | Installation check | POST /api/sdk/ping | pid, tok, sanitized url | | Page view | POST /api/sdk/page | Above plus eventId, sanitized page/campaign/referrer fields | | Named event | POST /api/sdk/event | Above plus eventId, event |

Requests omit credentials/cookies. The browser origin and URL must match the configured website. Origin validation mitigates unrelated browser installations; a public browser token is not a cryptographic signature against a server forging requests.

Legacy /verify, /pageview, /track route aliases and projectId/token aliases are accepted by the API, but current clients send the canonical names. Personal identity requests return unsupported.

Verification

Run the repository SDK route, client-contract and proof tests, and build this package. Before publication/deployment acceptance, verify the built artifact on a controlled HTTPS site, including initial page, SPA navigation, custom events, consent, reload and dashboard refresh. Verify the published package tarball independently after publication.