vitepress-template

Appearance

Browser Extension (ui-crx) ​

**Referenced Files in This Document** - [[manifest.json]](file/ui-crx/manifest.json) - [[background.js]](file/ui-crx/background.js) - [[content.js]](file/ui-crx/content.js) - [[popup.js]](file/ui-crx/popup.js) - [[popup.html]](file/ui-crx/popup.html) - [[options.js]](file/ui-crx/options.js) - [[options.html]](file/ui-crx/options.html) - [[utils.js]](file/ui-crx/utils.js) - [[mock_data.js]](file/ui-crx/mock-data.js) - [[Dockerfile]](file/ui-crx/dockerfile) - [[nginx.conf]](file/ui-crx/nginx.conf)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Security Considerations
  9. Cross-Browser Compatibility
  10. Troubleshooting Guide
  11. Conclusion
  12. Appendices

Introduction ​

The Browser Extension (ui-crx) is a Chrome extension designed to integrate with the BI platform for data collection and browser automation. It enables users to log in, configure synchronization channels, collect metrics from supported platforms, and manage extension settings. The extension consists of a background service worker, content scripts, a popup UI, and an options page. It communicates with a backend API for authentication, configuration retrieval, and data synchronization.

Project Structure ​

The ui-crx extension follows a modular structure with clear separation of concerns:

  • Manifest defines permissions, background script, content scripts, and UI entry points.
  • Background script manages long-running tasks, context menus, and synchronization loops.
  • Content script injects into web pages to extract data and interact with platform UIs.
  • Popup UI provides user controls for login, dashboard, and cache inspection.
  • Options page allows saving user preferences.
  • Utilities encapsulate API calls, storage, and shared constants.
  • Mock data supports development and testing scenarios.
  • Docker and Nginx configuration support local static hosting for development.

Diagram sources

Section sources

Core Components ​

  • Manifest (manifest.json): Declares permissions, host permissions, background service worker, action popup, options page, icons, and content scripts.
  • Background (background.js): Implements context menu creation, message handling, authentication checks, sync manager, and badge management.
  • Content Script (content.js): Handles ad-hoc data collection and metric extraction from platform pages.
  • Popup UI (popup.html + popup.js): Provides login forms, dashboard, channel status display, manual sync, and cache inspection.
  • Options (options.html + options.js): Allows saving upload intervals and displays current settings.
  • Utilities (utils.js): Defines API endpoints, channel names, status mapping, storage helpers, API helpers, time formatting, and login expiry checks.
  • Mock Data (mock_data.js): Supplies mock responses for development and testing.

Section sources

Architecture Overview ​

The extension architecture centers around a service worker background script orchestrating data collection and synchronization. Content scripts operate on target pages to extract metrics. The popup UI provides user interaction and status monitoring. Utilities encapsulate cross-cutting concerns like storage and API access.

Diagram sources

Detailed Component Analysis ​

Manifest and Permissions ​

  • Manifest Version 3 declares:
    • Permissions: activeTab, downloads, storage, scripting, tabs, contextMenus, cookies.
    • Host Permissions: <all_urls>.
    • Background: service worker type module pointing to background.js.
    • Action: default_popup to popup.html, default_title, default_icon.
    • Options Page: options.html.
    • Icons: asset paths for 16, 48, 128.
    • Content Scripts: matches all URLs, runs at document_idle, injects content.js.

Section sources

Background Service Worker ​

Key responsibilities:

  • Context Menu: Creates a context menu item "添加到 bi-helper分析" and handles clicks to send ad-hoc collection requests to the active tab.
  • Messaging: Listens for messages from popup and content scripts for actions like sync start, ad-hoc data collection, cache retrieval, logout, and forced sync.
  • Authentication: Checks login expiry on startup and clears storage if expired.
  • Sync Manager:
    • Starts and runs a continuous loop to process configured channels.
    • Determines whether to collect metrics based on type (realtime/archive) and timing.
    • Uses concurrency control to limit simultaneous tab operations.
    • Manages a cache queue and uploads batches to the backend.
    • Updates badge text and color based on sync status.
  • Cookie-based Login Detection: Validates login presence for specific platforms by checking cookies.

