React SDK

Track your data via the React SDK for Vemetric.

The React SDK is the preferred way to integrate Vemetric into your React application.

Below you can see how to initialize and configure the SDK, as well as all the available functions.

If you’re using a framework on top of React, check out the following guides on how to integrate Vemetric into your application:

Installation

npm install @vemetric/react

import { VemetricScript } from '@vemetric/react';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.tsx';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <VemetricScript token="YOUR_PROJECT_TOKEN" />
    <App />
  </StrictMode>
);

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

export function MyComponent() {
  return (
    <button onClick={() => vemetric.trackEvent('button_clicked')}>
      Click me
    </button>
  );
}

Configuration

You can pass additional props to the VemetricScript component to configure Vemetric.

Look at the different options below for more details.

Example:

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

<VemetricScript
  token="YOUR_PROJECT_TOKEN"
  scriptUrl="https://hub.yourdomain.com/main.js"
  host="https://hub.yourdomain.com"
  trackPageViews={true}
  trackOutboundLinks={true}
  trackDataAttributes={true}
  maskPaths={['/project/*', '/project/*/users']}
  onInit={() => {
    console.log('Vemetric initialized');
  }}
/>;

Replace YOUR_PROJECT_TOKEN with the unique token for your project (found in the project settings).

Methods

The React SDK exports a vemetric object that enables you to track custom events or identify users.

You can import it like this and use it anywhere in your application:

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

<button onClick={() => vemetric.trackEvent('custom_event_react')}>
  Track Custom Event
</button>

Below you can see all the available methods.

trackEvent

The main method to track any kind of event.

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

await vemetric.trackEvent('MyCustomEvent', {
  eventData: { key: 'value' },
}

The first argument is the event name. The second argument is optional and can be an object with the following properties (also both optional):

• eventData: An object containing the meta data of the event so you can later filter by
• userData: An object to update the user data. Only relevant for identified users.
  • set: An object containing the user data to set, overriding existing values.
  • setOnce: An object containing the user data to set once, only if the keys do not exist yet.
  • unset: An array of keys to remove from the user data.

Checkout the tracking custom events section to learn more.

identify

With this function you can identify a user. All following events will be associated with this user. Checkout the docs about User identification to learn more about how it works.

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,
});

The function takes the following parameters:

• identifier (Required): The unique identifier for the user. We recommend to use the user's primary id in your database.
• displayName (Optional): will be used to display the users' name in Vemetric
• allowCookies (Optional): Whether to use cookies to ensure smoother tracking.
• data (Optional): An object to update the user data.
  • set: An object containing the user data to set, overriding existing values.
  • setOnce: An object containing the user data to set once, only if the keys do not exist yet.
  • unset: An array of keys to remove from the user data.

getUserIdentifier

Returns the identifier of the currently identified user. Returns null if no user is identified.

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

const identifier = await vemetric.getUserIdentifier();

updateUser

Updates the data of the currently identified user.

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

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

The first parameter is an object with the following properties:

• set (Optional): An object containing the user data to set, overriding existing values.
• setOnce (Optional): An object containing the user data to set once, only if the keys do not exist yet.
• unset (Optional): An array of keys to remove from the user data.

resetUser

Should be called when the user logs out. From then on, all events will be tracked as anonymous. Checkout the docs about User identification to learn more about how it works.

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

await vemetric.resetUser();

enableTrackPageViews

A function to enable automatic page view tracking after initialization. Only needed if trackPageViews was disabled.

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

vemetric.enableTrackPageViews();

enableTrackOutboundLinks

A function to enable outbound link tracking after initialization. Only needed if trackOutboundLinks was disabled.

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

vemetric.enableTrackOutboundLinks();

enableTrackDataAttributes

A function to enable data attribute tracking after initialization. Only needed if trackDataAttributes was disabled. Learn more about tracking custom events via data attributes.

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

vemetric.enableTrackDataAttributes();

trackPageView

A function to manually track a page view from the current URL. Only needed if trackPageViews was disabled.

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

await vemetric.trackPageView();

trackPageLeave

A function to manually track a page leave. Only needed if trackPageViews was disabled.

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

vemetric.trackPageLeave();

Resources