Early access. The Web SDK is available on request during early access: you get the browser bundle (
snippet.global.js) and a local package archive. The repository is private until launch. To ask for it, use the Contact page of the ManaLens website (/contact). The source will be published at launch.Configuration
Local testing and environments
The SDK tracks every host, includinglocalhost. This is different from Formo’s SDK, which skips localhost by default. Events from localhost reach the collector only when the project domain allows them (for example a project with the domain localhost).
To send nothing from some environments, use the tracking option:
tracking: false is the same as disabled: true: no events and no browser storage.
Logging
Logging is off by default. Turn it on withlogger:
levels, all levels print. The levels list is matched exactly: ['warn'] prints warnings only, not errors. With the snippet, data-debug="true" prints all levels.
Logs never contain property values, traits, user IDs or keys.
Batching
The SDK keeps events in memory (never in browser storage) and sends them in batches: whenbatchSize events wait, every flushIntervalMs, when the page hides (with keepalive), and at once after identify(). flush() sends now.
- Server errors (408, 429, 5xx): the batch is sent again, at most
retryCounttimes. Between attempts, the SDK waits 1 s, 2 s, 4 s and so on up to 30 s, with jitter, or longer when a429hasRetry-After(up to 60 s). - Network errors (offline): the events wait in memory and are not counted as retries.
- Other 4xx (for example
401for a wrong key, or403for a page that is not on the project domain): the batch is dropped. - Queue limit: above
maxQueueSizebytes, the oldest events are dropped.
errorHandler gets an error each time events are dropped: refused by the collector, or a server error after retryCount retries. The error is a SendError with status (the HTTP status) and dropped (the number of events). Network errors do not call it. A refused batch is dropped and is not sent again. In SDK versions after 0.4.0, the error has reasons (the reason codes of the collector, for example SESSION_ID_REQUIRED) and the message has the text of the collector.
Ready callback
ready runs once, at the end of createAnalytics(), with the instance. It runs also when the SDK is disabled. An error in it is caught and logged.
window.untitledAnalytics, then dispatches the untitled-analytics:ready event on window (event.detail is the instance). Add the listener before the snippet runs, or check window.untitledAnalytics first:
Excluding traffic
The SDK never sends a full query string or a fragment: page URLs are origin and path, and the referrer is an origin. It reads only the campaign parameters. Use
excludeQueryParams to keep one of them out of every event, for example ['ref'].
An identify() on an excluded page is held and sent with the first event on an allowed page. A campaign from an excluded landing page is not carried.
Consent
Consent mode is off by default: the SDK stores a persistent visitor ID at once. Sites that need consent before analytics storage setrequireConsent: true (snippet: data-require-consent="true"). Then, until setConsent(true):
- the SDK reads and writes no cookies or localStorage;
- page and track events are sent without
anonymous_id,session_idanduser_id; - an
identify()call is held in memory and sent when consent is granted.
setConsent(false) clears all identity storage and removes identity from queued events. optOut() drops queued events, clears identity and stores an opt-out flag for one year. optIn() removes the flag. See Consent.
Cross subdomain tracking
With apex cookies, every subdomain can read the IDs. Use
false if you host untrusted content on a subdomain.
Referrals and campaign capture
From the landing URL, the SDK reads only these query parameters:- UTM:
utm_source,utm_medium,utm_campaign,utm_term,utm_content,utm_id,utm_source_platform,utm_creative_format,utm_marketing_tactic - Referral code:
ref, orreferralorreferral_code(sent asref) - Ad click IDs: Google
gclid,gbraid,wbraidandgad_source; Metafbclid; Microsoftmsclkid; TikTokttclid; Xtwclid; LinkedInli_fat_id; Redditrdt_cid; SnapchatScCid
android-app://com.google.android.youtube) when an Android app opened the link. From the values, it adds paid_source (the ad network, or paid_utm for a paid utm_medium) and click_id (the first click ID found). gad_source marks Google but is not a click ID. Values that are too long or have unsafe characters are dropped.
The SDK keeps the campaign in memory across route changes and attaches it to later events. A new tagged landing replaces it, and it is cleared at UTC midnight. It is not written to browser storage. See attribution.
Single-page apps and client routing
page(properties?) sends a page view of the current page. Without properties, it sends nothing when the path and query are the same as the last page view. With properties, it always sends.
With autoPageviews: true (the default), the SDK sends a page view:
A page view that waits is sent at once when the page hides (
pagehide, or the tab goes to the background), so it is not lost.
With autoPageviews: false (snippet: data-auto-pageviews="false"), the SDK sends no page view by itself, not even on the first load. Call page() on each route change, including the first page.
Frameworks with client routing
- Astro View Transitions (
<ClientRouter />): adddata-auto-pageviews="false"to the snippet and callwindow.untitledAnalytics.page()on everyastro:page-loadevent. Astro fires it after the first load and after each navigation (links, back and forward), when the new title is in place. Pages without<ClientRouter />do not fireastro:page-load: send their page view on the windowloadevent. See thewith-astroexample in the ManaLens examples repository. - Next.js App Router: set
autoPageviews: falseand callpage()whenusePathname()oruseSearchParams()changes. See the tab below and thewith-nextexample in the examples repository. - Other routers: the automatic page views work without code. If your router has a “page loaded” event, you can also use
autoPageviews: falseand callpage()from that event.
page() call for the same path and query sends nothing, so a duplicate listener does not count a page twice.
- Astro
- Next.js App Router
- React Router
src/layouts/Base.astro
<head>. The router keeps a head script that is the same on the next page, so the listener is added once.Snippet attributes
The snippet reads its options fromdata- attributes on its <script> tag. The instance is window.untitledAnalytics.
Other options (
tracking, batchSize, flushIntervalMs, retryCount, maxQueueSize, ready, errorHandler) need the npm package.
App context
A game that runs in a browser or in Electron can set theapp option. Then every event carries context.app with context.page. The events stay web events, and the App filters and breakdowns (build, version, platform, storefront, engine) work for them. The Game KPIs and Game health dashboard templates count them as game events. Web events need a page URL on your project domain, a subdomain, or a host in the project’s allowed origins. So this works on your own domain and in a game portal build once the portal host is in the list (see Game portals). See Browser and Electron games.
With the snippet, use the data attributes:
console.warn. The device, OS and browser still come from the browser user agent.
Game portals
A web game on a portal (itch.io HTML5, CrazyGames and similar) runs in an iframe on the portal’s own host, for examplehtml-classic.itch.zone. The web SDK works there once that host is in Project settings > Allowed origins:
- Open Project settings > Allowed origins. A new project already lists
*.itch.zone(itch.io). For another portal, click its preset (Add CrazyGames adds*.crazygames.com) or type the host, then Save allowed origins. - Load the SDK in the game’s HTML page as on any site, and set the
appoption (platform: 'web') so the App filters and the game dashboards count the events. - Upload the build to the portal. The collector accepts a web event whose page URL is on an allowed host and refuses any other host with
403(Page domain does not match project).
https://creator.itch.io. A page on an itch.io game host with no referrer at all is labelled as a referral from https://itch.io (channel_type Referrers), so it does not show as Direct. For traffic attribution, use the itch.io integration for purchases and short links for the links you post, since a short link records the click and its campaign before the player reaches the portal.
Portal rules on analytics. Check the portal’s rules before you add any analytics SDK:
- itch.io: the HTML5 docs (itch.io/docs/creators/html5) ask that requests to another domain use HTTPS; they set no rule on analytics SDKs.
- Poki: external requests are blocked by default. Analytics providers (including an in-house one) are reviewed case by case, Google products such as Google Analytics cannot be approved, and a game that sends data out needs an in-game privacy policy (external resources policy, requirements). Poki’s docs do not name the host that serves game builds, so there is no preset; ask Poki for it before you add it by hand.
- CrazyGames: runs a game on more than one
crazygames.comorigin (sitelock), so the preset is*.crazygames.com. Its docs recommend ByteBrew for advanced analytics and do not forbid other analytics SDKs. A game that collects personal data beyond the CrazyGames SDK events should show a Terms and Conditions or Privacy Policy notice to new players (requirements, technical requirements).
Proxy
Ad blockers can drop requests to an analytics host. Serve the script and send events through your own domain, then setendpoint (snippet: data-endpoint) to your path. See Reverse proxy.
Methods
Sessions
Each event with an identity has asession_id: a UUID that is never the anonymous_id. A new session starts after 30 minutes without an event. In SDK versions after 0.4.0, a new session also starts when the session is 24 hours old, so a page that stays active for days gets a new session each 24 hours. Before consent, an event has no anonymous_id and no session_id, and it is in no session.
The collector refuses an event that has an anonymous_id and no session_id, or a session_id equal to the anonymous_id (see the session ID contract). The SDK always sends a correct pair, so this refusal shows a modified or broken client.
To put a server event (for example a purchase) in the visitor’s session, send getAnonymousId() and getSessionId() to your backend and put them on the event: see send the client’s session ID. A read of getSessionId() does not count as activity.
Track custom events
- Event names: up to 128 characters. Use one naming style, such as
snake_case, and keep names stable. - Properties: a flat object of string (up to 1024 characters), number, boolean or
nullvalues. - Revenue: add a numeric
revenueproperty to count it in the Revenue metric.
signup_completed or purchase, not every click or keystroke.
Identify users
Players who come from your game
When a game made with the Godot SDK opens your website withlink_url(), the URL has a ua_hid parameter. On load, the SDK removes it from the address bar and sends one identity_handoff event. Reports then count the browser and the game install as one player. No setup is needed. In consent mode, the event waits for setConsent(true).
Browser storage
The SDK stores a persistent first-partyanonymous_id, a session_id and, after identify(), a user_id. See what we collect for keys and lifetimes.
Examples and source
The SDK repository (private during early access) has a local example (pnpm example) that runs against a local collector. The ManaLens examples repository (private for now) has complete projects: with-html (the snippet), with-astro (Astro View Transitions), with-next (Next.js App Router) and with-threejs (a browser game served from your own domain; on itch.io and other portals, send app events instead).