Diagram sources

Section sources

Content Script Injection ​

Responsibilities:

  • Listens for messages from background:
    • collect_adhoc_data: Extracts page content, selection, and images, then sends back to background.
    • collect_metric_data: Selects indicators and time scopes, stabilizes page, and extracts list data.
  • Toast notifications are rendered on the page for user feedback.

Diagram sources

Section sources

Components:

  • Login Tabs: WeChat, Phone, Account login modes.
  • Dashboard: Displays user info, channel list with status badges, stats, and manual sync links.
  • Cache View: Shows cached data per channel.
  • Message Container: Displays success/error messages.

User Interaction Handling:

  • Tab switching for login modes.
  • Login handlers for account and phone modes with OTP sending simulation.
  • Logout handler that contacts background to clear storage and resets UI.
  • Manual sync initiation per channel.
  • Cache inspection via background message.

Diagram sources

Section sources

Options Page Functionality ​

  • Saves upload intervals to local storage.
  • Loads previously saved settings on DOMContentLoaded.
  • Displays a success message upon save.

Section sources

Extension Settings Management ​

  • Storage Keys: auth, config, sync_status, cache_queue.
  • API Endpoints: login, config, sync, adhoc, error logging, version.
  • Channel Names and Status Mapping: Centralized for UI display and badge coloring.
  • Time Formatting: Utility for displaying timestamps.
  • Login Expiry Check: Clears storage after 30 days of inactivity.

Section sources

Data Collection Mechanisms ​

  • Ad-hoc Collection:
    • Background receives context menu click and sends collect_adhoc_data to active tab.
    • Content script extracts page metadata and selection, then reports back to background.
  • Metric Collection:
    • Background starts sync loop, creates tabs for each metric URL, waits for completion, and injects collect_metric_data message.
    • Content script performs indicator/time scope selection, stabilizes page, and extracts list data.
    • Data is queued and uploaded in batches.

Diagram sources

Section sources

Cross-Origin Communication ​

  • Background uses chrome.runtime.sendMessage/chrome.runtime.onMessage for inter-component messaging.
  • Content scripts communicate with background via runtime messaging.
  • Tabs API is used to create isolated tabs for metric collection.
  • Cookies API is used to detect login status on specific domains.

Section sources

Secure Storage Implementation ​

  • Chrome Storage Local API is used for persisting auth tokens, config, sync status, and cache queue.
  • Storage helper wraps get/set/remove/clear with Promises for easy use.
  • Login expiry is enforced by checking login_timestamp and clearing storage if expired.

Section sources

Messaging System Between Extension Components ​

  • Background listens for actions: sync_start, adhoc_data_collected, get_cache_queue, logout, force_sync.
  • Popup initiates actions and listens for status_update messages to refresh UI.
  • Content script responds to collect_metric_data and collect_adhoc_data.

Section sources

Event Listeners and Browser APIs ​

  • Context Menus: Creation and click handling.
  • Runtime: Installed, Startup, Message listeners.
  • Tabs: Creating tabs, listening to onUpdated events, removing tabs.
  • Cookies: Checking session cookies for login detection.
  • Action: Badge text and color updates.

Section sources

Extension Lifecycle Management ​

  • Installed: Initializes context menus.
  • Startup: Checks login expiry and clears storage if needed.
  • Running: Continuously monitors and updates sync status, badge, and UI.

Section sources

  • Login Tabs: WeChat (mock polling), Phone (OTP send), Account (credentials).
  • Dashboard: Channel list with status, stats, manual sync links.
  • Cache View: Displays cache content per channel.
  • Messages: Success/error notifications with auto-hide.

Section sources

