HP Analytics SDK Documentation

Introduction

The HP Analytics SDK (hp-analytics-lib) is a powerful tool for integrating analytics capabilities into your web applications. This SDK allows you to capture and analyze user events, track device properties, and manage user locations efficiently. This document provides guidance on how to integrate and utilize the SDK effectively in your projects.

Installation

To install the HP Analytics SDK, you can use npm or yarn:

npm install hp-analytics-lib

or

yarn add hp-analytics-lib

Initialization

To start using the SDK, you need to initialize it with the appropriate configuration. Here's how to do it:

Initital Properties Parameters: Name | Type | Description ------------ | ------------- | ------------- mode | String | "development" / "production" project_name | String | Name of the project project_id | String | ID of the project project_api_key | String | API key for the project app_version | String | Version of the application (eg: 1.0.0^beta)

Make sure to replace 'Your_Project_Name', 'Your_Project_ID', and 'Your_API_Key' with your actual project details.

Example:

import { HamroEventAnalytics } from 'hp-analytics-lib';

const config = {
    mode: "mode_of_project",
    project_name: 'Your_Project_Name',
    project_id: 'Your_Project_ID',
    project_api_key: 'Your_API_Key',
    app_version: 'Your_app_version',
};

const analytics = new HamroEventAnalytics(config);

User Properties

User properties can be set using the updateUserProperties method. Here's an example of how to set user properties:

NOTE: Please make sure to set user properties after initializing the SDK. Also, set user properties only after the user is authenticated.

User Properties Parameters: Name | Type | Description ------------ | ------------- | ------------- user_id | String | ID of the user user_name | String | Name of the user user_image | String | URL of user's profile image email | String | User's email address login_source | _ | "GOOGLE" / "FACEBOOK" / "TWITTER" phone | String | User phone number

Example:

const userProperties = {
    user_id: 'user123',
    user_name: 'John Doe',
    email: 'user_email',
    login_source: 'GOOGLE', // or 'FACEBOOK' or 'TWITTER'
    phone: 'user_phone_number',
};

analytics.updateUserProperties(userProperties);

//can also be accessed using window.HPAnalytics;
window.HPAnalytics.updateUserProperties(userProperties);

Capturing Events

Once the SDK is initialized, you can start capturing events using the capture method. Here's an example of how to capture events:

NOTE: Please make sure to capture events after initializing the SDK.

Example:

const event = {
  event_name: 'Login',
  properties: {
    "timestamp": Date.now(),
    "click": "XYZ Page",
  }
};

analytics.capture(event)
  .then(() => {
    console.log('Event captured successfully');
  })
  .catch((error) => {
    console.error('Error capturing event:', error);
  });

//can also be accessed using window.HPAnalytics;
window.HPAnalytics.capture(event);

Event Properties Parameters: Name | Type | Description ------------ | ------------- | ------------- event_name | String | Name of event to capture properties | Record<string,string> | event properties

Replace 'Login', 'user123', and other event-specific data with your actual event details.

Global Usage

Upon successful initialization, an object named HPAnalytics is stored on the window object. This object contains references to key functionalities of the SDK, making it globally accessible within your application. You can access HPAnalytics from anywhere in your codebase to interact with the SDK functionalities.

Here's an example of how to access HPAnalytics:

const HPAnalytics = console.log(window.HPAnalytics)
//expected result
HPAnalytics = {
    mode: "mode_of_project", //development or production
    capture: "event capture function",
    updateUserProperties: "user properties update function",
    initialized: "boolean",
    validated: "boolean"
}

Usage:

window.HPAnalytics.capture(event)

Logging Events

You can also log events using the logEvent method. Here's how to do it:

analytics.logEvent('Page View', {
  pageName: 'Home',
  timestamp: Date.now()
});

Replace 'Page View', 'Home', and other event-specific data with your actual event details.

Event Batching, Queue and Network Optimization

Events captured using the capture method are pushed to a queue before being sent to the API. Events are batched, and a batch is pushed to the API when the batch size reaches 5(five). This batching mechanism helps optimize network traffic and API usage.

Additional Features

The HP Analytics SDK provides additional features such as tracking device properties and managing user locations. These features are automatically handled during SDK initialization.

Conclusion

The HP Analytics SDK offers a comprehensive solution for integrating analytics into your web applications. By following the steps outlined in this documentation, you can easily integrate the SDK into your projects and start capturing valuable insights from user interactions.

License

ISC License (ISC)