@comparaonline/event-tracker/README.md

This library it's an interface between any frontend application and some event tracking platforms, currently Snowplow and Tag Manager.

# @comparaonline/event-tracker
![npm](https://img.shields.io/npm/v/@comparaonline/event-tracker.svg?style=flat-square)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)

This library is an interface between any frontend application and event tracking platforms.

There's more documentation available for the library in [compara's notion](https://www.notion.so/comparaonline/Event-tracker-87a0372cf2a24f2a8a461363b015a9d3)

## Documentation

- [Coding Conventions](./docs/CODING_CONVENTIONS.md): Coding conventions and patterns used in this project
- [Contributing Guidelines](./docs/CONTRIBUTING.md): Guidelines for contributing to the project
- [Project Structure](./docs/STRUCTURE.md): Explanation of the project's directory structure

## Installation

To install the library in your application use

```
yarn add @comparaonline/event-tracker
```

or 

```
npm install @comparaonline/event-tracker
```

## Usage example

After installing the package you can send an event using the function `track`. For example:

```typescript
import { track, BUSINESS_UNIT, COUNTRY_CODE } from '@comparaonline/event-tracker';

// Example of form step render event
track({
  name: 'form_step_render',
  data: {
    app_name: 'my-app',
    app_version: '1.0.0',
    country_code: COUNTRY_CODE.CL,
    business_unit: BUSINESS_UNIT.CAR_INSURANCE,
    user_type: 'anonymous',
    quote_id: '12345',
    accordion_index: '0',
    accordion_name: 'personal-information'
  }
});

// Example of transaction event
track({
  name: 'transaction',
  data: {
    app_name: 'my-app',
    app_version: '1.0.0',
    country_code: COUNTRY_CODE.CL,
    business_unit: BUSINESS_UNIT.CAR_INSURANCE,
    user_type: 'registered',
    user_id: 'user-123',
    transaction_id: 'trans-456',
    amount: 15000,
    currency: 'CLP'
  }
});
```

The library will automatically send the event to all enabled trackers (currently ABTasty and Heap).

## Trackers

The trackers currently supported by the library are:

- ABTasty: Used for A/B testing and analytics.
- Heap: Used for user behavior analytics.

The library is configured to use both trackers by default. The events are automatically sent to both trackers when you use the `track` function.

## Event Types

The library supports various event types:

- `attached_policy_to_user`: Track when a policy is attached to a user
- `cancel_policy_requested`: Track when a user requests a policy cancellation
- `cep_autocompleted`: Track when a postal code is autocompleted
- `form_step_render`: Track when a form step is rendered
- `payment_method_updated`: Track when a payment method is updated
- `person_autocompleted`: Track when person information is autocompleted
- `transaction`: Track a transaction
- `tutorial_begin`: Track when a tutorial begins
- `tutorial_complete`: Track when a tutorial is completed
- `user_account_onboarding_completed`: Track when user onboarding is completed
- `vehicle_autocompleted`: Track when vehicle information is autocompleted

Each event type requires specific data. You can import the type definitions to ensure you're providing the correct data:

```typescript
import { track, BUSINESS_UNIT, COUNTRY_CODE } from '@comparaonline/event-tracker';
import type { FormStepRenderData } from '@comparaonline/event-tracker';

const eventData: FormStepRenderData = {
  app_name: 'my-app',
  app_version: '1.0.0',
  country_code: COUNTRY_CODE.CL,
  business_unit: BUSINESS_UNIT.CAR_INSURANCE,
  user_type: 'anonymous',
  quote_id: '12345',
  accordion_index: '0',
  accordion_name: 'personal-information'
};

track({
  name: 'form_step_render',
  data: eventData
});
```

## Migrating from previous versions

If you're migrating from version 6.x or earlier, there are significant changes to the API. The main changes are:

1. The `sendEvent` function has been replaced with `track`
2. Event types and constants are now exported directly from the main module
3. There are no longer separate endpoints like `SNOWPLOW_APP` or `TAG_MANAGER_APP`
4. Event tracking is handled automatically to all enabled trackers

To migrate, update your imports and replace your event sending code:

Old code:
```typescript
import { endpoints, sendEvent, types } from '@comparaonline/event-tracker/';
import {
  carInsuranceGenerators,
  FormSubmitParams,
} from '@comparaonline/event-tracker/eventGenerators/carInsurance';

const rawFormSubmit: FormSubmitParams = {
  appVersion: '1.0',
  appName: 'test-module',
  countryCode: types.CountryCodeTypes.chile,
  formId: 'asdf',
  formType: types.FormTypes.wizard,
  formSubmitStatus: types.FormStatusTypes.successful,
  funnelType: types.FormRelatedTypes.FunnelTypes.quote,
  formValues: { a: 'asdf', b: 'sdf' },
};
const formSubmit = carInsuranceGenerators.generateFormSubmit(rawFormSubmit);
sendEvent(endpoints.SNOWPLOW_APP, formSubmit);
```

New code:
```typescript
import { track, BUSINESS_UNIT, COUNTRY_CODE } from '@comparaonline/event-tracker';

track({
  name: 'form_step_render',
  data: {
    app_name: 'test-module',
    app_version: '1.0',
    country_code: COUNTRY_CODE.CL,
    business_unit: BUSINESS_UNIT.CAR_INSURANCE,
    user_type: 'anonymous',
    quote_id: 'asdf',
    accordion_index: '0',
    accordion_name: 'form-step'
  }
});
```