@audienceranker/beacon
v1.0.2
Published
AudienceRanker tracking beacon — lightweight analytics collector for websites
Downloads
34
Maintainers
kazzkiqReadme
@audienceranker/beacon
Lightweight analytics beacon for AudienceRanker — a "pixel-style" tracking library that collects audience data and sends it to the AudienceRanker collector.
Installation
Option 1: NPM (Recommended for modern projects)
npm install @audienceranker/beaconOption 2: Script Tag (Simplest for any website)
Add this single line to your HTML <head>:
<script data-audience-ranker src="https://cdn.audienceranker.com/beacon.min.js?tid=YOUR_TENANT_ID"></script>Usage
NPM / ESM (Modern bundlers)
import { init, destroy } from '@audienceranker/beacon';
// Initialize with your tenant ID
init({ tenantId: 'your-tenant-id' });
// Optional: manually destroy when needed
// destroy();Script Tag (Auto-initialization)
When using the script tag with ?tid= parameter, the beacon auto-initializes:
<script data-audience-ranker src="https://cdn.audienceranker.com/beacon.min.js?tid=your-tenant-id"></script>Script Tag (Manual initialization)
If you prefer manual control, omit the ?tid= parameter:
<script data-audience-ranker src="https://cdn.audienceranker.com/beacon.min.js"></script>
<script>
// Initialize manually when ready
window.AudienceRanker.init({ tenantId: 'your-tenant-id' });
</script>Configuration
The init() function accepts a configuration object:
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| tenantId | string | Yes | — | Your unique tenant identifier |
| collectorUrl | string | No | https://collector.audience.lat | Custom collector endpoint |
Example with custom collector:
init({
tenantId: 'your-tenant-id',
collectorUrl: 'https://custom-collector.your-domain.com'
});API Reference
init(config: BeaconConfig): void
Initializes the beacon and starts all tracking features. Safe to call multiple times — each call destroys the previous instance first.
destroy(): void
Tears down the beacon, stopping all tracking, observers, and schedulers. Safe to call even if init() was never called.
VERSION: string
Current version of the beacon library (e.g., "0.0.1").
What It Tracks
The beacon automatically collects:
- Pageviews — Fires on every page load and SPA navigation
- Visits/Sessions — Tracks unique visits (30-minute session timeout)
- Core Web Vitals — LCP, INP, CLS for performance monitoring
- Traffic Type — Organic, direct, referral detection
- Traffic Origin — Referrer information
- Device Info — Device type from user agent
- Connection Speed — Network speed estimation
- Connection Type — WiFi, 4G, etc. (when available)
- Device Tier — Performance capability classification
- Geolocation — Country detection
Distribution Files
The package includes multiple builds for different use cases:
| File | Format | Use Case |
|------|--------|----------|
| dist/index.esm.js | ESM | Modern bundlers (Webpack, Vite, Rollup) |
| dist/index.cjs.js | CommonJS | Node.js, legacy bundlers |
| dist/beacon.min.js | IIFE/UMD | Browser <script> tag |
| dist/index.d.ts | TypeScript | Type definitions |
Browser Support
Works in all modern browsers that support:
navigator.sendBeacon(with XHR fallback)PerformanceObserver(for Core Web Vitals)URLandURLSearchParams
License
MIT
AudienceRanker — Analytics for newsrooms and content publishers.