✦ Now with returning players and D1, D7, D30 retention
☰
All featuresAttributionRetentionAnalytics OverviewIntegrationsPricingDocumentationComparisonsFree toolsBlogGlossary
SDK GUIDE

How to install

Create a project, register your site origin, and copy its Publishable key. During early access, the SDK is available on request. Hosted API and bundle URLs depend on your deployment.

Choose your platform

Get the SDK

The SDK is not on npm yet. During early access, the SDK is available on request. Contact us to get the browser bundle (snippet.global.js) and a local package archive. The source will be published at launch.

Option 1: browser script

Host 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-publishable-key="YOUR_PUBLISHABLE_KEY"
  data-endpoint="https://api.your-domain.com"
  defer></script>

Option 2: npm application integration

Install the SDK archive into your application. Adjust the relative path and archive name to your build.

Install command

npm install ../manalens-js/manalens-web-0.1.0.tgz

Browser initialization

import { createAnalytics } from '@manalens/web';

const analytics = createAnalytics({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  endpoint: 'https://api.your-domain.com',
});
analytics.track('signup_completed', { plan: 'launch' });

Client navigation

By default the SDK sends the first page view, a page view when pushState or replaceState changes the path, and a page view after back and forward. After back and forward, it waits until the framework changes the title (at most 1 second), so the title is the new page. page() without properties sends nothing when the path and query did not change. For a framework with its own page-load event, such as Astro View Transitions, add data-auto-pageviews="false" to the snippet (or autoPageviews: false) and call analytics.page() on that event, including the first page. See the web SDK guide for a browser singleton.

Identify after login

await analytics.identify('user_123', { email: 'person@example.com', plan: 'pro' });
analytics.reset(); // on logout

The SDK keeps a random anonymous ID in a first-party cookie and adds user_id to later events after identify. Partial scalar traits merge by key in Tinybird. Read the identity guide.

Optional consent mode

If your site needs consent before analytics storage, start the SDK in consent mode. Until you call setConsent(true), the SDK stores nothing and sends events with no visitor ID. Those events count toward event totals but not visitors.

const analytics = createAnalytics({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  endpoint: 'https://api.your-domain.com',
  requireConsent: true,
});
// When your consent manager allows analytics:
analytics.setConsent(true);
// On consent withdrawal:
analytics.setConsent(false);

Browser snippets support data-require-consent="true", data-auto-pageviews="false" and data-debug="true", and expose window.manalens. Read the identity and consent details. Connect a signed Stripe or Paddle webhook under project Integrations; billing customer IDs or provider metadata user_id link invoices to known profiles.

Server-side events

Send track and identify events from your backend to the same POST /v0/events endpoint, with channel: 'server' and the project's Secret key. Owners and admins create the Secret key in project Settings. Keep it on your server only: never put it in a page or a game build. To get country and device, send the player's IP and user agent in context.ip and context.user_agent. The collector does not store them.

curl -X POST https://api.your-domain.com/v0/events \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"events":[{"channel":"server","type":"track","event":"purchase_completed","user_id":"player_123","properties":{"sku":"dlc_1"},"context":{"ip":"203.0.113.7","user_agent":"Mozilla/5.0 ..."}}]}'

Avoid ad blockers

Ad blockers can drop requests to an analytics host. Serve the script and send events through your own domain with a reverse proxy, then set the endpoint to your own path, for example data-endpoint="https://yourdomain.com/mana". The SDK posts to that endpoint plus /v0/events. Read the proxy guide for Next.js, Vercel, Cloudflare Worker, and nginx examples.

Verify installation

  1. Open the published site and confirm the bundle loads once.
  2. Inspect successful collector requests, then look for the page in project activity.
  3. Trigger a named test event and a client navigation.
  4. Confirm the expected project and event count after queue delivery.

Frequently asked questions

Which key belongs in the snippet?

Use the Publishable key of your registered site. It is safe to ship in a page or a game build. Secret keys, API keys, and Tinybird, database, and AI provider keys do not belong in the browser.

Is the package on npm?

Not yet. During early access, the SDK is available on request. You get the browser bundle and a local package archive. The source will be published at launch.

Do I need to track the first pageview?

The SDK sends an initial pageview by default. Router-observer examples disable automatic pageviews (autoPageviews: false, or data-auto-pageviews="false" on the snippet) and call page() on each route, including the first.