🛡️ PaywallProtect Widget

JavaScript widget for protecting content from AI bots while allowing human visitors.

Configured for: [email protected]

Quick Start

1. Generate Your Credentials

node setup.js

This will create:

• A unique Site ID
• A unique API Key
• A configuration file (widget-config.html)

2. Add Widget to Your Site

Copy this code and paste it before the closing </body> tag on your website:

<script
  src="dist/paywall-widget.min.js"
  data-site-id="YOUR_SITE_ID"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_SUPABASE_URL/functions/v1"
  data-debug="true"
  async
></script>

Get your credentials from:

• Run node setup.js to generate them
• OR create a site in the Dashboard

3. That's It!

The widget will automatically:

• ✅ Allow all humans - No interruption for real visitors
• ❌ Block AI bots - GPTBot, ClaudeBot, CCBot, etc.
• ✅ Allow SEO bots - Google, Bing, etc. for search indexing
• 📊 Log everything - View traffic in your dashboard

Default Behavior

The widget is pre-configured to ONLY block bots:

| Visitor Type | Behavior | |--------------|----------| | 👤 Humans | ✅ Always allowed - no paywall | | 🤖 AI Bots (GPTBot, ClaudeBot) | ❌ Blocked | | 🔍 SEO Bots (Google, Bing) | ✅ Allowed | | 🕷️ Scrapers | ❌ Blocked |

You will NEVER see a paywall as a human visitor - this is the default configuration.

Configuration Options

Customize widget behavior with data attributes:

<script
  src="dist/paywall-widget.min.js"
  data-site-id="site_xxx"
  data-api-key="pk_live_xxx"
  data-api-url="https://your-project.supabase.co/functions/v1"

  <!-- Optional Configuration -->
  data-debug="true"              <!-- Enable debug logging -->
  data-mode="auto"               <!-- auto | always | never -->
  data-seo-safe="true"           <!-- Allow search engine bots -->
  data-protect-body="true"       <!-- Protect entire page -->
  data-subscribe-url="/subscribe" <!-- Custom subscribe URL -->
  data-login-url="/login"        <!-- Custom login URL -->
  async
></script>

Available Modes

• auto (default) - Automatically detect bots and block them
• always - Always show paywall (for testing)
• never - Disable widget entirely

Dashboard Setup

Option 1: Using the Dashboard (Recommended)

1. Go to http://localhost:5173/dashboard
2. Sign in with [email protected]
3. Click "Add New Site"
4. Enter your site details:
   • Site Name: "My Website"
   • Domain: "example.com"
5. Copy the Site ID and API Key shown
6. Add the widget code to your site

Option 2: Automatic Setup Script

Run the setup script to generate credentials automatically:

node setup.js

This creates a widget-config.html file with your unique credentials and integration instructions.

Testing the Widget

View Demo Page

open demo.html

The demo page shows:

• How the widget integrates
• Debug controls
• Configuration examples

Debug in Browser Console

Once the widget is loaded, you can use these commands in the browser console:

// View current status
PaywallProtect.debug.status()

// View all logs
PaywallProtect.logs.getAll()

// Download logs as JSON
PaywallProtect.logs.download()

// Export logs to console
console.log(PaywallProtect.logs.export())

// Test paywall display
PaywallProtect.showPaywall({ type: 'hard' })

// Hide paywall
PaywallProtect.hidePaywall()

// Force reload/recheck
PaywallProtect.reload()

Testing with Different User Agents

Test bot detection by changing your user agent:

# Using curl (will be detected as bot)
curl http://localhost:5173

# Using a bot user agent
curl -A "GPTBot/1.0" http://localhost:5173

Building the Widget

Development

# Install dependencies
npm install

# Build the widget
npm run build

This creates:

• dist/paywall-widget.min.js - Minified IIFE version
• dist/paywall-widget.esm.js - ESM module version

Distribution

The built files can be:

• Hosted on your CDN
• Included directly in your site
• Distributed via npm

How It Works

1. Widget loads on your page
2. Fingerprints browser - Collects canvas, WebGL, plugins, timing data
3. Checks user agent - Identifies known bots
4. Calls API - Sends fingerprint to your backend
5. Backend decides - Bot detection + paywall logic
6. Widget responds:
   • If bot: Silently blocked
   • If human: Full access (by default)
   • If paywall enabled for humans: Shows paywall UI

Allowed Bots (SEO-Safe)

These bots are allowed by default for SEO:

• Googlebot (Google Search)
• Bingbot (Bing Search)
• DuckDuckBot (DuckDuckGo)
• Baiduspider (Baidu)
• Yandexbot (Yandex)
• FacebookExternalHit (Facebook previews)
• TwitterBot (Twitter cards)
• LinkedInBot (LinkedIn previews)
• SlackBot (Slack previews)

Blocked Bots

These bots are automatically blocked:

• GPTBot (OpenAI)
• ClaudeBot (Anthropic)
• CCBot (Common Crawl)
• Cohere-AI (Cohere)
• Generic scrapers (curl, wget, python-requests, scrapy)

API Reference

JavaScript API

// Global PaywallProtect object
window.PaywallProtect = {
  version: '1.2.1',

  // Manual controls
  showPaywall: (config) => {},
  hidePaywall: () => {},
  checkAccess: () => Promise,
  reload: () => {},

  // Configuration
  config: { ... },
  allowedBots: [ ... ],

  // Logging
  logs: {
    getAll: () => Array,
    export: () => String,
    clear: () => void,
    download: () => void
  },

  // Debug helpers
  debug: {
    enable: () => void,
    disable: () => void,
    status: () => void
  }
}

Troubleshooting

Widget not loading?

Check browser console for errors:

// Expected output:
[PaywallProtect] Initializing PaywallProtect Widget
[PaywallProtect] ✓ Configuration validated
[PaywallProtect] ✓ Access granted, no protection applied
[PaywallProtect] ✓ PaywallProtect initialization complete

Seeing "Missing required configuration"?

Make sure you have:

• data-site-id="..."
• data-api-key="..."
• data-api-url="..."

All three are required.

Getting "payment required" as a human?

This means your site configuration has showPaywallToHumans: true.

To fix:

1. Go to your Dashboard
2. Find your site and click "Configure"
3. Ensure "Show Paywall to Humans" is disabled

The default is disabled - only bots are blocked.

Widget not blocking bots?

Check that your API endpoint is working:

// In browser console
fetch('YOUR_SUPABASE_URL/functions/v1/check-access', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    siteId: 'YOUR_SITE_ID',
    apiKey: 'YOUR_API_KEY',
    page: '/',
    userAgent: navigator.userAgent,
    fingerprint: {}
  })
}).then(r => r.json()).then(console.log)

Support

• Dashboard: http://localhost:5173/dashboard
• Demo: http://localhost:5173/demo
• Email: [email protected]

License

MIT License - See LICENSE file for details

Made with ❤️ for protecting content from AI bots