Identity & Tracking

Anonymous vs. identified users

The SDK tracks every visitor, even before they log in.

Anonymous tracking

On first load, the SDK creates a browser-local anonymous ID. It is:

• sent with access checks
• attached to tracked events
• persisted across page loads and sessions

Identifying users

There are two ways to identify a user:

1. Authenticated identity (recommended)

Use the built-in customer auth for cryptographically verified identity:

import { init, login, register, checkAccess } from '@latch/sdk';

init({ apiKey: 'pk_...', apiUrl: 'https://your-latch-api' });

// Register a new customer
const { customer } = await register('[email protected]', 'securepass123', 'Jane');

// Or log in an existing customer
const { customer } = await login('[email protected]', 'securepass123');

// Access checks now automatically include the verified JWT
const access = await checkAccess();

When authenticated, the SDK attaches the JWT as a Bearer token to access checks. The API verifies the token cryptographically rather than trusting a client-side userId.

See the Authentication page for the full auth API.

2. Manual identity (simple, unverified)

For simpler setups where identity spoofing is not a concern, call identify():

import { identify } from '@latch/sdk';

identify('user_123');

Once identified, access checks include userId and subscription lookups can succeed for that user.

Note

identify() does not create a customer record in Latch. It only changes what the SDK sends. The userId is trusted without verification. For secure identity, use the customer auth methods above.

Pre-setting identity

import { init } from '@latch/sdk';

init({
  apiKey: 'pk_...',
  apiUrl: 'https://your-latch-api',
  userId: getCurrentUserId(),
});

Resetting identity

import { resetIdentity } from '@latch/sdk';

resetIdentity();

resetIdentity() clears userId and falls back to the browser’s stored anonymous ID.

It does not rotate the anonymous ID or reset meter history.

Event tracking

Pageviews

init() automatically queues an initial pageview. For SPAs, call trackPageview() after client-side navigation.

import { trackPageview } from '@latch/sdk';

trackPageview({ section: 'technology' });

Captured fields include url, path, title, and referrer.

Custom events

import { trackEvent } from '@latch/sdk';

trackEvent('article_view', {
  slug: 'my-premium-article',
  premium: true,
});

Batching

The SDK flushes queued events:

• every 5 seconds
• when the queue reaches 20 items
• on beforeunload

If a flush fails, events are placed back in the queue for retry.