Stealth Browse Plugin API v2

Welcome to the Stealth Browse Plugin API documentation. This guide will help you create powerful plugins to extend the browser's functionality.

Getting Started

Stealth Browse plugins are distributed as .sbplugin files, which are ZIP archives containing your plugin code and manifest.

Plugin Structure

myplugin.sbplugin
├── manifest.json          // Required: Plugin metadata
├── js/
│   └── content.js         // Content scripts
├── css/
│   └── styles.css         // Stylesheets
├── icons/
│   ├── icon-48.png
│   └── icon-128.png
└── background.js          // Optional: Background script

Manifest File

The manifest.json file describes your plugin and its requirements.

{
  "id": "com.yourname.pluginname",
  "name": "My Awesome Plugin",
  "version": "1.0.0",
  "description": "A description of what your plugin does",
  "author": "Your Name",
  "author_url": "https://yourwebsite.com",
  "homepage": "https://plugin-homepage.com",
  "api_version": 2,
  "permissions": ["storage", "tabs", "history"],
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "exclude_matches": ["*://example.com/*"],
      "js": ["js/content.js"],
      "css": ["css/styles.css"],
      "run_at": "document_idle",
      "all_frames": false
    }
  ],
  "icons": {
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  }
}

run_at Options

Value Description
document_start Inject before page loads (for blocking scripts)
document_end Inject when DOM is ready
document_idle Inject after page fully loads (default)

Permissions

Plugins must declare required permissions in the manifest.

Permission Description
storage Store and retrieve plugin data
tabs Access tab information, create/close tabs
active_tab Access current tab only (limited)
history Read and modify browsing history
bookmarks Read and create bookmarks
downloads Access download history, start downloads
clipboard_read Read from clipboard
clipboard_write Write to clipboard
notifications Show notifications
web_request Monitor network requests
context_menus Add context menu items
cookies Read and write browser cookies
settings Modify browser settings (security, privacy, search)
translation Translate pages
navigation Control page navigation (back, forward, scroll)
media Extract media from pages

JavaScript API Reference

All API methods are available through the StealthBrowse global object.

Storage API

Requires: storage permission

// Store a value
StealthBrowse.storage.set('myKey', { foo: 'bar' });

// Get a value
const value = StealthBrowse.storage.get('myKey');

// Remove a value
StealthBrowse.storage.remove('myKey');

// Get all stored data
const all = StealthBrowse.storage.getAll();

// Clear all storage
StealthBrowse.storage.clear();

Tabs API

Requires: tabs or active_tab permission

// Get current tab info
const tab = StealthBrowse.tabs.getCurrent();
console.log(tab.url, tab.title);

// Get all tabs
const tabs = StealthBrowse.tabs.getAll();

// Create a new tab
StealthBrowse.tabs.create('https://example.com', true);

// Close a tab
StealthBrowse.tabs.close(tabId);

// Update tab URL
StealthBrowse.tabs.update(tabId, 'https://new-url.com');

// Reload a tab
StealthBrowse.tabs.reload(tabId);

History API

Requires: history permission

// Search history
const results = StealthBrowse.history.search('search term', 50);

// Get recent history
const recent = StealthBrowse.history.getRecent(100);

// Delete URL from history
StealthBrowse.history.deleteUrl('https://example.com');

Bookmarks API

Requires: bookmarks permission

// Get all bookmarks
const bookmarks = StealthBrowse.bookmarks.getAll();

// Create a bookmark
const bookmark = StealthBrowse.bookmarks.create('Title', 'https://url.com');

// Search bookmarks
const found = StealthBrowse.bookmarks.search('query');

// Remove a bookmark
StealthBrowse.bookmarks.remove(bookmarkId);

Downloads API

Requires: downloads permission

// Get all downloads
const downloads = StealthBrowse.downloads.getAll();

// Start a download
StealthBrowse.downloads.start('https://file-url.com/file.zip', 'custom-name.zip');

Clipboard API

Requires: clipboard_read and/or clipboard_write permission

