Tracktor

Tracktor is a robust JavaScript library for tracking and processing events in a first-party tracking environment. It is designed to handle asynchronous event queuing, processing, and validation with ease.

Features:

• Asynchronous Event Processing: Supports queuing and processing events in a thread-safe manner.
• First-Party Tracking: Automatically resolves first-party tracking domains based on the current environment.
• Built-In Validation: Validates UUIDs, email addresses, and phone numbers to ensure consistent and clean data.
• Custom Event Queue: Enqueues custom events for execution, even when the tracktor is not yet initialized.
• Lightweight and Simple API: Focused design for tracking common user interactions.

Installation: Install the package using npm:

npm install tracktor

Usage

1. Basic Setup

   const Tracktor = require('tracktor');
   
   const tracktor = new Tracktor();
   
   // Initialize Tracktor
   tracktor.initialize('your-uuid-here');

2. Track a page view

   tracktor.pageView({ metadata: "value" }, [{segment_key: "segment_value"}], "related-uuid", "https://custom-referrer.com");

3. Record an Email:

   tracktor.recordEmail("[email protected]");

4. Record a Phone Number:

   tracktor.recordPhone("+1234567890");

5. Track a Custom Event:

   tracktor.customEvent("button_click", { buttonId: "signup", position: "header" });

Methods

• initialize(): Initializes the tracktor by injecting a hidden iframe for first-party tracking.
• pageView(data: object, segments: array, relatedUuid: string, referrer: string): Tracks a page view with optional segmentation, related UUID, and referrer. The referrer parameter is used as a fallback when document.referrer is undefined or empty.
• recordEmail(email: string): Records an email address. The email is validated before being sent.
• recordPhone(phone: string): Records a phone number. The phone number is validated before being sent.
• customEvent(name: string, data: object): Tracks a custom event with the specified name and optional data payload. The name must be a non-empty string.

Development

• Running Tests: This package uses Jest for testing. Run the test suite with:

npm test

• Contributing: Contributions are welcome! Please submit a pull request or open an issue for bugs and features.

License

License: MIT License.