Web Beacon

The LeadVibe Web Beacon is a lightweight JavaScript snippet that automatically tracks visitor behavior on your website. Install it once and start capturing page views, scroll depth, engagement time, and custom events—all without writing any tracking code.

What It Does

The beacon provides real-time behavioral intelligence:

Automatic Tracking: Page views, scroll depth, engagement time, outbound clicks
Custom Events: Track button clicks, form submissions, and other interactions via API
Visitor Identification: Associate anonymous visitors with email/ID when they identify themselves
Passive Idle Detection: Distinguishes active engagement from idle time
Session Continuity: Maintains visitor identity across pages and sessions
Works with Chrome Extension: Receives events from the Chrome Extension visual tagger

The beacon is built for performance: lightweight (~5KB gzipped), non-blocking, and privacy-friendly.

Quick Start

Installation

Navigate to Settings → Integrations → Web in LeadVibe
Copy the beacon snippet (it includes your unique token)
Paste the snippet in the <head> section of your website (before </head>)
Deploy to production

Example snippet:

<script src="https://app.leadvibe.com/tracker.js"
        data-token="YOUR_BEACON_TOKEN"
        data-endpoint="https://app.leadvibe.com/ingest"
        defer></script>

Important: Replace YOUR_BEACON_TOKEN with the actual token from your LeadVibe settings. Tokens are scoped to your Organization Unit (OU) and enforce an origin allowlist for security.

How Tokens Work

Bearer Token Authentication:

Each beacon token is unique to your OU
Tokens include an origin allowlist (domains where the token is valid)
No sensitive credentials exposed in the browser
Tokens can be rotated in Settings → Integrations → Web

Security: Tokens cannot be used from unauthorized domains, preventing token theft and abuse.

What is captured automatically

Event: page_view
Metadata (structured JSON):
- path, full url, referrer
- UTM params: utm_source, utm_medium, utm_campaign, utm_term, utm_content
- title, language, user_agent
- Dimensions: screen.width/height, viewport.width/height
- scroll_percent - Maximum scroll depth (0-100)
- Engagement Metrics:
  - engaged_time_ms - Time actively engaged (reading, scrolling, interacting)
  - idle_time_ms - Time spent idle (no interaction)
  - times_went_idle - Number of times activity paused

Understanding Engagement Metrics

