How to install
Create a project, register your site origin, and copy its public SDK write key. The SDK is currently built from source; hosted API and bundle URLs depend on your deployment.
Choose your platform
Build the SDK
The source repository uses pnpm. Run these preparation commands once; use npm for installation inside your own application.
git clone https://github.com/yosriady/untitled-analytics-sdk.git
cd untitled-analytics-sdk
pnpm install
pnpm build
pnpm packOption 1: browser script
Host dist/snippet.global.js on your site and add the following snippet once. Use your analytics API origin for the endpoint.
<script src="/snippet.global.js"
data-write-key="YOUR_SDK_WRITE_KEY"
data-endpoint="https://api.your-domain.com"
defer></script>Option 2: npm application integration
Install the locally built archive into your application. Adjust the relative path and archive name to your build.
Install command
npm install ../untitled-analytics-sdk/untitled-analytics-web-0.1.0.tgzBrowser initialization
import { createAnalytics } from '@untitled-analytics/web';
const analytics = createAnalytics({
writeKey: 'YOUR_SDK_WRITE_KEY',
endpoint: 'https://api.your-domain.com',
});
analytics.track('signup_completed', { plan: 'launch' });Client navigation
The default SDK handles the initial page and popstate. Call analytics.page() after router changes that do not trigger that event. See the Next.js and React guides for a browser singleton and route observer.
Identify after login
await analytics.identify('user_123', { email: 'person@example.com', plan: 'pro' });
analytics.clearUserId(); // on logoutIdentity stays in memory. Call identify after a fresh authenticated page load. Partial scalar traits merge by key in Tinybird. Read the identity and trait guide.
Optional cross-day attribution
Enable Attribution mode in project settings and acknowledge its data processing. Pass a callback from your consent manager; until it returns true, the SDK uses daily identity without browser storage.
const analytics = createAnalytics({
writeKey: 'YOUR_SDK_WRITE_KEY',
endpoint: 'https://api.your-domain.com',
attribution: { consent: () => consentManager.analyticsAllowed() },
});
await analytics.ready;
await analytics.identify('user_123', {
stripe_customer_id: 'cus_123', // or paddle_customer_id
});
// On consent withdrawal:
analytics.setConsent(false);The callback is supplied by your application. Browser snippets support data-attribution="true" with window.untitledAnalyticsConsent. Read the identity and consent details before enabling it. Connect a signed Stripe or Paddle webhook under project Integrations; billing customer IDs or provider metadata user_id link invoices to known profiles.
Verify installation
- Open the published site and confirm the bundle loads once.
- Inspect successful collector requests, then look for the page in project activity.
- Trigger a named test event and a client navigation.
- Confirm the expected project and event count after queue delivery.
Web Vitals and session replay are explicit opt-in additions. Review their instructions separately.
Frequently asked questions
Which key belongs in the snippet?
Use the public SDK write key for your registered site. Private MCP, Tinybird, database, and AI provider keys do not belong in the browser.
Is the package on npm?
The current SDK package is private and unpublished. Build it from source, then host its browser bundle or install the local package archive in your application.
Do I need to track the first pageview?
The SDK sends an initial pageview by default. Router-observer examples disable automatic pageviews and handle all route events explicitly to avoid duplicates.