@eduzz/tracking

Ambient TypeScript types for the Eduzz Tracking CDN script.

The tracking runtime is loaded with a <script> tag (not as an npm import). This package only adds compile-time types for the globals that script exposes on window.

Install

pnpm add -D @eduzz/tracking

Use npm / yarn equivalents if needed. Keep it in devDependencies.

Enable the types

Because this package is under @eduzz/* (not @types/*), TypeScript does not load it automatically after install. Register it once in tsconfig.json:

{
  "compilerOptions": {
    "types": ["@eduzz/tracking"]
  }
}

If you already list packages in compilerOptions.types, append @eduzz/tracking to that array. Setting types replaces automatic inclusion of every @types/* package, so keep any other entries you still need (for example "node").

After that, no import is required. window.eduzzTracking and window.eduzzDataLayer are typed in the project.

Usage

Load the script from the CDN

<script src="https://your-cdn.example/packages/tracker/index.js"></script>

Initialize and push events

const user = {
  loggedUser: {
    sessionId: '1e0f9bb539e8cd7e0687c745b9c0680339c45fcd5298f6c709fcd8a575e3a3f8',
    accountsId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
    name: 'Biru Zilva',
    email: '[email protected]',
    role: 'producer',
    roles: ['producer'],
    createdAt: '2024-01-01T00:00:00.000Z',
    alreadyTransferred: false,
    isSupport: false,
    platform: 'web'
  }
};

window.eduzzTracking.init(user);

// Optional: on localhost / *.devopzz.ninja / *.testzz.ninja, load tokens for another mapped host
window.eduzzTracking.init(user, { asHost: 'biru.maracaja.com' });

// Same loggedUser.accountsId and accessedUser.accountsId: no-op
window.eduzzTracking.init(user);

// Different logged or accessed accountsId: empties eduzzDataLayer, restarts polling,
// and re-identifies Clarity / Pendo / GTM without loading scripts again
window.eduzzTracking.init({
  loggedUser: user.loggedUser,
  accessedUser: {
    accountsId: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
    name: 'Opened account',
    email: '[email protected]'
  }
});

window.eduzzDataLayer = window.eduzzDataLayer || [];
window.eduzzDataLayer.push({
  event: 'page_view',
  path: '/home'
});

window.eduzzTracking.updateInitOptions({
  loggedUser: {
    onboardingStatus: 'completed'
  }
});

Optional named imports

You can also import the public types when typing your own helpers:

import type { TrackingEvent, TrackingUser } from '@eduzz/tracking';

const user: TrackingUser = {
  loggedUser: {
    sessionId: '1e0f9bb539e8cd7e0687c745b9c0680339c45fcd5298f6c709fcd8a575e3a3f8',
    accountsId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
    name: 'Ada',
    email: '[email protected]',
    role: 'producer',
    roles: ['producer'],
    createdAt: '2024-01-01T00:00:00.000Z',
    alreadyTransferred: false,
    isSupport: false,
    platform: 'web'
  }
};
const event: TrackingEvent = { event: 'page_view' };

Public API

| Name | Kind | Description | | --- | --- | --- | | TrackingUser | type | Payload passed to init (loggedUser, optional accessedUser) | | TrackingInitOptions | type | Optional second argument to init (asHost to borrow another host's tokens on allowlisted hosts) | | TrackingInitUpdate | type | Nested partial of TrackingUser passed to updateInitOptions | | TrackingEvent | type | Item pushed to eduzzDataLayer (event plus extra fields) | | EduzzTrackingApi | type | Shape of window.eduzzTracking | | window.eduzzTracking | global | { init(user, options?), updateInitOptions(update) }. init no-ops when both accounts ids match the last successful init; otherwise resets eduzzDataLayer, restarts the poll loop, and re-identifies vendors | | window.eduzzDataLayer | global | Optional array of TrackingEvent |

Vendor globals used only inside the CDN script (Pendo, GTM, Clarity) are not part of this package.

What this package is not

• Not the tracking runtime
• Not a browser bundle
• Not a replacement for the CDN <script> tag

Apps still load the script from the CDN. This package only makes TypeScript aware of that script's public globals.