TimeLock Video Widget - WordPress Plugin

A complete WordPress plugin that displays videos with time-based restrictions. Once playback starts, users have a limited viewing time before the video gets locked with an overlay (not hidden). IP-based tracking prevents re-watching until reset.

✅ ALL ISSUES FIXED

1. ✅ Classic Widget - Now properly registered and appears in Widgets panel
2. ✅ Elementor Support - Full Elementor widget included
3. ✅ YouTube Support - Upload video OR use YouTube URL
4. ✅ Locked Overlay - Video shows overlay message instead of disappearing
5. ✅ Custom Messages - Backend control for locked message text

🎯 Key Features

Video Options

• Upload Videos - MP4 files from media library
• YouTube URLs - Paste any YouTube link
• Responsive Player - Works on all devices

Time Controls

• Watch Timer - Starts countdown when video plays (not on page load!)
• IP Tracking - One view per IP until reset
• Locked Overlay - Shows custom message when time expires
• Video Stays Visible - User sees what they're missing

Scheduling

• Start/End Dates - Set availability windows per widget
• Countdown Timer - Optional visual timer (overlay or below)
• Custom Position - Choose where countdown appears

Access Control

• Whitelist IPs - Allow unlimited access for specific IPs
• Blacklist Countries - Block specific regions (requires API)
• Auto IP Cleanup - Schedule automatic IP reset (7-90 days)

Platform Support

• ✅ Classic Widgets - Sidebar, footer, widget areas
• ✅ Gutenberg Blocks - Modern block editor
• ✅ Elementor - Drag & drop page builder

📦 Installation

File Structure

Create this exact structure in /wp-content/plugins/:

timelock-video-widget/
├── timelock-video-widget.php          (Main plugin file)
├── includes/
│   ├── class-widget.php               (Classic widget)
│   ├── class-elementor-widget.php     (Elementor widget)
│   ├── class-settings.php             (Admin settings)
│   └── class-renderer.php             (Gutenberg renderer)
├── assets/
│   ├── css/
│   │   ├── frontend.css               (Frontend styles)
│   │   └── admin.css                  (Admin styles)
│   └── js/
│       ├── frontend.js                (Frontend logic)
│       ├── admin.js                   (Admin logic)
│       └── block-editor.js            (Gutenberg block)
└── README.md

Steps

1. Upload Files

   • Create folder timelock-video-widget in /wp-content/plugins/
   • Upload ALL files maintaining folder structure
   • Verify file permissions (755 folders, 644 files)

2. Activate Plugin

   • Go to WordPress Admin → Plugins
   • Find "TimeLock Video Widget"
   • Click Activate

3. Verify Database

   • Plugin creates table: wp_tlvw_views
   • Check in phpMyAdmin if needed

4. Configure Settings (Optional)

   • Go to TimeLock Video menu
   • Set default watch time (30 seconds recommended)
   • Set default locked message
   • Configure IP cleanup schedule

🎬 Usage

Classic Widget (Sidebars/Footers)

1. Go to Appearance → Widgets
2. Find "TimeLock Video" widget
3. Drag to desired area
4. Configure:
   • Video Type: Upload or YouTube
   • Select Video or paste YouTube URL
   • Watch Time: Seconds before lock (e.g., 30)
   • Show Countdown: Enable/disable
   • Countdown Position: Overlay or below
   • Locked Message: Custom text when locked
5. Save widget

Gutenberg Block

1. Edit page/post
2. Click (+) → Search "TimeLock Video"
3. Insert block
4. Select video or enter YouTube URL
5. Configure in sidebar:
   • Watch time
   • Countdown settings
   • Schedule dates
   • Locked message
6. Publish

Elementor Widget

1. Edit page with Elementor
2. Search for "TimeLock Video" widget
3. Drag to canvas
4. Configure:
   • Video Settings tab: Choose upload/YouTube
   • Countdown tab: Enable and position
   • Schedule tab: Set date range
   • Locked Message tab: Custom text
5. Update page

⚙️ Settings Page

Navigate to TimeLock Video in admin menu:

Basic Settings

• Default Watch Time: Global default (30 seconds)
• Default Locked Message: Default overlay text
• IP Cleanup Schedule: Auto-clear IPs (7/14/30/60/90 days or manual)

Access Control

• Whitelist IPs: Comma-separated IPs with unlimited access
• Blacklist Countries: Block specific regions (requires geo API)

Statistics

• Total views recorded
• Unique IP addresses
• Export IP list as CSV

Actions

• Clear All IPs: Reset all restrictions
• Export IP List: Download CSV

🔧 How It Works

User Experience

1. Page Load: Video visible and playable
2. Click Play: Timer starts (NOT on page load!)
3. Watch Video: Countdown shows remaining time
4. Time Expires:
   • Video pauses automatically
   • Locked overlay appears with custom message
   • Video player stays visible but locked
5. Returning Visit: Overlay shown immediately

Technical Flow

User visits page
    ↓
Check IP status (AJAX)
    ↓
