JUMBLE

๐Ÿ›ก๏ธ SEO-Safe Bot Detection & Content Protection ๐Ÿค–

Smart bot detection that protects your content from scrapers while allowing search engines to index your site properly. Google, Bing, and social platforms see real content while malicious bots see scrambled content. SEO protection enabled by default!

๐Ÿ“ฆ View on NPM Registry ๐Ÿ”— Source Code on GitHub

Compatible with all major frameworks:

React
Vue
Angular
Svelte
JavaScript
TypeScript

๐ŸŽ›๏ธ Demo Controls

Human Mode

๐Ÿ’ก ๐Ÿค–โ†”๏ธ๐Ÿ‘ค = ๐Ÿ” โ€ข ๐Ÿ”„ = ๐Ÿ“„โœจ

๐Ÿ›ก๏ธ SEO-Safe Bot Detection Demo

๐Ÿ” SEO-Safe Protection (Default)

Smart bot detection that protects content from scrapers while preserving SEO:

  • โœ… Google, Bing, Yahoo โ†’ See real content for indexing
  • โœ… Facebook, Twitter, LinkedIn โ†’ See real content for social previews
  • โœ… SEO tools (SEMrush, Ahrefs) โ†’ See real content for analysis
  • โŒ Scrapers & headless browsers โ†’ See scrambled content
  • โŒ AI training bots โ†’ See scrambled content
  • โŒ Content harvesters โ†’ See obfuscated media

SEO protection is enabled by default - no configuration needed!

๐Ÿ“ Text Content Protection

This text content will be scrambled for malicious bots but remain readable for humans and legitimate search engine crawlers like Googlebot and Bingbot.

The component uses intelligent allowlisting and 14+ detection methods to distinguish between legitimate and malicious visitors.

Web development involves creating websites and web applications using various technologies like HTML, CSS, and JavaScript.

๐Ÿ–ผ๏ธ Media Content Protection

Images and videos are also protected from bot scraping:

Sample Images

These images will be replaced with placeholders if a bot is detected:

Sample landscape image Sample portrait image

Sample Video

Video sources and poster images are cleared for bots:

๐Ÿ›ก๏ธ How SEO-Safe Detection Works

The component uses intelligent 3-tier detection to distinguish between legitimate and malicious bots:

  1. SEO Allowlist Check - Legitimate search engines bypass protection
  2. Malicious Pattern Detection - Known scraper signatures are blocked
  3. Advanced Analysis - 14+ behavioral detection methods for unknown bots

Supported Search Engines: Google, Bing, Yahoo, DuckDuckGo, Yandex, Baidu + social platforms

๐Ÿ›ก๏ธ Protection Features

When a bot is detected, the following protections activate:

  • Text Scrambling: All text content gets character-level obfuscation
  • Image Protection: Image sources are replaced with placeholder data
  • Video Protection: Video sources and posters are cleared
  • Backup Preservation: Original content is stored for potential restoration

๐ŸŒ Multi-Language Support

The component intelligently handles different writing systems and character sets:

๐Ÿ‡บ๐Ÿ‡ธ English (Latin Script)

Hello World! Welcome to our website.

This is a sample paragraph in English that demonstrates Latin character scrambling for bot protection.

Latin characters (a-z, A-Z) get scrambled to random letters

๐Ÿ‡ธ๐Ÿ‡ฆ Arabic (Arabic Script)

ู…ุฑุญุจุงู‹ ุจูƒู… ููŠ ู…ูˆู‚ุนู†ุง ุงู„ุฅู„ูƒุชุฑูˆู†ูŠ

ู‡ุฐุง ู†ุต ุชุฌุฑูŠุจูŠ ุจุงู„ู„ุบุฉ ุงู„ุนุฑุจูŠุฉ ู„ุฅุธู‡ุงุฑ ูƒูŠููŠุฉ ุญู…ุงูŠุฉ ุงู„ู…ุญุชูˆู‰ ู…ู† ุงู„ุจุฑุงู…ุฌ ุงู„ุขู„ูŠุฉ

Arabic characters get scrambled to random Arabic script characters

๐Ÿ‡จ๐Ÿ‡ณ Chinese (CJK Script)

ๆฌข่ฟŽ่ฎฟ้—ฎๆˆ‘ไปฌ็š„็ฝ‘็ซ™

