AdsTracker

A simple tracking client library for ad viewability and user activity monitoring with automatic user identification.

Installation

npm install ads-tracker

Usage

Site Time Tracking

import { siteTimeTracker } from 'ads-tracker';

const tracker = siteTimeTracker();
tracker.start();

console.log(tracker.getStats());

CDN Usage

<script src="https://unpkg.com/ads-tracker/dist/utrack.umd.min.js"></script>
<script>
  const tracker = UTrack.siteTimeTracker();
  tracker.start();
  console.log(tracker.getStats());
</script>

Banner Viewability Tracking

import { viewabilityTracker } from 'ads-tracker';

const bannerTracker = viewabilityTracker({
  selector: '.banner',
  itemId: 'banner123'
});

bannerTracker.start();

console.log(bannerTracker.getStats());
console.log(bannerTracker.getAverageVisibility());

User Identification

The library automatically generates and persists a unique user ID for each browser/user. This ID is stored in localStorage and reused across sessions.

// Automatic user ID generation (recommended)
const tracker = siteTimeTracker();

// Or specify custom user ID
const tracker = siteTimeTracker({ userId: 'custom-user-id' });

Viewability Tracker API

• getStats() - returns viewability stats plus average viewability
• getAverageVisibility() - returns the current banner quartile state for the current session
• getAverageVisibilityById(bannerId) - loads stored average visibility data for a specific banner id from localStorage
• clearAverageVisibilityById(bannerId) - removes saved visibility data for a specific banner id
• clearAllAverageVisibility() - removes all saved banner visibility data from localStorage

Local Storage Keys

• _ut_user_id - automatically generated unique user identifier
• _ut_avg_{userId}_{itemId} - saved average visibility summary for each banner per user
• _ut_view_{userId}_{itemId} - saved total view stats for each banner per user
• _ut_site_stats_{userId} - saved site activity stats per user

Development

Build

npm run build

Development Mode

npm run dev

License

MIT