[Already viewed?]
├─ Yes → Show locked overlay
└─ No → Allow playback
         ↓
    User clicks play
         ↓
    Record IP + Start time
         ↓
    Start countdown
         ↓
    [Time expired?]
    └─ Yes → Pause + Show overlay
              ↓
         Block IP for future visits

💡 Best Practices

Recommended Settings

Flash Sales (High Urgency)

Watch Time: 15-30 seconds
Countdown: Yes, overlay
Message: "⚡ Time's up! This exclusive offer ends soon. Act now!"

Webinar Preview

Watch Time: 60-120 seconds
Countdown: Yes, below video
Message: "Want to see more? Register for the full webinar at [link]"

Product Demo

Watch Time: 45 seconds
Countdown: Yes, overlay
Message: "Ready to buy? Get instant access: [CTA button]"

Testing Your Setup

1. Add Your IP to Whitelist during setup
2. Test all features with whitelist enabled
3. Remove IP from whitelist
4. Test from different device/network
5. Verify locked overlay appears
6. Check IP recorded in statistics

Video File Tips

• MP4 Format: Best compatibility
• File Size: Under 10MB for fast loading
• Resolution: 720p or 1080p
• Length: 1-3 minutes ideal for teasers

YouTube Tips

• Use full URL: https://www.youtube.com/watch?v=VIDEO_ID
• Or short URL: https://youtu.be/VIDEO_ID
• Video must be public or unlisted
• Embedded video follows YouTube's terms

🎨 Customization

CSS Classes

.tlvw-container { }              /* Main wrapper */
.tlvw-video-wrapper { }          /* Video container */
.tlvw-video { }                  /* HTML5 video element */
.tlvw-youtube-container { }      /* YouTube wrapper */
.tlvw-youtube-player { }         /* YouTube iframe */
.tlvw-countdown { }              /* Countdown timer */
.tlvw-countdown-overlay { }      /* Timer on video */
.tlvw-countdown-below { }        /* Timer below video */
.tlvw-countdown-urgent { }       /* Last 10 seconds */
.tlvw-locked-overlay { }         /* Lock overlay */
.tlvw-locked-content { }         /* Lock message content */
.tlvw-lock-icon { }              /* Lock emoji/icon */
.tlvw-locked-text { }            /* Lock message text */

Custom Lock Overlay Style

Add to your theme's CSS:

/* Gradient background */
.tlvw-locked-overlay {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
}

/* Larger lock icon */
.tlvw-lock-icon {
    font-size: 96px !important;
}

/* Custom text style */
.tlvw-locked-text {
    font-size: 24px !important;
    text-shadow: 0 2px 4px rgba(0,0,0,0.3);
}

🔍 Troubleshooting

Widget Not Appearing in Classic Editor

Solution:

1. Deactivate and reactivate plugin
2. Check includes/class-widget.php exists
3. Clear WordPress cache
4. Try refreshing widgets page

Elementor Widget Missing

Solution:

1. Ensure Elementor is active
2. Check includes/class-elementor-widget.php exists
3. Clear Elementor cache (Elementor → Tools → Regenerate)
4. Refresh page

Video Not Playing

Solution:

1. Check video URL is valid
2. Test video directly in browser
3. Check browser console (F12) for errors
4. Verify JavaScript loaded (tlvw-frontend.js)

Countdown Not Showing

Solution:

1. Ensure "Show Countdown" is enabled
2. Video must be playing (click play!)
3. Check CSS file loaded
4. Try changing position (overlay → below)

Locked Overlay Not Appearing

Solution:

1. Wait for full countdown to finish
2. Check JavaScript console for errors
3. Verify CSS loaded (frontend.css)
4. Clear browser cache

IP Not Being Tracked

Solution:

1. Check database table exists (wp_tlvw_views)
2. Check AJAX working (Network tab in browser)
3. Verify nonce not expired
4. Check PHP error logs

YouTube Video Issues

Solution:

1. Video must be public or unlisted
2. Use full YouTube URL
3. Check if YouTube API loaded
4. Some embedded videos may have restrictions

🚀 Pro Tips

1. Create Urgency: Use 15-30 second timers for maximum impact
2. Strong CTA: Include call-to-action in locked message
3. A/B Testing: Try different messages and times
4. Mobile First: Test on mobile devices
5. Clear IP Weekly: Keep data fresh for campaigns

📊 Analytics Integration

Google Analytics

Add to functions.php:

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        $('.tlvw-container').on('tlvw:locked', function() {
            if (typeof gtag !== 'undefined') {
                gtag('event', 'video_locked', {
                    'event_category': 'Video',
                    'event_label': 'TimeLock Expired'
                });
            }
        });
    });
    </script>
    <?php
});

🔐 Security

• Nonce verification on all AJAX calls
• Prepared SQL statements
• Capability checks for admin functions
• XSS protection with escaping
• CSRF protection

📄 License

GPL v2 or later

🆘 Support

1. Check this README
2. Review troubleshooting section
3. Enable WP_DEBUG in wp-config.php
4. Check browser console (F12)
5. Check PHP error logs

Built for your business success! 🚀💰