// Read clipboard
const text = StealthBrowse.clipboard.read();

// Write to clipboard
StealthBrowse.clipboard.write('Text to copy');

Page Interaction API

// Get current page URL
const url = StealthBrowse.page.getUrl();

// Get page title
const title = StealthBrowse.page.getTitle();

// Inject JavaScript
StealthBrowse.page.injectScript(`
    console.log('Injected script running!');
`);

// Inject CSS
StealthBrowse.page.injectCSS(`
    body { background: #000 !important; }
`);

Notifications API

Requires: notifications permission

// Show a notification
StealthBrowse.notifications.create(
    'Notification Title',
    'Notification message body',
    'https://icon-url.com/icon.png' // optional
);

Utility API

// Show a toast message
StealthBrowse.utils.showToast('Hello from plugin!');

// Log a message (appears in Android logs)
StealthBrowse.utils.log('Debug message');

Browser Info API

// Get browser information
const info = StealthBrowse.browser.getInfo();
// Returns: { name, version, apiVersion, platform }

// Get/set user agent
const ua = StealthBrowse.browser.getUserAgent();
StealthBrowse.browser.setUserAgent('Custom UA');

// Get plugin information
const pluginInfo = StealthBrowse.plugin.getInfo();
// Returns: { id, name, version, permissions }

// Check if plugin has a permission
if (StealthBrowse.plugin.hasPermission('tabs')) {
    // Use tabs API
}

Navigation API

// Go back/forward in history
StealthBrowse.navigation.goBack();
StealthBrowse.navigation.goForward();

// Check if navigation is possible
if (StealthBrowse.navigation.canGoBack()) { ... }
if (StealthBrowse.navigation.canGoForward()) { ... }

// Stop loading / Reload
StealthBrowse.navigation.stop();
StealthBrowse.navigation.reload();

// Print the page
StealthBrowse.navigation.print();

// Scroll control
StealthBrowse.navigation.scrollTo(0, 500);
StealthBrowse.navigation.scrollToTop();
StealthBrowse.navigation.scrollToBottom();

Settings API

Requires: settings permission

// Get all settings
const settings = StealthBrowse.settings.getAll();

// Get individual setting
const adBlock = StealthBrowse.settings.get('adBlockEnabled');
const darkMode = StealthBrowse.settings.get('darkMode'); // 'on', 'off', 'system'
const textZoom = StealthBrowse.settings.get('textZoom'); // 50-200

// Set settings
StealthBrowse.settings.set('adBlockEnabled', true);
StealthBrowse.settings.set('darkMode', 'on');
StealthBrowse.settings.set('textZoom', 120);

// Available settings keys:
// adBlockEnabled, httpsOnlyEnabled, fingerprintProtectionEnabled,
// scriptBlockingEnabled, doNotTrackEnabled, blockThirdPartyCookiesEnabled,
// autoDismissCookiesEnabled, autoSkipVideoAdsEnabled, smartFormFillEnabled,
// darkMode, desktopModeEnabled, textZoom, stealthSearchEnabled,
// googleCleanEnabled, searchEngine, dnsOverHttpsEnabled, dataSaverEnabled

Translation API

Requires: translation permission

// Translate current page
StealthBrowse.translation.translate('es'); // Translate to Spanish

// Show original page
StealthBrowse.translation.showOriginal();

// Check if page is translated
if (StealthBrowse.translation.isTranslated()) { ... }

// Get supported languages
const languages = StealthBrowse.translation.getSupportedLanguages();
// Returns: [{ code: 'en', name: 'English' }, ...]

Find in Page API

// Show find in page UI
StealthBrowse.find.show();

// Find text
StealthBrowse.find.next('search text');
StealthBrowse.find.previous('search text');

// Clear search highlights
StealthBrowse.find.clear();

// Hide find UI
StealthBrowse.find.hide();

Reading Mode API

Requires: active_tab permission

// Enable reading mode
StealthBrowse.readingMode.enable();

// Check if reading mode is active
if (StealthBrowse.readingMode.isActive()) { ... }

