User Identification

Identify users to connect anonymous sessions with known profiles for deeper insights.

By default, Vemetric will track the data of your users anonymously and without using cookies. In order to do that, we use a combination of the IP address, the user agent and a daily rotating Salt as a hashed id for each user. That also means that on the following day, anonymous users will count as new users.

But as Vemetric is also a product analytics tool, it enables you to identify users, which allows you to connect anonymous activity to a known user once he is authenticated.

When to identify or reset users

Important: When implementing user identification, you should check the user’s authentication state on initial page load and call the appropriate function:

If a user is logged in: Call identify with their user ID
If a user is not logged in: Call resetUser to ensure they’re tracked anonymously

This ensures that the user’s identity state is correctly synchronized with Vemetric from the moment they land on your site. Without this check, returning logged-in users might be tracked as anonymous users until they perform an action that triggers identification.

Identify users

To identify users, you can use the identify function from one of our Frontend SDKs. When calling it you need to provide a unique identifier for the user. We highly recommend using the primary id of your user in your database.

You should call identify on initial page load, as soon as you know the user is logged in. If your page doesn’t reload on authentication state changes (e.g. in a Single Page Application), you should also call identify when the authentication state changes from anonymous to authenticated.

This will create a user profile and from then on, all tracked events will be associated with the identified user. Also existing events sent from the anonymous user session, will be merged with the identified user.

By default, no cookies will be used event after identifying a user. In case you have the consent of your authenticated users, you can pass allowCookies: true to the identify function. This will make the event tracking for identified users more accurate. We also highly recommend to use a proxy in this case, to ensure a first-party cookie is being used.

To identify users with the HTML script, you can call the identify function like this:

await window.vmtrc('identify', {
  identifier: 'your-user-id', // we recommend to use the user's primary id in your database
  displayName: 'John Doe', // optional, will be used to display the users' name in Vemetric

  // If you have the consent of your authenticated users, you can allow cookies to ensure smoother tracking
  allowCookies: true,
});

Look at the HTML script docs for a detailed explanation of the available parameters. For example you can also pass a data object to set additional attributes for the user.

To identify users with the JavaScript SDK, you can call the identify function like this:

import { vemetric } from '@vemetric/web';

await vemetric.identify({
  identifier: 'your-user-id', // we recommend to use the user's primary id in your database
  displayName: 'John Doe', // optional, will be used to display the users' name in Vemetric

  // If you have the consent of your authenticated users, you can allow cookies to ensure smoother tracking
  allowCookies: true,
});

Look at the JavaScript SDK docs for a detailed explanation of the available parameters. For example you can also pass a data object to set additional attributes for the user.

To identify users in React, you can call the identify function like this:

import { vemetric } from '@vemetric/react';

await vemetric.identify({
  identifier: 'your-user-id', // we recommend to use the user's primary id in your database
  displayName: 'John Doe', // optional, will be used to display the users' name in Vemetric

  // If you have the consent of your authenticated users, you can allow cookies to ensure smoother tracking
  allowCookies: true,
});

Look at the React SDK docs for a detailed explanation of the available parameters. For example you can also pass a data object to set additional attributes for the user.

To identify users in Astro, you can call the identify function like this:

import { vemetric } from '@vemetric/astro';

await vemetric.identify({
  identifier: 'your-user-id', // we recommend to use the user's primary id in your database
  displayName: 'John Doe', // optional, will be used to display the users' name in Vemetric

  // If you have the consent of your authenticated users, you can allow cookies to ensure smoother tracking
  allowCookies: true,
});

Look at the Astro SDK docs for a detailed explanation of the available parameters. For example you can also pass a data object to set additional attributes for the user.

Merging data from anonymous users

As soon as you identify a user, all events from the anonymous user session will be merged with the identified user. In other words, all the actions the user took before logging in can now be linked to the same user. This gives you a continuous view of the user’s journey from first visit to sign-up and beyond.

For example if a user visits your website for the first time via a blog post, then visits pricing, and later signs up, you got all of that connected under that user’s profile and see how they got aware of your product.

Reset user

Calling resetUser tells Vemetric to stop associating any following events with the previously identified user (in case he was identified) and to track them anonymously again.

You should call resetUser on initial page load, as soon as you know the user is logged out. If your page doesn’t reload on authentication state changes (e.g. in a Single Page Application), you should also call resetUser when the authentication state changes from authenticated to anonymous.

To reset a user with the HTML script, you can call the resetUser function like this:

await window.vmtrc('resetUser');

To reset a user with the JavaScript SDK, you can call the resetUser function like this:

import { vemetric } from '@vemetric/web';

await vemetric.resetUser();

To reset a user in React, you can call the resetUser function like this:

import { vemetric } from '@vemetric/react';

await vemetric.resetUser();

To reset a user in Astro, you can call the resetUser function like this:

import { vemetric } from '@vemetric/astro';

await vemetric.resetUser();

Updating user data

Most of the time it’s enough to pass user data directly to the identify function which is described above. In case you still want to update their data via a separate action, you can call the updateUser function. This lets you add additional attributes to the user or update existing ones, so you can later use them to filter and group users in Vemetric.

To update a user’s data you can pass an object with the following properties:

set: An object containing key-value pairs of attributes to set. If the user already has the attributes, the values will be overwritten.
setOnce: An object containing key-value pairs of attributes to set only if they don’t already exist on the user.
unset: A string array of attribute keys to remove from the user.

All of these properties are optional, so you can also only pass one of them to update the user’s data.

To update a user’s data with the HTML script, you can call the updateUser function like this:

window.vmtrc('updateUser', {
  set: { key1: 'value1' },
  setOnce: { key2: 'value2' },
  unset: ['key3'],
});

Look at the HTML script docs for a detailed explanation of the available parameters.

To update a user’s data with the JavaScript SDK, you can call the updateUser function like this:

import { vemetric } from '@vemetric/web';

vemetric.updateUser({
  set: { key1: 'value1' },
  setOnce: { key2: 'value2' },
  unset: ['key3'],
});

Look at the JavaScript SDK docs for a detailed explanation of the available parameters.

To update a user’s data in React, you can call the updateUser function like this:

import { vemetric } from '@vemetric/react';

vemetric.updateUser({
  set: { key1: 'value1' },
  setOnce: { key2: 'value2' },
  unset: ['key3'],
});

Look at the React SDK docs for a detailed explanation of the available parameters.

To update a user’s data in Astro, you can call the updateUser function like this:

import { vemetric } from '@vemetric/astro';

vemetric.updateUser({
  set: { key1: 'value1' },
  setOnce: { key2: 'value2' },
  unset: ['key3'],
});

Look at the Astro SDK docs for a detailed explanation of the available parameters.

Checkout the Backend SDKs to learn more how to update user data on the backend.

Tracking custom events

Track meaningful user actions by sending custom events with Vemetric.

User Journeys

Visualize and analyze the full journey of users across your product with Vemetric.