📈 T3 Pixel Tracker

Pixel de rastreamento avançado para campanhas, funil, comportamento, identidade e eventos customizados. Flexível, extensível e pronto para integrações futuras com Google, Meta e plataformas de pagamento.

✅ Features

• ✅ UTM Capture (utm_source, gclid, fbclid, subid, etc)
• ✅ Behavior Tracking (scroll, click, time on page, idle, exit intent...)
• ✅ Funnel Steps (navigation flow tracking)
• ✅ TrackId cross-domain (iframe bridge support)
• ✅ Heartbeat (periodic session pings)
• ✅ Custom Events (lead, purchase, etc)
• ✅ Fallback Tracking (Pixel IMG fallback)
• ✅ AutoInit via Script Tag with data-attributes
• ✅ Error Isolation (never breaks client site)
• ✅ Performance Safe (debounced and SPA friendly)

✅ Installation

pnpm add @trede/pixel
# or
yarn add @trede/pixel
# or
npm install @trede/pixel

✅ Usage (ESM / Node / TypeScript)

import { init } from "@trede/pixel";

init({
  enabled: true,
  debug: true,
  funnel: { enabled: true },
  behavior: { enabled: true },
});

✅ Usage via Script Tag (AutoInit)

<script
  src="https://cdn.jsdelivr.net/npm/@trede/pixel/dist/index.global.js"
  data-params-tracker
  data-enabled="true"
  data-debug="true"
  data-delay="0"
  data-endpoint="https://api.example.com/track"
  data-endpoint-fallback="https://api.example.com/track-fallback"
  data-use-fallback="true"
  data-use-beacon="true"
  data-funnel-enabled="true"
  data-behavior-enabled="true"
></script>

✅ Configuration Options (PixelConfig)

| Property | Type | Default | Description | |---|---|---|---| | enabled | boolean | true | Whether the Pixel should start | | debug | boolean | false | Enable debug console logs | | delay | number | 0 | Startup delay in ms | | endpoint | string | - | Main payload endpoint | | endpoint_fallback | string | - | Fallback IMG Pixel endpoint | | useFallback | boolean | false | Enables IMG fallback tracking | | useBeacon | boolean | false | Use navigator.sendBeacon | | funnel | object | - | Funnel tracking config | | behavior | object | - | Behavior tracking config |

Funnel Config

| Property | Type | Default | Description | |---|---|---|---| | enabled | boolean | true | Enable funnel | | disableAutoStep | boolean | false | Disable automatic step tracking | | ttl | number | 24h | Funnel TTL | | storageKey | string | "FUNNEL" | Local storage key |

Behavior Config

| Property | Type | Default | Description | |---|---|---|---| | enabled | boolean | true | Enable behavior tracking | | storageKey | string | "BEHAVIOR" | Local storage key | | ttl | number | 15min | State TTL | | shadow | boolean | false | Inject behavior inside Shadow DOM | | disableAutoTrack | boolean | false | Disable auto-tracking | | idleThresholdMs | number | 30000 | Idle time threshold | | timeIntervalMs | number | 5000 | Page time update interval |

✅ Public API

| Function | Description | |---|---| | init(config) | Initialize Pixel | | trackEvent(eventName, extraData?) | Track custom event | | trackPageView(extraData?) | Trigger page view | | updateUser(properties) | Update user identity | | flush() | Force payload flush | | getTrackerContext() | Get current tracker context | | reset() | Clear funnel, behavior, and visitor state |

✅ Default Events (PixelEventType)

| Event | Description | |---|---| | PAGE_VIEW | Page view | | CLICK | Click | | SCROLL | Scroll | | LEAD | Lead | | PURCHASE | Purchase | | BEGIN_CHECKOUT | Begin checkout | | ADD_TO_CART | Add to cart | | CUSTOM | Custom | | FALLBACK | Fallback | | HEARTBEAT | Heartbeat | | VIEW_CONTENT | View content | | INITIATE_CHECKOUT | Initiate checkout | | COMPLETE_REGISTRATION | Complete registration | | SEARCH | Search | | ADD_PAYMENT_INFO | Add payment info | | SESSION_START | Session start | | VIEW_ITEM | View item | | GENERATE_LEAD | Generate lead | | LOGIN | Login | | SIGN_UP | Sign up | | LOGOUT | Logout |

✅ Internal Flow

1. Capture UTMs and advanced parameters
2. Resolve TrackId cross-domain (iframe bridge)
3. Capture Visitor Info
4. Open Funnel Session
5. Start Behavior Tracking
6. Build Payload
7. Send to endpoint
8. Generate Heartbeats
9. SPA compatible (observeRouteChange)

✅ Local Development

pnpm install
pnpm dev
pnpm build

✅ Folder Structure

src/
├── behavior/
├── bridge/
├── fallback/
├── funnel/
├── payload/
├── storage/
├── utils/
├── visitInfo/
├── pixelInit.ts
├── init.ts
├── index.ts
└── types.ts

✅ License

MIT