Examples of Data Extraction Workflows ​

  • Ad-hoc Data Extraction:
    • Context menu click triggers background to send collect_adhoc_data to content script.
    • Content script gathers selection, images, and page metadata.
    • Background uploads adhoc data to backend.
  • Metric Data Extraction:
    • Background creates a hidden tab for each metric URL.
    • Content script selects indicator/time scope and extracts list data.
    • Background queues and uploads batches to backend.

Section sources

Extension Customization Options ​

  • Upload Intervals: Saved via options page and persisted in local storage.
  • Server Address: Currently fixed in utils.js; options page indicates immutability.

Section sources

Dependency Analysis ​

The extension relies on Chrome extension APIs and a backend API. Internal dependencies:

  • background.js depends on utils.js for storage, API, constants, and helpers.
  • content.js depends on runtime messaging and DOM manipulation.
  • popup.js depends on utils.js and runtime messaging.
  • options.js depends on storage API.
  • All modules depend on mock_data.js for development/testing.

Diagram sources

Section sources

Performance Considerations ​

  • Concurrency Control: Limits simultaneous tab operations to prevent resource contention.
  • Anti-Crawling Delays: Random delays during metric collection reduce detection risk.
  • Batch Uploads: Queues data and uploads in configurable sizes and intervals.
  • Badge Updates: Efficiently updates badge text and color based on aggregated status.
  • Tab Cleanup: Ensures tabs are removed after data extraction to free resources.

Section sources

Security Considerations ​

  • Permissions: Requires activeTab, downloads, storage, scripting, tabs, contextMenus, cookies. Ensure minimal necessary permissions are granted.
  • Authentication: Stores tokens in Chrome storage; enforces 30-day expiry and clears storage automatically.
  • Cookies: Uses cookies API to detect login status for specific platforms; sensitive cookie handling should be reviewed.
  • Cross-Origin: Uses host_permissions for <all_urls>; restrict to necessary domains if possible.
  • API Calls: Uses Authorization headers with bearer tokens; ensure HTTPS endpoints.

Section sources

Cross-Browser Compatibility ​

  • Manifest Version 3: Uses ES module service worker and modern Chrome APIs.
  • Content Scripts: Run at document_idle; ensure compatibility with target platform pages.
  • Storage: Uses Chrome Storage Local API; not compatible with Firefox WebExtensions storage without adaptation.
  • Tabs/Cookies APIs: Chrome-specific; would require polyfills or alternative implementations for Firefox/Edge.

Section sources

Troubleshooting Guide ​

Common Issues and Resolutions:

  • Login Failure:
    • Verify credentials and network connectivity.
    • Check mock_data.js for expected login responses during development.
  • No Metrics Collected:
    • Ensure platform login cookies are present for the specific domain.
    • Verify metric URLs and selector logic in content script.
  • Upload Failures:
    • Check backend connectivity and token validity.
    • Review cache queue and upload intervals.
  • Badge Not Updating:
    • Confirm status updates are being sent and badge manager is invoked.
  • Popup UI Not Responding:
    • Ensure popup.html is served and popup.js is loaded as a module.

Section sources

Conclusion ​

The ui-crx extension provides a robust framework for browser-based data collection and synchronization within the BI platform. Its modular architecture, clear separation of concerns, and use of Chrome extension APIs enable efficient data extraction, user-friendly controls, and reliable background processing. By adhering to security best practices and considering cross-browser compatibility, the extension can be maintained and extended effectively.

Appendices ​

API Definitions ​

  • POST /api/v1/auth/login: Login endpoint returning tokens and user info.
  • GET /api/v1/auth/config: Configuration including permissions, metrics, and upload settings.
  • POST /api/v1/data/crx/sync: Batch upload of collected metrics.
  • POST /api/v1/data/crx/adhoc: Ad-hoc data upload.
  • POST /api/v1/log/error: Error logging endpoint.
  • GET /api/v1/data/crx/ver: Version check endpoint.

Section sources

Build and Deployment ​

  • Dockerfile: Builds an nginx container serving static files.
  • Nginx Configuration: Serves popup.html as index and routes all paths to popup.html.

Section sources