่ฟ™ๆ˜ฏไธ€ไธชไธญๆ–‡็คบไพ‹ๆฎต่ฝ๏ผŒๅฑ•็คบไบ†ๅฏนไธญๆ—ฅ้Ÿฉ็ปŸไธ€่กจๆ„ๆ–‡ๅญ—็š„ไฟๆŠคๆœบๅˆถ

CJK characters get scrambled to random Chinese ideographs

๐Ÿ”ข Numbers & Symbols

Phone: +1 (555) 123-4567

Price: $29.99 | Discount: 15% off!

Email: contact@example.com

Numbers, punctuation, and symbols remain unchanged

๐ŸŒ Mixed Content Example

Welcome! ุฃู‡ู„ุงู‹ ูˆุณู‡ู„ุงู‹ ๆฌข่ฟŽ - Phone: (555) 123-4567

This demonstrates mixed-language content: English + ุงู„ุนุฑุจูŠุฉ + ไธญๆ–‡ + Numbers 2024

Each character set is handled according to its script type while preserving structure

๐Ÿ”ง How Language Detection Works:

  • Latin Characters (a-z, A-Z): Scrambled to random lowercase letters (a-z)
  • Arabic Script (0x0600-0x06FF): Scrambled to random Arabic characters
  • CJK Ideographs (0x4E00-0x9FFF): Scrambled to random Chinese characters
  • Numbers (0-9): Left unchanged for functionality
  • Punctuation & Symbols: Preserved to maintain readability structure
  • Emojis: Remain unchanged

โš ๏ธ Note: This protection works automatically and transparently. Legitimate users and search engines see normal content, while bots see scrambled/obfuscated content.

๐Ÿ’ป Correct Usage

<!DOCTYPE html>
<html lang="en" class="jumble-init">
<head>
<!-- CRITICAL: Hide content during 100ms bot detection -->
<style>
html.jumble-init * { visibility: hidden !important; }
</style>
<!-- Load Jumble scripts -->
<script type="module" src="https://unpkg.com/@4884org/jumble@latest/dist/jumble/jumble.esm.js"></script>
</head>
<body>
<!-- SEO-safe bot protection (place early in body) -->
<jumble-head></jumble-head>
<!-- Content protected from scrapers, visible to SEO -->
<p>Googlebot sees this, scrapers see scrambled text</p>
<img src="seo-friendly.jpg" alt="Images protected from bots">
<video src="content.mp4" controls></video>
</body>
</html>

๐Ÿ“ˆ SEO Benefits: Search engines index your content normally while scrapers are blocked!

๐Ÿ“ฆ Installation

๐Ÿ“ฆ NPM Installation

Install via npm for maximum flexibility and version control:

npm install @4884org/jumble

๐ŸŒ CDN Installation

Quick setup via CDN for rapid prototyping:

<script type="module" src="https://unpkg.com/@4884org/jumble@latest/dist/jumble/jumble.esm.js"></script>

๐Ÿš€ Basic Usage

Universal Setup: Add the script tags to your HTML head, place <jumble-head> early in your body, and include the critical CSS for 100ms protection timing.

๐ŸŒ HTML Implementation (Works with any framework)
<!DOCTYPE html>
<html lang="en" class="jumble-init">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Protected Content</title>

<!-- CRITICAL: Hide content during 100ms bot detection -->
<style>
html.jumble-init * {
visibility: hidden !important;
}
</style>

<!-- Jumble component scripts -->
<script type="module"
src="https://unpkg.com/@4884org/jumble@latest/dist/jumble/jumble.esm.js">
</script>
</head>
<body>
<!-- Initialize bot protection (place early in body) -->
<jumble-head></jumble-head>

<main>
<h1>Your content will be protected automatically</h1>
<p>This text will be scrambled for bots but readable for humans.</p>
<img src="image.jpg" alt="This image will be hidden from bots">
<video src="video.mp4" controls></video>
</main>
</body>
</html>

๐Ÿ”ง Framework Integration

Universal Approach: The setup is the same for all frameworksโ€”load the library in your build tool, then add <jumble-head> to your HTML body. The component works at the browser level, not the framework level.

โš ๏ธ Important: Always include the jumble-init class on your <html> element and the CSS rule to hide content during the brief 100ms detection period.

โš›๏ธ React

// 1. Install the component
npm install @4884org/jumble

