Download the PHP package rajendra/youtube-progress without Composer

Rajendra YouTube Progress

Enterprise-grade YouTube video progress tracking for Laravel with anti-cheat detection, segment-based verification, and LMS-optimized completion tracking.

That single line loads the YouTube IFrame API, tracks watch progress with verified watched segments, blocks forward-skip cheating, saves progress to Local Storage, and resumes playback on the viewer's next visit — automatically.

Table of Contents

• Why v1.0.2
• Requirements
• Installation
• Configuration
• Usage
  • Blade component
  • Anti-cheat options
  • Progress bar component
  • Helper function
  • Facade
  • Multiple videos on one page
• How anti-cheat tracking works
• Storage format
• Events
• Developer callbacks
• Public JavaScript API
• Configuration reference
• Security
• Accessibility
• Performance
• Browser & platform support
• Migration from v1.0.0
• Example app
• Testing
• FAQ
• Troubleshooting
• License

Why v1.0.2

In v1.0.0, a student could cheat by dragging the YouTube seek bar to the end of a video, instantly receiving course completion. v1.0.2 solves this with a comprehensive anti-cheat system:

Completion now requires actually watching the required percentage of the video. No workarounds, no shortcuts.

Requirements

Installation

Laravel's package auto-discovery registers the service provider and facade automatically.

Publish the config file and the compiled JS/CSS assets:

You can publish each piece independently:

Configuration

Every key can also be set via .env:

Usage

Blade component

With options:

video accepts a bare 11-character ID or a full YouTube URL (watch?v=, youtu.be/, embed/, shorts/) — it's normalized to an ID internally.

Anti-cheat options

Progress bar component

A standalone indicator that syncs with the player via events:

Helper function

Facade

Multiple videos on one page

Each gets a unique generated player ID and fully independent progress tracking. The IFrame API is loaded exactly once.

How anti-cheat tracking works

Segment-based progress

Instead of storing a single currentTime number, the package stores an array of watched segments — time ranges the viewer has actually watched:

Overlapping segments are merged automatically. The unique watched duration is the sum of all segment lengths.

Completion algorithm

A video is marked completed only when this percentage reaches completion_percentage (default 95%). Dragging the seek bar to the end does not count as watched.

Forward seek prevention

When prevent_forward_seek is enabled (default), the player tracks maxWatchedTime — the farthest point reached through normal playback. Any attempt to seek beyond this boundary:

1. Automatically snaps the player back to maxWatchedTime
2. Displays a toast notification
3. Dispatches a youtube-progress:blocked event

Playback verification

Watched time is only counted while the YouTube player state is PLAYING. The following states are ignored:

• BUFFERING — no time counted during buffer stalls
• PAUSED — no time counted while paused
• UNSTARTED — no time counted before first play
• ENDED — segment finalized from last position to duration

Speed monitoring

If playback speed exceeds maximum_allowed_speed (default 2x), the tracking system pauses segment recording and dispatches a youtube-progress:speed-warning event. Speed is checked on every tracking tick.

Storage format

Everything lives in localStorage. Each video gets a key: {prefix}{videoId}.

Saved automatically:

• Every save_interval milliseconds while playing
• On pause (includes final segment before pause)
• On video end (segment finalized to duration)
• When the tab becomes hidden (visibilitychange)
• On page unload/refresh/close (beforeunload and pagehide)

Events

All events are dispatched on document as native CustomEvents:

Developer callbacks

Pass JavaScript function names as Blade attributes:

Public JavaScript API

Access via window.YouTubeProgress:

Configuration reference

Blade component attributes

Security

• Video IDs/URLs are validated against ^[A-Za-z0-9_-]{11}$ before reaching the DOM; invalid values throw InvalidArgumentException.
• All Blade output goes through automatic {{ }} escaping.
• No eval(), no innerHTML with untrusted input, no inline handlers.
• No data leaves the browser — no backend endpoint, no database, no network call other than the YouTube IFrame API itself.

Accessibility

• Player wrapper has role="region" and aria-label="YouTube video player".
• Progress bars include role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax, and aria-label.
• Toast notifications use role="alert" and aria-live="assertive" for screen reader announcements.
• Debug overlay includes aria-label for context.
• Keyboard focus styling on the player wrapper (:focus-within outline).
• YouTube's built-in keyboard controls (spacebar, arrows) work natively.

Performance

• Single YouTube IFrame API instance per page regardless of player count.
• Lazy initialization — players only initialize when the API is ready.
• Debounced localStorage writes via configurable save_interval.
• Segment merge algorithm runs in O(n log n) due to sort; typically O(n) since segments arrive in order and rarely need re-sorting.
• Minimal DOM manipulation — only updates progress bar width/text and debug overlay text content.

Browser & platform support

Desktop: Chrome, Firefox, Safari, Edge, Opera. Mobile: Android and iOS (responsive layout via CSS aspect-ratio).

Migration from v1.0.0

Automatic. When the package reads an old localStorage record (no version field), it automatically migrates it to the v1.0.2 segment format:

• Old currentTime becomes the initial segment [[0, currentTime]]
• maxWatchedTime is set to currentTime
• The migrated record is saved immediately

No data is lost. Students retain their existing progress. The migration happens transparently on the first page load after upgrading.

If you need to handle this in your own code:

Example app

See example-app/ for a minimal consumer app demonstrating: anti-cheat player, debug overlay, light theme, free-seeking mode, standalone progress bar, multiple players, public API usage, and live event logging.

Testing

The suite covers:

• Video ID resolution and validation (bare IDs, watch URLs, youtu.be, embed, shorts)
• Storage key generation with custom prefixes
• All jsConfig() keys including anti-cheat options
• Anti-cheat config defaults and custom values
• Blade component rendering with all new attributes
• Prevent-seek, show-debug, theme, callback data attributes
• Inline progress bar rendering
• ARIA accessibility attributes
• Backward compatibility with minimal component usage
• Unique player ID generation
• The youtube_progress() helper function
• Config merging with expected defaults

FAQ

Does this require a database? No. All progress lives in the visitor's browser via localStorage.

Does progress sync across devices? No — by design. Use youtube-progress:saved to persist to your own server.

Can students still cheat? The anti-cheat system makes cheating significantly harder. Forward seeks are blocked, completion requires actual watched time, and speed abuse is detected. Dedicated attackers with browser dev tools could theoretically modify localStorage directly — for server-side verification, listen to youtube-progress:saved and validate against your own records.

Can I use this with Livewire, Inertia, or Turbo? Yes. Dispatch youtube-progress:rescan on document after injecting new players into the DOM:

What happens if localStorage is unavailable? Reads/writes are wrapped in try/catch; playback still works, it just won't persist progress.

Can I style the player or progress bar? Override .yt-progress-wrapper, .yt-progress-player, .yt-progress-bar-track, .yt-progress-bar-fill, .yt-progress-bar-label, .yt-progress-toast, or .yt-progress-debug in your CSS, or publish the views to change the markup.

Troubleshooting

License

MIT. See LICENSE.