UnifyApps Analytics SDK for React

UnifyApps Analytics is a platform designed to help you track and analyze user behavior on your websites. This library provides the tools to integrate UnifyApps Analytics into your browser-based applications.

Key Features

• Event Tracking: Record custom and predefined events such as user actions, session data, and errors.
• Real-Time Data Transmission: Send analytics data to UnifyApps Analytics for instant insights.
• Customizable Schema: Define event structures tailored to your application’s requirements.
• Secure and Optimized: Enjoy encrypted data communication and performance optimized for React applications.

Installation

Update .npmrc accordingly

@unifyapps:registry=https://registry.npmjs.org/
registry.npmjs.org/:_authToken=<npm_token>

To install the library from npm, run the following command:

npm install @unifyapps/analytics-web

Usage

NOTE: This is a client-side library. If you’re using it in a Next.js application, please refer to the example app for proper usage. See Example App for guidance on how to integrate with Next.js applications.

Permissions:

For the app to send location-related data, the end user must grant location permissions.

To use UnifyApps Analytics, first import the necessary components:

import {
  AnalyticsProvider,
  UnifyAppsAnalyticsClient,
} from '@unifyapps/analytics-web';

Initialize the client with the following config options:

| Config Option | Type | Description | Default | |---------------|------|-------------|---------| | host | string | Custom host URL for the analytics endpoint | https://marketing.uat.unifyapps.com | | apiKey | string | Your API key | Required | | sessionTimeout | number | Session timeout in seconds | 5 min | | isEventBatching | boolean | is event batching allowed | true | | flushAt | number | number of events in each batch to be send | 20 | | debug | boolean | to log the payloads and responses | false |

const config = {
  host: 'https://marketing.uat.unifyapps.com',
  apiKey: 'YTph',
  sessionTimeout: 300000,
  flushAt: 20,
  isEventBatching: true,
  debug: false
};

const unifyAppsClient = createClient(config);

Then, wrap your app in the AnalyticsProvider using the client created above:

<AnalyticsProvider client={unifyAppsClient}>
  <Component />
</AnalyticsProvider>

Tracking methods

The following methods are available to track different user events:

1. Track
2. Identify
3. Screen
4. Group
5. Alias

To use these methods, first import them from the useAnalytics hook in your component, as shown below:

import { useAnalytics } from '@unifyapps/analytics-web';

Then, retrieve the methods in your component:

const { track, identify, alias, reset, group } = useAnalytics();

Methods:

Track

The track method is used to track custom events. You can assign a name to the event as event and send the properties associated with that event:

track(event, properties);

Example: Tracking a form submission. Add the track function in onClick of button.

import { useAnalytics } from '@unifyapps/analytics-web';

function handleFormSubmit() {
    const { track } = useAnalytics();
    const formData = {    
        userType: 'Guest'
        timestamp: new Date().toISOString(),
    };
    track('Form Submission', formData);
    // handle form submission ....
}

<button onClick={handleFormSubmit}>
    Submit Form
</button>

Identify

The identify method is used to identify a user. It takes userId and userTraits as arguments.

Initially, the user is set to anonymous, and the userId is assigned a randomly generated string.

When calling identify, the user is updated with the new userId and userTraits:

identify(userId, userTraits);

Example: Call the identity function after login implementation:

import { useAnalytics } from '@unifyapps/analytics-web';
...
const { identify } = useAnalytics();
const userDetails = {
  name: 'John Doe',
  age: 22
}
identity('123', userDetails)
...

Alias

The alias method is used to associate a user with a different ID, allowing you to map multiple IDs to the same user. For example, before logging in, the user is anonymous and is assigned a random ID. After logging in, you can use the alias method to map the anonymous user to the logged-in user:

alias(userId);

Example: If you want to link events from before the user logs in (random user id) to those after login (userId), you can create an alias. This event can then be used to map all the activities to one user with different ids.

import { useAnalytics } from '@unifyapps/analytics-web';
...
const { alias } = useAnalytics();
userId = '123';
login(); //login implementation.
alias(userId);

Group

The group method is used to associate a user with a group, such as an organization or company. It takes groupId and groupTraits as arguments:

group(groupId, groupTraits);

Example: Adding users organisation details.

import { useAnalytics } from '@unifyapps/analytics-web';
...
const { group } = useAnalytics();
const organisation = {
  name : 'abc',
  address : "xyz",
  id : '987'
}
group(organisation.id, organisation)

Screen

The screen method is used to track screen views. You can send the screen name as screen along with other related properties: The screen function sends the following details also.

| Property | Description | Example Value | |------------|--------------------------------------------|------------------------------------| | path | The path of the current screen or page. | /home | | url | The full URL of the current screen or page.| https://example.com/home | | referrer | The URL of the previous page or screen. | https://example.com/login | | search | The query string of the current URL. | ?utm_source=newsletter | | title | The title of the current screen or page. | Welcome to Home |

screen(screen, properties);

Example: Tracking when the user visits a particular screen:

import { useAnalytics } from '@unifyapps/analytics-web';

const Home = () => {
  const { screen } = useAnalytics();
  const screenDetails = {
    name: 'Home',
    visit: new Date().toJSON();
  }
  screen('Home', screenDetails)

  return (
    <div>
      <h1>Home screen</h1>
    </div>
  )

}

Reset

The reset method is used to reset the analytics state. It sets the user to anonymous and assigns a randomly generated string as the userId:

reset();

Example: Clearing User Details after user logouts:

import { useAnalytics } from '@unifyapps/analytics-web';
const { reset } = useAnalytics();
logout(); // logout details ...
reset();

Data Sent:

With each event we also send the context object that contains the following details:

| Property | Description | Example Value | |----------------------------|-----------------------------------------------|-------------------------------------------| | traits | Object containing user-specific traits. | { name: 'John Doe', email: '[email protected]' } | | locale | The user's browser language setting. | en-US | | timezone | The user's current time zone. | America/New_York | | browser.userAgent | The browser's user agent string. | Mozilla/5.0 (Windows NT 10.0; Win64; x64) | | browser.hostName | The current hostname of the website. | example.com | | browser.geoLocation.latitude | The latitude of the user's location (if available). | 37.7749 | | browser.geoLocation.longitude | The longitude of the user's location (if available). | -122.4194 | | screen.density | The device's screen density (pixel ratio). | 2.0 | | screen.height | The height of the user's screen in pixels. | 1080 | | screen.width | The width of the user's screen in pixels. | 1920 |