// 2. In your main index.js or App.js
import { defineCustomElements } from '@4884org/jumble/loader';

// Initialize the custom elements
defineCustomElements();

// 3. Update your public/index.html
/*
<html lang="en" class="jumble-init">
<head>
<meta charset="utf-8" />
<title>React App</title>
<style>
html.jumble-init * { visibility: hidden !important; }
</style>
</head>
<body>
<div id="root"></div>
<jumble-head></jumble-head>
</body>
</html>
*/

// Your React components work normally
function App() {
return (
<div>
<h1>Your protected content</h1>
<p>This text will be automatically protected</p>
</div>
);
}

๐ŸŸข Vue.js

// 1. Install the component
npm install @4884org/jumble

// 2. In your main.js or main.ts
import { createApp } from 'vue';
import { defineCustomElements } from '@4884org/jumble/loader';
import App from './App.vue';

// Initialize the custom elements
defineCustomElements();

createApp(App).mount('#app');

// 3. Update your public/index.html
/*
<html lang="en" class="jumble-init">
<head>
<meta charset="UTF-8">
<title>Vue App</title>
<style>
html.jumble-init * { visibility: hidden !important; }
</style>
</head>
<body>
<div id="app"></div>
<jumble-head></jumble-head>
</body>
</html>
*/

// Your Vue components work normally
<template>
<div>
<h1>Your protected content</h1>
<p>This text will be automatically protected</p>
</div>
</template>

๐Ÿ…ฐ๏ธ Angular

// 1. Install the component
npm install @4884org/jumble

// 2. In your main.ts
import { defineCustomElements } from '@4884org/jumble/loader';

// Initialize the custom elements
defineCustomElements();

// 3. In your app.module.ts (for custom elements support)
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

@NgModule({
declarations: [AppComponent],
imports: [BrowserModule],
schemas: [CUSTOM_ELEMENTS_SCHEMA],
bootstrap: [AppComponent]
})
export class AppModule { }

// 4. Update your src/index.html
/*
<html lang="en" class="jumble-init">
<head>
<meta charset="utf-8">
<title>Angular App</title>
<style>
html.jumble-init * { visibility: hidden !important; }
</style>
</head>
<body>
<app-root></app-root>
<jumble-head></jumble-head>
</body>
</html>
*/

// Your Angular components work normally
// app.component.html:
<div>
<h1>Your protected content</h1>
<p>This text will be automatically protected</p>
</div>

โšก Svelte

// 1. Install the component
npm install @4884org/jumble

// 2. In your main.js
import App from './App.svelte';
import { defineCustomElements } from '@4884org/jumble/loader';

// Initialize the custom elements
defineCustomElements();

const app = new App({
target: document.getElementById('app'),
});

export default app;

// 3. Update your public/index.html
/*
<html lang="en" class="jumble-init">
<head>
<meta charset="UTF-8">
<title>Svelte App</title>
<style>
html.jumble-init * { visibility: hidden !important; }
</style>
</head>
<body>
<div id="app"></div>
<jumble-head></jumble-head>
</body>
</html>
*/

// Your Svelte components work normally
// App.svelte:
<main>
<h1>Your protected content</h1>
<p>This text will be automatically protected</p>
</main>

โš™๏ธ Component Attributes Reference

The <jumble-head> component accepts the following attributes for customization:

Attribute Type Default Description
allow-seo boolean true Controls SEO protection mode. When true, legitimate search engines see real content. When false, ALL bots see scrambled content.
custom-allowlist string[] [] JSON array of additional bot patterns to allow (added to default search engines). Case-insensitive matching.
custom-denylist string[] [] JSON array of additional bot patterns to block (added to default malicious patterns). Case-insensitive matching.

โœ… Basic Usage Examples

<!-- โœ… Recommended: SEO-safe (default behavior) -->
<jumble-head></jumble-head>

<!-- ๐Ÿ”’ Maximum protection: Block ALL bots (including search engines) -->
<jumble-head allow-seo="false"></jumble-head>

<!-- ๐ŸŽฏ Custom allowlist: Allow your partner's bot -->
<jumble-head custom-allowlist='["mypartnerbot", "trustedapi"]'></jumble-head>

<!-- ๐Ÿšซ Custom denylist: Block specific scrapers -->
<jumble-head custom-denylist='["badbot", "evilscraper", "harvester"]'></jumble-head>

