Skip to main content
The Tappd Web SDK tracks every visitor from their very first page view — even before they create an account or log in. Each anonymous visitor gets a stable identifier stored in their browser, and the moment they identify themselves, all of their previous activity is automatically merged into their user profile.

​
How Anonymous Tracking Works

1

First Visit — Anonymous ID Generated

When the SDK initializes for the first time, it generates a unique anonymousId (for example, anon_xyz789abc123) and stores it in localStorage under the key _tappd_anonymous_id. All events from this point forward are tracked against that ID.
const tappd = new TappdSDK({ appId: 'YOUR_APP_ID' });

// Anonymous ID is created automatically
const anonymousId = tappd.getAnonymousId();
console.log(anonymousId);
// Output: anon_abc123def456ghi789
2

Anonymous Events Are Captured

Every track() and trackPageView() call is recorded with the anonymousId. You don’t need to do anything special — it all happens behind the scenes.
// All of these are captured and attributed to the anonymousId
await tappd.track('page_view');
await tappd.track('button_click', { buttonId: 'cta' });
await tappd.track('add_to_cart', { productId: 'prod_123' });
3

User Identifies — Events Are Merged

When the user logs in or signs up, call identify(). The SDK automatically links all previous anonymous events to the newly identified user.
await tappd.identify({
  external_id: 'user_123',   // Required: your internal user ID
  email: 'john@example.com',
  name: 'John Doe'
});

// All previous anonymous events are now merged with user_123
4

Future Events Use the Identified User

After identify() is called, events are tracked with the identified user’s external_id. The anonymousId is retained as an alias for future matching.

​
Anonymous ID Persistence

The anonymous ID is designed to survive normal browser activity, but it resets when users explicitly clear their data.

Persists across...

  • Browser sessions
  • Tab refreshes
  • Browser restarts
  • Device reboots (same browser)

Resets when...

  • User clears browser data
  • User closes an incognito/private window
  • You call tappd.reset()
You can inspect the stored value directly: 
// The anonymous ID is stored in localStorage
localStorage.getItem('_tappd_anonymous_id');
// Returns: anon_abc123def456...

​
Use Cases

Capture product browsing and cart activity before a user creates an account, then attribute that behavior to the new user automatically.
// Anonymous user browses and adds to cart
await tappd.track('product_viewed', { productId: 'prod_123' });
await tappd.track('add_to_cart', { productId: 'prod_123' });

// User creates an account at checkout
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com',
  name: 'John Doe'
});

// Cart and browsing history are now linked to user_123

​
Getting the Anonymous ID

const anonymousId = tappd.getAnonymousId();
console.log('Anonymous ID:', anonymousId);

​
Resetting Anonymous Tracking

Call tappd.reset() when a user logs out. This clears the current identity, regenerates a fresh anonymousId, and ensures the next user on the same browser starts with a clean slate. 
function handleLogout() {
  tappd.reset();
  // A new anonymousId is generated automatically
  // The user is now anonymous again
}
Avoid calling reset() unless the user is explicitly logging out. Unnecessary resets break the anonymous-to-identified journey and prevent historical data from merging correctly.

​
Data Privacy

Anonymous tracking is built with privacy compliance in mind:
  • No personal information is stored in the anonymousId
  • Fully GDPR compliant
  • Users can opt out via standard browser privacy settings
  • Anonymous data can be deleted on request

​
Troubleshooting

Cause: The browser has localStorage disabled or blocked.Fix: Check for localStorage support before initializing the SDK:
if (typeof Storage !== 'undefined') {
  console.log('localStorage is supported — anonymous tracking will persist');
} else {
  console.log('localStorage is not supported — anonymous IDs will reset on each load');
}
Cause: identify() was called without a valid external_id, or the anonymous context was lost before identification.Fix: Always pass a non-empty external_id when calling identify(). The SDK uses this to link the anonymous session to the user record server-side.
// Correct — SDK automatically includes the anonymousId internally
await tappd.identify({
  external_id: 'user_123',  // Required: must be a valid, non-empty string
  email: 'john@example.com'
});