LeadVibe automatically tracks how engaged visitors are with your content. The beacon distinguishes between active engagement (when someone is reading, scrolling, or interacting) and idle time (when the tab is open but there's no activity).

This gives you a true picture of content engagement without any additional setup.

What Gets Tracked

Metric	Description	Example Value
`engaged_time_ms`	Time spent actively engaging with the page	`180000` (3 minutes)
`idle_time_ms`	Time when the page was open but inactive	`720000` (12 minutes)
`times_went_idle`	Number of times the visitor stopped interacting	`2`

Why This Matters

Lead Scoring Use engaged time to identify high-intent leads. Someone who spends 8 minutes actively reading your pricing page is more qualified than someone who glanced at it for 30 seconds.

Content Performance Understand which pages truly hold attention. High scroll percentage + high engaged time = compelling content that resonates with your audience.

Visitor Segmentation Segment visitors by engagement patterns:

Engaged readers: High engaged time, low idle time
Researchers: Multiple visits with consistent engagement
Quick scanners: Low engaged time, high scroll percentage

Example Event Data

Here's what the engagement metrics look like in a typical page view event:

{
  "engaged_time_ms": 180000,
  "idle_time_ms": 720000,
  "times_went_idle": 2,
  "scroll_percent": 85
}

Reading this data: A visitor spent 3 minutes actively engaged, had 12 minutes of idle time (likely switched tabs or stepped away), went idle twice, and scrolled 85% down the page.

Note: The legacy time_visible_ms field is still present for backward compatibility but now reports the same value as engaged_time_ms. Use engaged_time_ms for all new integrations and scoring rules.

Custom Events

Track custom interactions on your website using the beacon API.

Track an Event

window.leadvibe.push(['track', 'event_name', { metadata_key: 'value' }]);

Parameters:

event_name (string): Name of the event (e.g., cta_click, video_play)
metadata (object): Key-value pairs with event details

Example:

// Track a button click
window.leadvibe.push(['track', 'pricing_cta_click', {
  button: 'Get Started',
  plan: 'Enterprise'
}]);

// Track video engagement
window.leadvibe.push(['track', 'video_play', {
  video_id: 'demo_2024',
  duration: 120
}]);

Identify a Visitor

Associate an anonymous visitor with their email or external ID.

window.leadvibe.push(['identify', {
  email: 'user@example.com',
  external_id: 'user_123',
  phone: '+1234567890'
}]);

Parameters:

email (string): Visitor's email address
external_id (string, optional): Your system's user ID
phone (string, optional): Phone number

Example:

// After user logs in
window.leadvibe.push(['identify', {
  email: 'jane@company.com',
  external_id: 'crm_456'
}]);

When to identify:

After user logs in
After form submission (if you capture email)
When user verifies email
When user creates an account

Once identified, all subsequent events are linked to that lead.

Integration with Chrome Extension

The beacon works seamlessly with the LeadVibe Chrome Extension:

Install beacon on your website (this page)
Install Chrome extension in your browser
Visually tag elements using the extension (buttons, forms, etc.)
Extension injects event listeners that call window.leadvibe.push()
Beacon sends events to LeadVibe backend with session context

No coding required: Marketing ops teams can deploy tracking without developer involvement. The extension provides a point-and-click interface for tagging, and the beacon handles the rest.

See Chrome Extension documentation for visual tagging instructions.

Performance and Privacy

Performance

Small footprint: ~5KB gzipped
Non-blocking: Uses defer attribute, doesn't delay page load
Efficient batching: Events sent with keepalive for reliability
No cookies (except anonymous visitor ID): Respects privacy

Privacy

Anonymous by default: No PII collected until visitor identifies themselves
Visitor ID cookie: First-party cookie for session continuity (not cross-site tracking)
No third-party sharing: Data sent only to LeadVibe backend
Origin allowlist: Tokens only work on authorized domains

Browser Support

Modern browsers (Chrome, Firefox, Safari, Edge)
IE11 and older browsers: Beacon won't load (graceful degradation)

Troubleshooting

Events Not Appearing in LeadVibe

Check the browser console (F12 → Console tab):

No errors: Beacon loaded successfully
401 Unauthorized: Token is invalid or expired (regenerate token in Settings)
403 Forbidden: Domain not in origin allowlist (add domain to token's allowed origins)
Network error: data-endpoint URL is incorrect or backend is unreachable

"Beacon not found on page" (Chrome Extension)

Cause: Beacon script hasn't loaded yet or isn't installed.

Solution:

Verify beacon snippet is in <head> section
Check network tab (F12 → Network) for tracker.js request
Refresh the page after installing beacon

Double Page Views

Cause: Beacon snippet included multiple times (e.g., in both header and footer).

Solution: Remove duplicate script tags. Beacon should only be included once.

Tracking Doesn't Work on Localhost

Cause: Beacon token's origin allowlist doesn't include localhost.

Solution: Add http://localhost:3000 (or your local port) to the token's allowed origins in Settings → Integrations → Web.

Advanced Configuration

Custom Endpoint

By default, the beacon sends events to the LeadVibe SaaS backend. For self-hosted deployments, set a custom endpoint:

<script src="https://your-domain.com/tracker.js"
        data-token="YOUR_BEACON_TOKEN"
        data-endpoint="https://your-leadvibe-api.com/ingest"
        defer></script>

Testing on Staging

Create a separate beacon token for staging environments:

In Settings → Integrations → Web, click Create Token
Name it "Staging" and add staging domains to allowed origins
Use this token in your staging environment

This keeps staging events separate from production.

API Reference

`window.leadvibe.push()`

All beacon interactions use the push method:

window.leadvibe.push([command, ...args]);

Track Event

window.leadvibe.push(['track', 'event_name', { metadata }]);

Returns: None (fire-and-forget)

Example:

window.leadvibe.push(['track', 'download', {
  file: 'whitepaper.pdf',
  source: 'blog_post'
}]);

Identify Visitor

window.leadvibe.push(['identify', { email, external_id, phone }]);

Returns: None (fire-and-forget)

Example:

window.leadvibe.push(['identify', {
  email: 'user@example.com'
}]);

Event Data Reference

Automatic Event: `page_view`

Sent on every page load.

Metadata:

path: Page path (e.g., /pricing)
url: Full URL
referrer: HTTP referrer
title: Page title
language: Browser language
user_agent: User agent string
screen.width, screen.height: Screen dimensions
viewport.width, viewport.height: Viewport dimensions
scroll_percent: Maximum scroll depth (0-100)
engaged_time_ms: Time actively engaged (see below)
idle_time_ms: Time idle (see below)
times_went_idle: Number of idle periods
UTM parameters: utm_source, utm_medium, utm_campaign, utm_term, utm_content

Automatic Event: `outbound_link_click`

Sent when visitor clicks an external link.

Metadata:

href: Link destination
element_text: Link text
url: Current page URL

Automatic Event: `page_scrolled`

Sent when visitor scrolls past 90% of the page.

Metadata:

scroll_percent: Final scroll depth (usually 90+)
url: Current page URL

Automatic Event: `page_unloaded`

Sent when visitor leaves the page (navigates away, closes tab).

Metadata:

engaged_time_ms: Total time actively engaged
idle_time_ms: Total time idle
times_went_idle: Number of idle periods
scroll_percent: Maximum scroll depth achieved
url: Page URL that was unloaded

Notes

Beacon uses keepalive to ensure events are sent even if the page is closing
No credentials sent: Beacon uses bearer token authentication only
Anonymous visitor ID: First-party cookie _lv_vid maintains visitor continuity across sessions
Events batched: Multiple events may be sent in a single request for efficiency

What It Does​

Quick Start​

Installation​

How Tokens Work​

What is captured automatically​

Understanding Engagement Metrics​

What Gets Tracked​

Why This Matters​

Example Event Data​

Custom Events​

Track an Event​

Identify a Visitor​

Integration with Chrome Extension​

Performance and Privacy​

Performance​

Privacy​

Browser Support​

Troubleshooting​

Events Not Appearing in LeadVibe​

"Beacon not found on page" (Chrome Extension)​

Double Page Views​

Tracking Doesn't Work on Localhost​

Advanced Configuration​

Custom Endpoint​

Testing on Staging​

API Reference​

window.leadvibe.push()​

Track Event​

Identify Visitor​

Event Data Reference​

Automatic Event: page_view​

Automatic Event: outbound_link_click​

Automatic Event: page_scrolled​

Automatic Event: page_unloaded​

Notes​

What It Does

Quick Start

Installation

How Tokens Work

What is captured automatically

Understanding Engagement Metrics

What Gets Tracked

Why This Matters

Example Event Data

Custom Events

Track an Event

Identify a Visitor

Integration with Chrome Extension

Performance and Privacy

Performance

Privacy

Browser Support

Troubleshooting

Events Not Appearing in LeadVibe

"Beacon not found on page" (Chrome Extension)

Double Page Views

Tracking Doesn't Work on Localhost

Advanced Configuration

Custom Endpoint

Testing on Staging

API Reference

`window.leadvibe.push()`

Track Event

Identify Visitor

Event Data Reference

Automatic Event: `page_view`

Automatic Event: `outbound_link_click`

Automatic Event: `page_scrolled`

Automatic Event: `page_unloaded`

Notes