<!-- โšก Full configuration: Combined settings -->
<jumble-head
allow-seo="true"
custom-allowlist='["partnerbot", "apiservice"]'
custom-denylist='["maliciousbot", "scraper123"]'>
</jumble-head>

๐Ÿ“‹ Attribute Details

allow-seo (boolean)

  • Default: true (SEO-safe mode)
  • When true: Legitimate search engines (Google, Bing, Facebook, etc.) see real content for indexing and social previews
  • When false: ALL bots see scrambled content (maximum protection but breaks SEO)
<!-- SEO-friendly (recommended for public websites) -->
<jumble-head allow-seo="true"></jumble-head>

<!-- Maximum security (recommended for private/internal content) -->
<jumble-head allow-seo="false"></jumble-head>

custom-allowlist (string array)

  • Default: [] (empty array)
  • Purpose: Add specific bot patterns that should be allowed to see real content
  • Format: JSON array of strings (case-insensitive partial matching)
  • Combined with: Default legitimate search engines (Google, Bing, Facebook, etc.)
<!-- Allow your monitoring service -->
<jumble-head custom-allowlist='["uptimerobot"]'></jumble-head>

<!-- Allow multiple partner services -->
<jumble-head custom-allowlist='["partnerapi", "trustedbot", "monitoring-service"]'></jumble-head>

custom-denylist (string array)

  • Default: [] (empty array)
  • Purpose: Add specific bot patterns that should be blocked and see scrambled content
  • Format: JSON array of strings (case-insensitive partial matching)
  • Combined with: Default malicious patterns (headless browsers, scrapers, AI training bots, etc.)
<!-- Block specific scraper -->
<jumble-head custom-denylist='["badbot"]'></jumble-head>

<!-- Block multiple malicious patterns -->
<jumble-head custom-denylist='["scraper", "harvester", "malicious-bot", "content-stealer"]'></jumble-head>

๐ŸŒŸ Real-World Configuration Examples

๐Ÿ›’ E-commerce Site: Allow price monitoring, block scrapers

<jumble-head
allow-seo="true"
custom-allowlist='["shopify-monitor", "price-tracker"]'
custom-denylist='["competitor-scraper", "price-spy"]'>
</jumble-head>

๐Ÿ“ฐ News Site: Allow social media, block AI training

<jumble-head
allow-seo="true"
custom-denylist='["content-scraper", "article-bot"]'>
</jumble-head>

๐Ÿ” Private Dashboard: Maximum protection

<jumble-head
allow-seo="false"
custom-allowlist='["internal-monitor"]'>
</jumble-head>

๐Ÿ“ Public Blog: Default SEO-safe protection

<jumble-head></jumble-head>

๐Ÿ“š Built-in Bot Detection

โœ… Default Legitimate Bots
(Always Allowed with allow-seo="true")

  • Search Engines: Google, Bing, Yahoo, DuckDuckGo, Yandex, Baidu
  • Social Media: Facebook, Twitter, LinkedIn, WhatsApp, Telegram, Discord
  • SEO Tools: SEMrush, Ahrefs, Majestic, Moz, Screaming Frog
  • Monitoring: UptimeRobot, Pingdom, GTmetrix

โŒ Default Malicious Patterns
(Always Blocked)

  • Automation Tools: Selenium, Puppeteer, Playwright, PhantomJS
  • Generic Scrapers: headless, scraper, crawler, harvester, extractor
  • AI Training Bots: GPTBot, ClaudeBot, CCBot, meta-externalagent
  • And 20+ more malicious patterns...

๐Ÿงช Interactive Attribute Testing

Want to test different attribute configurations? Try these interactive demos:

๐Ÿ”’ Maximum Protection Mode

Blocks ALL bots (including search engines)

โœ… SEO-Safe Mode

Allows search engines, blocks scrapers

๐ŸŽฏ Custom Lists Testing

Add your own bot patterns (Note: These are examples - actual bot detection requires real bot user agents)

๐Ÿ’ก These tests simulate attribute changes. In production, configure attributes directly in your HTML.

โš ๏ธ Important Notes:

  • Attributes must be set when the component loads - they cannot be changed dynamically after initialization
  • JSON arrays in attributes must use proper JSON syntax with double quotes
  • Partial matching is case-insensitive (e.g., "googlebot" matches "Googlebot/2.1")
  • Custom lists are combined with defaults - they don't replace them