Lesson
Completion Prompt
Two independent features for Tutor LMS: an automatic popup that prompts students to mark a lesson complete at the right moment, and an instant search field for navigating to any lesson in a course.
Overview
Tutor LMS Lesson Completion Prompt adds two independent, separately-toggleable features to Tutor LMS. Each can be enabled or disabled without affecting the other.
Completion Popup
Monitors student engagement on lesson pages and fires a prompt at the right moment — when a video reaches a set percentage, or after a set number of seconds on a text lesson. The student confirms and the lesson is marked complete via AJAX, then navigation moves to the next lesson automatically.
Lesson Search Field
Renders an instant AJAX search field above the curriculum on course, lesson, and assignment pages. Students type any part of a lesson title to jump directly to it — supporting lessons, assignments, and quizzes with color-coded type icons.
The completion popup only shows to logged-in, enrolled students on incomplete lessons. The lesson search field works for all visitors on course, lesson, and assignment pages — enrollment is not required.
Requirements
| Requirement | Details |
|---|---|
| WordPress | 5.8 or higher |
| PHP | 7.4 or higher — enforced at activation; the plugin deactivates itself with an error if the version check fails |
| Tutor LMS | Any current version (Free or Pro) |
| Student (for popup) | Must be logged in and enrolled in the course; lesson must not already be complete |
Lesson pages must not be served from a full-page cache. The popup and search scripts include per-user nonces that must be fresh on each page load. Configure your caching plugin to exclude Tutor LMS lesson pages.
Installation
Upload and activate
- Log in to your WordPress admin dashboard
- Navigate to Plugins → Add New → Upload Plugin
- Select the plugin ZIP file, click Install Now, then Activate Plugin
Activate your license
After activation, navigate to the License Management page:
- If the Ksajie hub is present: Ksajie → Lesson Completion Prompt License
- If no Ksajie hub: Tutor → Lesson Completion Prompt License
Enter your license key and click Activate License. Neither feature will function until a valid license is active.
Configure settings
Navigate to Tutor → Lesson Completion Prompt to review and adjust the defaults: 75% video completion threshold, 60-second text lesson timer, and search field enabled. See the Settings section for full details.
Settings
Navigate to Tutor → Lesson Completion Prompt. The page has three card sections, each with a toggle switch and optional numeric field.
Enable Video Completion Popup
When enabled, the popup fires on video lessons when the playback position reaches the configured percentage. Supports Plyr, YouTube, Vimeo, and HTML5 video.
On by defaultVideo Completion Percentage
The percentage of video duration at which the popup triggers. Accepts 1–100. For most courses, 75–85% balances engagement confirmation with prompt timing.
Default: 75%Enable Non-Video Completion Popup
When enabled, the popup fires on text and reading lessons after the student has been on the page for the configured number of seconds. Also acts as the fallback when no video player is detected on a video lesson.
On by defaultTime on Page (seconds)
Seconds elapsed since page load before the popup fires on text lessons. The timer counts real elapsed time — not active reading time. Set a generous threshold (120–300s) for longer lessons.
Default: 60 secondsEnable Lesson Search Field
When enabled, an instant search field appears above the curriculum accordion on course pages and above the sidebar on lesson pages. Students can find any lesson, assignment, or quiz by partial title match.
On by defaultCompletion Popup
The popup fires automatically when the configured trigger threshold is reached. The student confirms to mark the lesson complete — the action is handled via AJAX, so no page reload is needed for the completion itself.
When the popup appears
Before showing anything, the plugin checks all of the following conditions. If any check fails, the popup is skipped entirely:
- Student is logged in
- Current page is a Tutor LMS lesson page
- Lesson is not already marked complete for this student
- Student is enrolled in the course
- Lesson does not have the offline lesson flag set
- The relevant popup type (video or non-video) is enabled in settings
Popup preview
The popup adapts its text based on whether a next lesson exists in the course:
On the last lesson in a course, the confirm button reads Complete Lesson and the message omits the “move to next” phrasing. The popup can be dismissed with the ✕ button, Not Now, clicking the overlay background, or pressing Escape.
What happens when you confirm
- The confirm button is disabled and shows “Processing…”
- An AJAX request marks the lesson complete using Tutor LMS’s own completion function — the same function used when a student clicks the native Tutor LMS complete button
- If a next lesson exists, the browser navigates to it; if this was the last lesson, the page reloads
- If the request fails, an error alert is shown and the button is re-enabled
Video Player Detection
On video lesson pages, the plugin polls for a supported video player every 500ms for up to 20 seconds. The four player types are checked in priority order — the first one found wins and tracking begins immediately.
window.tutorLessonPlayer exists with a .on() method and a .plyr element or [data-plyr-provider] is in the DOM. Waits for the player’s ready event if not yet initialized.
enablejsapi=1 to the iframe src, loads the YouTube IFrame API, and creates a YT.Player to poll progress.
Vimeo.Player instance, polling progress via its promise-based API.
<video> element is found outside a Plyr wrapper. Polls currentTime and duration directly every second.
To check which player was detected on a specific lesson, open the browser console and type TLVCP.playerType. It returns 'plyr', 'youtube', 'vimeo', 'html5', or null if detection timed out.
Non-Video Lesson Tracking
For text and reading lessons — or as the fallback when no video player is detected — the plugin tracks elapsed time since page load. Once the time threshold set in Settings is reached, the popup fires exactly as it would for a video lesson.
The timer counts real elapsed time since page load, not active reading time. A student who opens the lesson and switches to another tab will still accumulate time. For longer reading lessons, set the threshold to 120–300 seconds so students have a reasonable minimum engagement window before being prompted.
Lesson Search Field
When enabled, an instant search field appears automatically on course, lesson, and assignment pages. Students type at least 2 characters to search across all lessons, assignments, and quizzes in the current course. Results appear in a dropdown with color-coded type icons and the matched text highlighted in yellow.
Where it appears
- Course pages: positioned after the course content title, above the curriculum accordion
- Lesson pages: positioned after the sidebar title, above the sidebar navigation
- Assignment pages: rendered before the content area
What it searches
The search covers all content assigned to topics within the current course: lessons (including video, YouTube, Vimeo, and HTML5 types), assignments, and quizzes. Each result shows a color-coded type icon, the lesson title with matched text highlighted, and the topic it belongs to.
The search uses partial, case-insensitive matching — typing any part of a title will find it. Results link directly to the lesson, assignment, or quiz page.
Search behaviour details
- Input is debounced 300ms — the search only fires after you stop typing briefly
- Minimum 2 characters required before a search fires
- Each new search aborts any in-flight request from the previous keystroke
- Press Escape to clear the input and hide results
- Click anywhere outside the search field to hide the results dropdown
- Works for both logged-in and non-logged-in visitors
Frequently Asked Questions
TLVCP.playerType. It returns 'plyr', 'youtube', 'vimeo', 'html5', or null. A null value after 20 seconds means detection timed out and the plugin fell back to time-on-page tracking._is_offline_lesson post meta flag — lessons with this flag set are automatically skipped by the plugin. As a workaround, offline lesson status can be applied to any lesson you want excluded from the popup..tutor-course-content-title on course pages, or after .tutor-course-single-sidebar-title on lesson pages. If your theme or another plugin renames or removes these elements, the repositioning will not find its target and the field may appear in an unexpected location. Check the browser console for any JavaScript errors related to the search field.tls_search_lessons AJAX request.window.tutorLessonPlayer), which is the first detection priority. YouTube and Vimeo lessons embedded through Tutor LMS Pro are also supported via the dedicated YouTube and Vimeo detection paths.Troubleshooting
- Confirm the license shows Valid on the License Management page
- Confirm the student is logged in and enrolled in the course
- Confirm the lesson is not already marked complete for that student
- Confirm the lesson does not have the offline lesson flag set (
_is_offline_lesson = 1) - Confirm the relevant enable toggle (video or non-video) is on in settings
- If using a caching plugin, confirm lesson pages are excluded from full-page caching — stale cached pages will have invalid nonces
- Open the browser console and check that
tlvcpDatais present in the page source
- Open the browser Network tab and look for the
tlvcp_complete_lessonAJAX request — check its response for an error - Confirm the student is still enrolled — enrollment is re-checked server-side at the moment of completion
- Confirm the
tlvcp_noncenonce is present in the page source (search fortlvcpData)
Check which player was detected by opening the browser console and typing TLVCP.playerType. If it returns null, detection timed out and the plugin is using time-on-page tracking instead. Common causes:
- The video player loads later than the 20-second detection window — check for slow-loading third-party embeds
- A theme or plugin conflict prevents
window.tutorLessonPlayerfrom being set before the detection window closes - YouTube or Vimeo iframes with modified URLs that don’t match the expected patterns — the plugin checks for
youtube.com,youtu.be, andvimeo.comin the iframe src
- Confirm the Enable Lesson Search Field toggle is on in Tutor → Lesson Completion Prompt
- Check the browser console for JavaScript errors and confirm
tlsDatais present in the page source - If the field appears but search does nothing, confirm the page is not cached without the script localization data
- If the field appears in the wrong position, check that
.tutor-course-content-title(course pages) or.tutor-course-single-sidebar-title(lesson pages) exists in the DOM — the plugin uses these elements for repositioning
Support
Need help? Visit the support portal
If you’re experiencing an issue not covered in this documentation or the troubleshooting section, submit a support request through the portal. Please include the details below to help resolve your issue as quickly as possible.
Open Support Portal →TLVCP.playerType in the browser console (for popup issues)