Overview & Initialization

This SDK aims to simplify the capture and delivery of user events to Mixpanel. In addition, it incorporates a Device Identification System for precise, anonymous user identification. The SDK is designed to offer an excellent developer experience by incorporating: data validation for each event with descriptive errors and an intuitive syntax.

Purpose

The SDK allows developers to:

1. Capture user events, such as searches or purchases, that will be sent to Mixpanel.
2. Identify users anonymously using the Device Identification System.
3. Validate events before sending them, ensuring the required structure and data types are respected.

SDK Initialization

The init function is responsible for initializing the SDK with the configuration needed to capture events. After a successful initialization, the SDK fires a system event called Tracker Ready, which notifies that the library is ready to use.

init function parameters

Parameter	Type	Description
appName	string	Name of the application using the SDK. Used to identify the origin of events and differentiate applications that share the same analytics infrastructure.
mixpanelToken	string	The Mixpanel token used to track events.
identificationToken	string	The token used for device identification through the Device Identification System.
debug	boolean, optional	Enables or disables debug mode. Default value: false.
isSandbox	boolean, optional	Toggles between the sandbox or production environment. Default value: false.
trackerProxy	string, optional	Proxy URL for the tracker service.
identificationProxy	string, optional	Proxy URL for the device identification service.
identificationCacheTTL	number, optional	Time to live (TTL) in days for the device identification cache.
trackerCacheKey	string, optional	Key used to cache the tracker data.

Usage example

import analytics, { InitConfig } from "@reservamos/browser-analytics";

const config: InitConfig = {
  appName: "my-web-app", //New prop
  mixpanelToken: "YOUR_MIXPANEL_TOKEN",
  identificationToken: "YOUR_IDENTIFICATION_TOKEN",
  debug: true, // Set to false in production,
  isSandbox: true // Defaults to false
};

analytics.init(config);

Note

The appName parameter is not yet considered required in the current version; however, its required status will be implemented in future SDK updates. It is highly recommended to include it immediately to ensure compatibility and allow precise identification of the origin of each captured event.

Firing of the Tracker Ready event

Once the SDK has been fully initialized, a system event called "Tracker Ready" will be fired. This system event should not be confused with the user events that are sent to Mixpanel, as its purpose is to notify that the SDK is ready to capture user events.

System Event: Tracker Ready

The Tracker Ready system event notifies when the library has been fully initialized and is ready to capture and send events to Mixpanel. This event is useful to ensure that no user events are captured before the SDK is configured.

Description

• System event name: "Tracker Ready"
• Fired by: The SDK after a successful initialization.
• Event details: The event includes the configuration used to initialize the SDK and can be accessed through the detail property.

Structure of the event’s detail object

Property	Type	Description
detail.config	object	Object that contains the configuration used to initialize the SDK.

Usage example of the "Tracker Ready" system event

You can listen to the "Tracker Ready" event to perform actions when the library is completely ready. This can be useful if you need to wait for the SDK to be initialized before sending user events.

// Listen to the system event to ensure the tracker is ready
window.addEventListener("Tracker Ready", (event) => {
  console.log("Tracker is ready with configuration:", event.detail.config);
  // Here you can run any tracker-dependent code
});