Video Lead Tracker

Gate your video content behind a lead form — then know exactly who watched, how much, and where they dropped off.

Video Lead Tracker is a self-hosted WordPress plugin that turns any HTML5 video into a lead-capture and analytics engine. Visitors submit their name and mobile number before the video unlocks. Every second of playback is recorded, aggregated, and surfaced in a built-in admin dashboard — with no third-party analytics services and no data leaving your server.

Why Video Lead Tracker

Most lead-capture tools stop at the form. You collect a name and number, but you have no idea whether the person who submitted actually watched your content — or for how long. Video Lead Tracker closes that gap.

• A lead who watched 80% of your product demo behaves differently from one who watched 5 seconds and left. Now you can tell them apart.
• All data lives in your WordPress database. No external SaaS, no tracking pixels, no GDPR headaches from third parties.
• Built for the Iranian market: native support for all local mobile number formats and direct integration with Kavenegar and SMS.ir for OTP verification.

Features

Lead Capture & Identity

• Overlay form collects name + mobile number before the video plays
• Mobile number is normalized from any Iranian format (09xxxxxxxxx, +98xxxxxxxxxx, etc.) to a canonical 98xxxxxxxxxx form
• Returning visitors are recognized automatically via a secure identity token stored in localStorage and a cookie — they skip the form on repeat visits
• Anonymous viewing data (ranges, events, page visits) is retroactively linked to the lead record the moment the form is submitted
• Optional OTP verification via SMS confirms mobile ownership before video access

OTP Verification

• 6-digit cryptographically random code, SHA-256 hashed before storage
• Configurable code expiry and resend cooldown
• Built-in integrations: Kavenegar and SMS.ir
• Brute-force safe: attempt counter increments before code comparison
• Clean, in-page OTP UI with masked mobile display and resend countdown

Video Analytics

Event tracking — every meaningful player action is recorded:

Watch range tracking — continuous play segments are captured as [from_second, to_second] pairs:

• Ranges are committed on pause, seek, heartbeat, and page close
• Page-close commits use navigator.sendBeacon with a fetch keepalive fallback so no data is lost when the tab closes
• Seeking mid-play correctly commits the pre-seek segment and starts a fresh one at the new position

Per-viewer summary — after each range commit, aggregated stats are updated in real time:

Range deduplication uses a 0.25 s tolerance so scrubbing back a tiny amount doesn't inflate unique watch time.

Per-second heatmap — for each video, a heatmap table tracks how many viewers (total, unique leads, unique visitors) watched each second. Useful for spotting the exact moment engagement drops.

Page Visit Tracking

• page_view, page_visible, page_hidden, page_unload, and heartbeat events
• Visibility API for accurate focus/blur detection
• sendBeacon on tab close so unload events are never lost

Admin Dashboard

• Overview — plugin-wide totals: leads, sessions, videos, watch hours
• Leads Report — sortable table of all leads with watch stats and verification status; click any row for the full lead detail view
• Video Analytics — per-video funnel: viewers → starters → completers; average unique watch percent; timeline of activity
• Heatmap UI — color-coded, per-second bar chart showing where viewers engage and where they drop
• Export — download any report as CSV or XLSX

Privacy & Security

