This guide covers using the DQM React Component as a standalone widget via the pre-built IIFE or ESM bundles. This allows you to use DQM without a build pipeline or React setup. ## Table of Contents - [Overview](#overview) - [Bundle Types](#bundle-types) - [IIFE Bundle (Browser Global)](#iife-bundle-browser-global) - [ESM Bundle (ES Modules)](#esm-bundle-es-modules) - [Widget Loading Flow](#widget-loading-flow) - [Integration Examples](#integration-examples) - [CMS Integrations](#cms-integrations) - [Configuration](#configuration) - [Troubleshooting](#troubleshooting) ## Overview The widget bundle provides a standalone version of the DQM sidebar that can be embedded in any web page without React dependencies. The widget: - **Runs in Shadow DOM** - Isolated from page styles and scripts - **Zero Dependencies** - All dependencies bundled (React, MUI, etc.) - **Self-Contained** - No build pipeline or npm required - **CMS-Friendly** - Easy integration with WordPress, Shopify, Drupal, etc. ## Bundle Types | Format | File | Use Case | Browser Support | |--------|------|----------|----------------| | **IIFE** | `dqm-widget.iife.js` | Traditional ` ``` ### API The IIFE bundle exposes a global `DQMWidget` object with: ```typescript window.DQMWidget = { /** * Load and initialize the DQM widget * @param options - Widget configuration * @returns Cleanup function to remove widget */ loadDQMWidget(options: { config: DQMConfig; containerId?: string; open?: boolean; }): () => void; /** * Get current widget version */ version: string; } ``` ### Full Example with AI Features ```html DQM Widget with AI Translation

Willkommen zu meiner Website

Diese Seite wird mit Crownpeak DQM überwacht.

``` ## ESM Bundle (ES Modules) ### Basic Usage ```html DQM Widget - ESM Example

My Website

Content to be analyzed by DQM

``` ### With Import Maps ```html DQM Widget - ESM with Import Maps

My Website

``` ## Widget Loading Flow ```mermaid flowchart TD A[Page Load] --> B{Widget Script Loaded?} B -->|Yes| C[Call loadDQMWidget] B -->|No| D[Wait for DOMContentLoaded] D --> C C --> E[Create Shadow DOM Container] E --> F[Mount React App in Shadow DOM] F --> G[Initialize DQM Sidebar Component] G --> H{Auto-open?} H -->|Yes| I[Open Sidebar] H -->|No| J[Show FAB Button] I --> K[Extract HTML from current page] K --> L[Send to DQM API] L --> M[Poll for Analysis Result] M --> N{Analysis Complete?} N -->|Yes| O[Display Results] N -->|No| M O --> P{AI Translation Enabled?} P -->|Yes| Q[Translate Checkpoints] P -->|No| R[Display Raw Results] Q --> S{AI Summary Enabled?} S -->|Yes| T[Generate Summary] S -->|No| R T --> R J --> U[User Clicks FAB] U --> K ``` ## Integration Examples ### WordPress (PHP Template) ```php

``` ### Shopify (Liquid Template) ```liquid {{ page_title }} {{ content_for_header }} {{ content_for_layout }} ``` ### Drupal (Twig Template) ```twig {# page.html.twig #}

{# DQM Widget #} ``` ### Webflow (Custom Code) ```html ``` ### Google Tag Manager ```javascript // Create new Custom HTML tag // Trigger: All Pages (or specific pages) ``` ## CMS Integrations ### WordPress Plugin Structure ``` dqm-widget-wordpress/ ├── dqm-widget.php # Main plugin file ├── admin/ │ └── settings.php # Admin settings page └── public/ └── widget-loader.php # Frontend widget loader ``` **dqm-widget.php:** ```php ``` ## Configuration ### Full Configuration Object ```typescript interface DQMConfig { // Authentication (required) websiteId: string; apiKey: string; // Overlay Detection (optional) overlayConfig?: { selector?: string; validateIframe?: boolean; pollMs?: number; manualOffset?: { position: 'top' | 'bottom' | 'left' | 'right'; pixels: number; }; }; // AI Translation (optional) // Note: OpenAI API key is configured via localStorage (dqm_openai_apiKey) translation?: { enabledByDefault?: boolean; // Enable translation by default computeBudgetMs?: number; // Timeout in ms (default: 15000 for fast mode) }; // AI Summary (optional) // Note: OpenAI API key is configured via localStorage (dqm_openai_apiKey) summary?: { timeoutMs?: number; // Timeout in ms (default: 30000) }; } ``` ### Environment-Specific Configuration ```javascript // Configure OpenAI API key via localStorage localStorage.setItem('dqm_openai_apiKey', 'sk-...'); localStorage.setItem('dqm_openai_model', 'gpt-4o-mini'); localStorage.setItem('dqm_target_language', 'de'); // Development window.DQMWidget.loadDQMWidget({ config: { websiteId: 'dev-website-id', apiKey: 'dev-api-key', translation: { enabledByDefault: true, computeBudgetMs: 30000, // 30s for full mode } } }); // Production window.DQMWidget.loadDQMWidget({ config: { websiteId: 'prod-website-id', apiKey: 'prod-api-key', translation: { enabledByDefault: true, computeBudgetMs: 15000, // 15s for fast mode }, summary: { timeoutMs: 30000, } } }); ``` ## Troubleshooting ### Widget Not Loading **Symptom:** Nothing appears on the page after script inclusion. **Solutions:** 1. Check browser console for errors 2. Verify script URL is correct and accessible 3. Ensure script is loaded after `` tag 4. Check if Content Security Policy (CSP) blocks script ```html ``` ### Shadow DOM Conflicts **Symptom:** Widget styles broken or invisible. **Solutions:** 1. Ensure no global CSS resets affect Shadow DOM 2. Check if page uses `::slotted()` selectors that interfere 3. Verify no JavaScript tries to access widget internals ```javascript // DON'T: Access Shadow DOM internals const widgetHost = document.querySelector('#dqm-widget-host'); const shadowRoot = widgetHost.shadowRoot; // May be null or closed // DO: Use widget API only window.DQMWidget.loadDQMWidget({ /* config */ }); ``` ### CORS Errors **Symptom:** `Access-Control-Allow-Origin` errors in console. **Solutions:** 1. Use CDN URL (unpkg.com) instead of local file 2. Host bundle on same domain as page 3. Configure server CORS headers if self-hosting ```nginx # nginx configuration for self-hosting location /dqm-widget.iife.js { add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Methods "GET, OPTIONS"; } ``` ### Performance Issues **Symptom:** Widget loads slowly or blocks page rendering. **Solutions:** 1. Load script with `defer` or `async` attribute 2. Use ESM bundle for better tree-shaking 3. Consider lazy-loading widget on user interaction ```html ``` ### AI Features Not Working **Symptom:** Translation or summary not appearing. **Solutions:** 1. Check OpenAI API key is valid 2. Check browser console for AI-related errors 3. Ensure localStorage keys are set correctly ```javascript // Debug AI configuration console.log('Translation Enabled:', localStorage.getItem('dqm_translate_results_enabled')); console.log('OpenAI API Key Set:', !!localStorage.getItem('dqm_openai_apiKey')); console.log('Target Language:', localStorage.getItem('dqm_target_language')); console.log('Summary Enabled:', localStorage.getItem('dqm_ai_summary_enabled')); ``` ## See Also - **[Examples](./EXAMPLES.md)** - React component examples - **[AI Features Guide](./AI-FEATURES.md)** - AI translation and summary documentation - **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions - **[API Reference](./API-REFERENCE.md)** - Full TypeScript API documentation