Cookies API

Requires: cookies permission

// Get cookies for URL
const cookies = StealthBrowse.cookies.get('https://example.com');

// Set a cookie
StealthBrowse.cookies.set('https://example.com', 'name=value; path=/');

// Remove a cookie
StealthBrowse.cookies.remove('https://example.com', 'cookieName');

// Clear all cookies
StealthBrowse.cookies.clearAll();

Context Menu API

Requires: context_menus permission

// Register a context menu item
StealthBrowse.contextMenu.register('myAction', 'Do Something', 'all');
// context: 'all', 'link', 'image', 'text'

// Unregister a context menu item
StealthBrowse.contextMenu.unregister('myAction');

Media Extraction API

Requires: active_tab or media permission

// Extract media from current page
const media = StealthBrowse.media.extractFromPage();
// Returns: { images: [...], videos: [...] }

Share API

// Share text
StealthBrowse.share.text('Check out this text!');

// Share current page
StealthBrowse.share.currentPage();

External URL API

// Open URL in external app
StealthBrowse.external.openUrl('https://example.com');

Events

// Listen for API ready event
window.addEventListener('stealthbrowse:ready', (event) => {
    console.log('API ready!', event.detail.version);
    
    // Your plugin initialization code here
});

// Inter-plugin communication
// Emit an event
StealthBrowse.events.emit('myEvent', { data: 'value' });

// Listen for events from other plugins
StealthBrowse.events.on('myEvent', (data) => {
    console.log('Received:', data);
});
Protected Features

Plugins cannot access or modify the following features:

  • VPN functionality
  • License and subscription management
  • Core security settings
  • Premium feature restrictions

Example Plugin

manifest.json

{
  "id": "com.example.darkmode",
  "name": "Quick Dark Mode",
  "version": "1.0.0",
  "description": "Applies dark mode to all websites",
  "author": "Example Developer",
  "api_version": 2,
  "permissions": ["storage"],
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["js/darkmode.js"],
      "css": ["css/darkmode.css"],
      "run_at": "document_start"
    }
  ]
}

js/darkmode.js

(function() {
    'use strict';
    
    // Wait for API to be ready
    function init() {
        const enabled = StealthBrowse.storage.get('darkModeEnabled');
        
        if (enabled !== 'false') {
            document.documentElement.classList.add('stealth-dark-mode');
        }
    }
    
    if (typeof StealthBrowse !== 'undefined') {
        init();
    } else {
        window.addEventListener('stealthbrowse:ready', init);
    }
})();

css/darkmode.css

.stealth-dark-mode {
    filter: invert(1) hue-rotate(180deg);
}

.stealth-dark-mode img,
.stealth-dark-mode video,
.stealth-dark-mode iframe {
    filter: invert(1) hue-rotate(180deg);
}

Creating Plugin UI

Plugins can create rich user interfaces that are displayed in the browser. There are several ways to add UI elements:

1. Floating Overlay UI (Injected into Page)

Create draggable, floating panels on any webpage:

