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: host the browser script

Copy snippet.global.js to your website’s public assets. Add the script once before the closing body tag or in your shared document template. Replace both placeholders; the Publishable key is public and scoped to your site.

HTML script tag

<script src="/snippet.global.js"
  data-publishable-key="YOUR_PUBLISHABLE_KEY"
  data-endpoint="https://api.your-domain.com"
  defer></script>

Track a custom event

The browser script exposes window.manalens after loading. Send an event when a player completes an action, such as a click on your Steam button or a finished level in a browser build.

After the script has loaded

window.manalens?.track('steam_button_clicked', { placement: 'hero' });

Option 2: integrate with npm

Install the archive produced by pnpm pack into your application. Adjust its local path and version to the file you built.

Run in your application directory

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

Initialize in browser code

Create one instance for the application. Page views are automatic by default: the first page, pushState and replaceState path changes, and back and forward (sent after the router changes the title). For a router with its own page-load event, set autoPageviews: false and call page from that event, or dispatch manalens:navigate after the new page shows.

Browser initialization

import { createAnalytics } from '@manalens/web';
const analytics = createAnalytics({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  endpoint: 'https://api.your-domain.com',
});
analytics.track('level_completed', { level: 3 });

Verify pageviews and custom events

Register your actual site origin and use its Publishable key. The endpoint is your deployed API origin, not a Tinybird URL. Open the published site, check that the bundle loads, and inspect successful collector requests and the project activity feed. Collection is queued, so allow for delivery latency.

Trigger a second page and a custom event. Confirm one expected pageview per navigation. Disable duplicate analytics installations. If your game has accounts, identify a player only after login and clear the SDK user ID at logout. Review campaign fields and properties on a non-sensitive page first.

Frequently asked questions

Is the npm package public?

No. The SDK is not on npm yet. During early access, the SDK is available on request from the contact page. You get a local package archive and the browser bundle. Install the archive in your application, or host the browser bundle. The source will be published at launch.

Which endpoint do I use?

Use your deployed analytics API origin, such as https://api.your-domain.com. Do not use a Tinybird URL. Register your actual site origin and use the Publishable key for that site. The Publishable key is public and safe in browser code. Never put Tinybird or database credentials in browser code.

How do I check installation?

Open the published site and check that the bundle loads. Inspect the collector requests and the project activity feed. Then trigger a second page and a custom event, and confirm one pageview per navigation. Collection is queued, so allow for some delivery delay. Disable any duplicate analytics installations.

Do I need to send pageviews myself?

Usually not. Page views are automatic by default. The SDK sends the first page, pushState and replaceState path changes, and back and forward navigation. For a router with its own page-load event, set autoPageviews to false and call page from that event. You can also dispatch manalens:navigate after the new page shows.

Sources and implementation