• IP addresses can be stored raw, SHA-256 hashed, or not stored at all (configurable per site)
• User-agent storage is opt-in
• Identity tokens are never stored; only their SHA-256 hash (keyed with WP's secure_auth salt) is persisted
• All write endpoints are rate-limited per IP using WordPress transients
• No jQuery dependency — pure vanilla ES5 JavaScript

Requirements

Installation

1. Upload the video-lead-tracker folder to /wp-content/plugins/
2. Activate the plugin from Plugins → Installed Plugins
3. Go to Video Tracker → Settings to configure OTP provider, tracking options, and privacy preferences
4. Place the shortcode on any page or post:

[video_lead_tracker key="my-video" url="https://example.com/video.mp4"]

Shortcode Parameters

Usage Guide

Step 1 — Initial Setup

After activating the plugin, go to Video Lead Tracker → Settings:

Step 2 — Embed the Video

Place the shortcode inside any page or post:

[video_lead_tracker key="demo" url="https://yourdomain.com/video.mp4" title="Product Demo"]

When a visitor arrives at the page:

1. An overlay form asks for their name and mobile number
2. If OTP is enabled, they receive a verification code via SMS
3. After the form is submitted the video unlocks and tracking begins
4. On return visits the visitor is recognised automatically and sees the video directly — no form

Step 3 — Reading the Admin Dashboard

Overview

Once the first visits are recorded, the Overview page shows five KPIs:

• Total Leads — number of unique people who submitted the form
• Verified — leads whose mobile number was confirmed via OTP
• Sessions — total page loads by all visitors
• Videos — number of active videos
• Watch Hours — total deduplicated watch time across all viewers

Below the KPIs you'll find the Recent Leads and Top Videos tables.

Overview data is cached for 5 minutes. The cache is automatically invalidated after each watch-range commit, so live data appears immediately after a viewer watches.

Leads Report

A sortable table of all leads. Columns:

• Name / Mobile — name and masked mobile number
• Verified — OTP confirmed?
• Videos Watched — how many distinct videos this lead has watched
• Avg Watch — progress bar showing their average unique watch percentage
• Sessions — number of sessions

Click any lead's name to open the Lead Detail page:

• Full identity info (unmasked mobile, verification status, first/last seen)
• Video Watch History table (watch %, unique seconds, sessions, completed badge, first play)
• Last 20 Sessions table (browser, device, OS, landing URL)

The Export CSV button at the top downloads all leads with their stats.

Video Analytics

A list of all active videos with aggregate stats. Click any video to open its detail page:

• 5 KPI cards: Viewers, Avg %, Watch Hours, Completions, Sessions
• Watch Distribution: how many viewers fell into each bucket — 0–25%, 25–50%, 50–75%, 75–100%
• Top Viewers: ranked by unique watch percentage, each linked to their Lead Detail page

The Export CSV button downloads all video summary rows.

Heatmap

1. Pick a video from the dropdown — the bar chart loads automatically
2. Each bar represents a time bucket of the video (bucket size auto-scales so there are at most ~120 bars)
3. Toggle between Total Views / Unique Visitors / Unique Leads using the buttons at the top
4. Hover over any bar to see the exact time range and count

How to read it: a short bar means fewer viewers watched those seconds. Tall bars at the start and short bars toward the end = drop-off in the middle of the video. A sudden dip in the middle may indicate a boring segment or a technical issue.

The Export Heatmap CSV button downloads raw per-second data for further analysis in Excel or any BI tool.

Logs

If something goes wrong (OTP delivery failure, database error, aggregation issue), go to Logs:

• Filter by level: Error / Warning / Info / Debug
• Each entry shows the exact timestamp, context (which part of the plugin wrote it), message, and expandable metadata
• The last 200 entries are shown, newest first

OTP Provider Setup

Kavenegar

1. Log in to your Kavenegar panel and copy your API key
2. Go to Video Tracker → Settings → OTP and select Kavenegar
3. Paste your API key and set the sender line number

SMS.ir

1. Go to Video Tracker → Settings → OTP and select SMS.ir
2. Enter your API key
3. Set the template ID for the OTP message pattern

Database Schema

The plugin creates 11 tables (prefixed with wp_vlt_):

Optional tables created on demand:

Schema upgrades are handled automatically via WordPress's dbDelta() on plugin update.

REST API

All endpoints live under /wp-json/vlt/v1/.

Localization

The plugin ships with a full Persian (fa_IR) translation. All user-facing strings in both PHP and JavaScript are wrapped with WordPress's standard __() / _e() functions and the video-lead-tracker text domain.

To add a new language, copy languages/video-lead-tracker.pot and use Poedit or Loco Translate to create a .po file, then compile it to .mo.

Architecture Notes

• No jQuery. All frontend JavaScript is plain ES5, split across two IIFE modules:
  • vlt-frontend.js — session init, form, OTP, page tracking, shared state (window.vltState, window.vltApiFetch)
  • vlt-video-tracker.js — video event and range tracking; boots on the custom vlt:videoReady event
• Static classes. All PHP classes use static methods and a singleton bootstrap (VLT_Plugin::get_instance()) — no instantiation required.
• Manual autoloader. A spl_autoload_register map in the main plugin file replaces Composer autoload to keep the plugin self-contained with zero dependencies.
• Aggregation on write. VLT_Aggregator::aggregate() runs synchronously after every range insert so the summary table is always up to date without background jobs.

License

GPLv2 or later — the same license as WordPress itself.

Author

Mohamad Karim — m-karim.ir