// Create a floating UI panel
(function() {
    'use strict';
    
    // Prevent multiple instances
    if (window.__myPluginActive) return;
    window.__myPluginActive = true;
    
    // Color palette (Dracula theme for consistency)
    const COLORS = {
        bg: 'rgba(18, 18, 24, 0.95)',
        text: '#f8f8f2',
        accent: '#bd93f9',
        border: 'rgba(255, 255, 255, 0.15)'
    };
    
    // Inject styles
    const styles = document.createElement('style');
    styles.textContent = `
        .myplugin-container {
            position: fixed;
            top: 20px;
            right: 20px;
            z-index: 2147483647;
            width: 320px;
            background: ${COLORS.bg};
            border-radius: 16px;
            box-shadow: 0 25px 50px rgba(0,0,0,0.5);
            font-family: -apple-system, sans-serif;
            user-select: none;
        }
        .myplugin-header {
            display: flex;
            align-items: center;
            padding: 12px 16px;
            background: rgba(40, 42, 54, 0.95);
            border-radius: 16px 16px 0 0;
            cursor: move;
        }
        .myplugin-title {
            color: ${COLORS.text};
            font-weight: bold;
            flex: 1;
        }
        .myplugin-close {
            width: 24px;
            height: 24px;
            border: none;
            background: rgba(255, 95, 86, 0.9);
            border-radius: 50%;
            cursor: pointer;
        }
        .myplugin-content {
            padding: 16px;
            color: ${COLORS.text};
        }
        .myplugin-btn {
            width: 100%;
            padding: 12px;
            margin: 8px 0;
            border: none;
            border-radius: 8px;
            background: ${COLORS.accent};
            color: #fff;
            font-weight: bold;
            cursor: pointer;
        }
    `;
    document.head.appendChild(styles);
    
    // Create UI
    const container = document.createElement('div');
    container.className = 'myplugin-container';
    container.innerHTML = `
        <div class="myplugin-header">
            <span class="myplugin-title">My Plugin</span>
            <button class="myplugin-close">×</button>
        </div>
        <div class="myplugin-content">
            <p>Your plugin content here</p>
            <button class="myplugin-btn">Do Something</button>
        </div>
    `;
    document.body.appendChild(container);
    
    // Make draggable
    let isDragging = false, offsetX, offsetY;
    const header = container.querySelector('.myplugin-header');
    
    header.addEventListener('mousedown', (e) => {
        isDragging = true;
        offsetX = e.clientX - container.offsetLeft;
        offsetY = e.clientY - container.offsetTop;
    });
    
    document.addEventListener('mousemove', (e) => {
        if (isDragging) {
            container.style.left = (e.clientX - offsetX) + 'px';
            container.style.top = (e.clientY - offsetY) + 'px';
            container.style.right = 'auto';
        }
    });
    
    document.addEventListener('mouseup', () => isDragging = false);
    
    // Close button
    container.querySelector('.myplugin-close').onclick = () => {
        container.remove();
        styles.remove();
        window.__myPluginActive = false;
    };
    
    // Button action
    container.querySelector('.myplugin-btn').onclick = () => {
        StealthBrowse.utils.showToast('Button clicked!');
    };
})();

2. Plugin Options Page

Add an options_page to your manifest for a dedicated settings page:

{
  "id": "com.example.myplugin",
  "name": "My Plugin",
  "options_page": "options.html",
  ...
}

Then create options.html in your plugin:

<!DOCTYPE html>
<html>
<head>
    <style>
        body {
            background: #0D0A15;
            color: #E8E6F0;
            font-family: -apple-system, sans-serif;
            padding: 20px;
        }
        .setting {
            margin: 15px 0;
            display: flex;
            justify-content: space-between;
            align-items: center;
        }
        input[type="checkbox"] {
            width: 20px;
            height: 20px;
            accent-color: #7C4DFF;
        }
        .btn {
            background: #7C4DFF;
            color: white;
            border: none;
            padding: 12px 24px;
            border-radius: 8px;
            cursor: pointer;
        }
    </style>
</head>
<body>
    <h1>My Plugin Settings</h1>
    <div class="setting">
        <label>Enable Feature</label>
        <input type="checkbox" id="enableFeature">
    </div>
    <button class="btn" onclick="save()">Save Settings</button>
    
    <script>
        // Load saved settings
        document.getElementById('enableFeature').checked = 
            StealthBrowse.storage.get('enableFeature') === 'true';
        
        function save() {
            StealthBrowse.storage.set('enableFeature', 
                document.getElementById('enableFeature').checked);
            StealthBrowse.utils.showToast('Settings saved!');
        }
    </script>
</body>
</html>

3. Plugin Popup (Toolbar Action)

Add a popup that appears when clicking your plugin icon in the toolbar:

{
  "id": "com.example.myplugin",
  "name": "My Plugin",
  "browser_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "48": "icons/icon-48.png"
    },
    "default_title": "Click to open"
  },
  ...
}

Adding Plugin to Toolbar Menu

