@easyflow/pixel/README.md

Easyflow client-side pixel SDK

# @easyflow/pixel

Client-side SDK for event tracking in Easyflow checkouts.

This SDK encapsulates the **Meta (Facebook)**, **Google**, and **TikTok** tracking pixels, allowing standardized event
sending through a unified interface. In addition, all events are also reported to Easyflow's API for storage, auditing,
and retry processing.

## ✨ Features

- Dynamic loading of third-party pixel scripts
- Automatic mapping of Easyflow events to platform-specific events
- Simultaneous dispatch to Meta, Google, and TikTok
- Full logging of all events to Easyflow backend
- Rich metadata collection from the client environment

---

## 🚀 Installation

```bash
npm install @easyflow/pixel
```

---

## 🔧 Usage

```ts
import {EasyflowPixel, Events} from '@easyflow/pixel';

const pixel = new EasyflowPixel('BUSINESS_ID_HERE', 'FINGERPRINT_ID_HERE', {
    product: 'PRODUCT_ID_HERE',
    offer: 'OFFER_ID_HERE',
    checkout: 'CHECKOUT_ID_HERE',
    paymentLink: 'PAYMENT_LINK_ID_HERE',
});

await pixel.init();

pixel.track(Events.CHECKOUT_INITIALIZED);
pixel.track(Events.PURCHASE_COMPLETED, {
    value: 349.90,
    currency: 'BRL',
    transaction_id: 'ORD102983'
});
```

---

## 🎯 Available Events

```ts
export enum Events {
    CHECKOUT_INITIALIZED = 'checkout-initialized',
    PURCHASE_COMPLETED = 'purchase-completed',
    PURCHASE_FAILED = 'purchase-failed',
    PURCHASE_BTN_CLICKED = 'purchase-btn-clicked',
    PIX_SELECTED = 'pix-selected',
    PIX_GENERATED = 'pix-generated',
    PIX_EXPIRED = 'pix-expired',
    PIX_COPIED = 'pix-copied',
    CREDIT_CARD_SELECTED = 'credit-card-selected',
    CREDIT_CARD_FORM_COMPLETED = 'credit-card-form-completed',
    BANK_BILLET_SELECTED = 'bank-slip-selected',
    BANK_BILLET_GENERATED = 'bank-slip-form-completed',
    ADDRESS_FORM_COMPLETED = 'address-form-completed',
    DELIVERY_ADDRESS_COMPLETED = 'delivery-address-completed',
    COUPON_ADDED = 'coupon-added',
    COUPON_BOX_CLICKED = 'coupon-box-clicked',
    COUPON_FORM_COMPLETED = 'coupon-form-completed',
    COUPON_APPLY_FAILED = 'coupon-apply-failed',
    USER_FORM_COMPLETED = 'user-form-completed',
    PRE_CHECKOUT_FORM_COMPLETED = 'pre-checkout-form-completed'
}
```

---

## 📦 Production Deployment

Make sure to:

- Only include the SDK in your checkout pages
- Call `await pixel.init()` before tracking any events

---

## 🧪 Telemetry & Logging

All events are reported to Easyflow with:

- Navigation context
- UTM metadata
- Fingerprint identification
- Page visibility state
- Page performance metrics
- Delivery attempts and platform status

---

## 🔐 Privacy

- No sensitive user data is stored
- Supports cookie policy and Do Not Track (DNT)

---

## Additional Resources

- [Easyflow Digital](https://easyflow.digital): Official website of Easyflow.
- [Easyflow API Documentation](https://docs.easyflow.digital): Detailed API documentation for Easyflow.
- [Support Site](https://easyflow.digital/contact): Contact Easyflow support for assistance.
- [Support Email](mailto:contato@easyflow.digital): Email Easyflow support for queries.

---

## 🧾 License

MIT License © [Easyflow](https://easyflow.digital)