Plugins can register themselves in the browser's toolbar menu (3-dot menu) using the toolbar_action manifest property:

{
  "id": "com.example.myplugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "permissions": ["storage"],
  "toolbar_action": {
    "id": "myPluginAction",
    "title": "My Plugin",
    "icon": "icons/icon-48.png",
    "show_in_menu": true,
    "action": "toggle"
  },
  "content_scripts": [...]
}

Toolbar Action Properties

Property Description
id Unique identifier for the action
title Text shown in the menu
icon Path to icon (48x48 recommended)
show_in_menu Whether to show in 3-dot menu
action Action type: toggle, popup, or script

Responding to Toolbar Clicks

// Listen for toolbar action clicks
StealthBrowse.events.on('toolbar:myPluginAction', () => {
    // Toggle your plugin UI
    if (window.__myPluginActive) {
        closePlugin();
    } else {
        openPlugin();
    }
});

Plugin Statistics API

For plugins that track statistics (like ad blockers), you can expose and retrieve stats:

// Get ad block statistics
const stats = JSON.parse(StealthPluginAPI.getAdBlockStats());
console.log('Blocked domains:', stats.blockedDomainCount);
console.log('Session blocked:', stats.sessionBlockedCount);
console.log('Total blocked:', stats.totalBlockedCount);
console.log('Last sync:', stats.lastSyncTime);

// Expose your own plugin stats
window.__myPluginStats = {
    getStats: () => ({
        itemsProcessed: myPlugin.processed,
        errorsCount: myPlugin.errors
    })
};

Ad Block Statistics

Access the ad blocker statistics directly:

// These methods are available via StealthPluginAPI
StealthPluginAPI.getBlockedDomainCount();     // Total blocked domains
StealthPluginAPI.getBuiltInDomainCount();     // From filter lists
StealthPluginAPI.getRemoteDomainCount();
StealthPluginAPI.getSessionBlockedCount();    // Blocked this session
StealthPluginAPI.getTotalBlockedCount();      // All-time blocked count
StealthPluginAPI.recordBlockedRequest();      // Increment blocked counter

Packaging Your Plugin

  1. Create your plugin files with the structure shown above
  2. Compress all files into a ZIP archive
  3. Rename the extension from .zip to .sbplugin
  4. Install via Settings → Plugins → Install from file

Example Plugin Structure

my-plugin/
├── manifest.json
├── popup.html          // Optional: Toolbar popup
├── options.html        // Optional: Settings page
├── background.js       // Optional: Background script
├── js/
│   └── content.js      // Main content script
├── css/
│   └── styles.css      // Injected styles
└── icons/
    ├── icon-16.png
    ├── icon-48.png
    └── icon-128.png

Best Practices

  • Request only the permissions your plugin actually needs
  • Use document_idle for most content scripts (best performance)
  • Use document_start only for blocking/modifying scripts
  • Handle the case where the API might not be immediately available
  • Use descriptive plugin IDs (reverse domain format recommended)
  • Provide clear descriptions of what your plugin does
  • Test your plugin thoroughly before distribution
  • Use the Dracula theme colors for UI consistency
  • Use z-index: 2147483647 for floating overlays
  • Always provide a close button for any overlay UI
  • Support both touch and mouse events for mobile compatibility

UI Design Guidelines

Follow these guidelines for consistent plugin UI:

Color Palette

Color Hex Usage
Background #05030D Main backgrounds
Surface #0D0A15 Cards, panels
Surface Elevated #1A1625 Headers, elevated elements
Primary Accent #7C4DFF Buttons, links, highlights
Text Primary #E8E6F0 Main text
Text Secondary #B0AFC4 Secondary text
Success #34C759 Success states
Error #FF3B30 Error states

Typography

  • Use system fonts: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
  • Titles: 16-20sp, bold
  • Body: 14sp, normal
  • Captions: 12sp, normal

Spacing

  • Panel padding: 16px
  • Element spacing: 8-12px
  • Border radius: 8-16px

Stealth Browse Plugin API v2 • © FATAL Cybersecurity