@mobiloud/ml-review-popup

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a review prompt popup widget designed specifically for MobiLoud mobile apps. The widget creates a modern, iOS-style popup that prompts users to leave a review for the app in the App Store and the Play Store. The popup gives the user two options: 1. Yes, I love the app and I want to leave a review 2. No, there is something wrong with the app or I simply don't like it and I don't want to leave a review The labels are customizable through configuration options. When option #1 is clicked, it triggers `nativeFunctions.triggerReviewFlow()`, which natively triggers the corresponding review workflow based on the device system (iOS or Android). ## Architecture The project consists of three main files: - **script.js**: Core widget implementation as a JavaScript class (ReviewPromptPopup) - **widget.html**: Demo page with multiple configuration examples - **style.css**: Demo page styling (widget styles are embedded in script.js) ## Configuration Options The widget accepts these configuration options: ### Basic Options - `heading`: Popup title text (default: "Rate Our App") - `text`: Description text (default: "Love using our app? Your feedback helps us improve and reach more people like you!") - `acceptText`: Accept button label (default: "Rate Now") - `declineText`: Decline button label (default: "Maybe Later") - `successMessage`: Success message text (default: "✅ Thank you for your feedback!") ### Display Control - `autoTrigger`: Auto-show on page load (default: false) - `delay`: Delay before auto-trigger in milliseconds (default: 0) - `triggerElement`: CSS selector for manual trigger element - `allowedUrls`: Array of URL patterns where popup can show ### Session Management - `maxSessions`: Maximum number of times to show popup (works with timeframeDays) - `timeframeDays`: Time period in days for session limit (works with maxSessions) - `initialDelay`: Initial delay in days before first popup becomes eligible ### Behavior & Styling - `darkMode`: Enable dark mode styling (default: false) - `debugMode`: Bypass app status checks for testing (default: false) - `enableAnalytics`: Enable Google Analytics tracking (default: false) - `colors`: Object containing color customization options (see Color Customization section) ### Callbacks - `onAccept`: Callback function when user accepts review prompt - `onDecline`: Callback function when user declines review prompt - `onClose`: Callback function when popup is closed ## Review-Specific Behavior ### "Never Show Again" Logic - When user clicks accept (Rate Now), the popup sets a permanent cookie flag - Once accepted, the popup will never show again for that user - This prevents users from being asked multiple times after they've already reviewed ### Decline Behavior - When user declines, normal session limit logic applies - Popup can show again based on `maxSessions` and `timeframeDays` settings - Perfect for periodic review prompts (e.g., every 7 days for 30 days maximum) ### Cookie Tracking - Uses cookie name: `ml_review_popup_tracking` - Stores: session count, timestamps, never-show-again flag - Automatic cleanup and timeframe management ## Testing The widget includes comprehensive debug capabilities: - Set `debugMode: true` to bypass all app status checks - Demo page (widget.html) provides multiple test scenarios - Debug mode simulates review flow without requiring native functions ## MobiLoud Integration The widget is specifically designed for MobiLoud mobile apps and relies on: - MobiLoud user agent detection (`canvas` in user agent) - Native bridge function `nativeFunctions.triggerReviewFlow()` - No real-time status monitoring needed (unlike push notifications) For production use, the widget should be deployed within a MobiLoud app context where the native review function is available. ## Color Customization The widget supports comprehensive color customization through the `colors` configuration option. You can customize all visual elements to match your app's branding. ### Available Color Options ```javascript const reviewPopup = createReviewPopup({ colors: { // Button colors acceptButton: '#007AFF', // Accept button background acceptButtonHover: '#0056CC', // Accept button hover state acceptButtonText: 'white', // Accept button text color declineButton: '#f5f5f5', // Decline button background declineButtonHover: '#e5e5e5', // Decline button hover state declineButtonText: '#666', // Decline button text color // Close button colors closeButton: '#f5f5f5', // Close button background closeButtonHover: '#e5e5e5', // Close button hover state closeButtonText: '#666', // Close button text color // Text and background colors headingText: '#1a1a1a', // Popup heading text color bodyText: '#666', // Popup body text color background: 'white', // Popup background color // Success message colors successBackground: '#e8f5e9', // Success message background successBorder: '#34c759', // Success message border successText: '#256029', // Success message text color // Dark mode colors (used when darkMode is enabled) darkMode: { background: '#2c2c2e', headingText: 'white', bodyText: '#a1a1a6', declineButton: '#48484a', declineButtonHover: '#5a5a5c', declineButtonText: '#a1a1a6', closeButton: '#48484a', closeButtonHover: '#5a5a5c', closeButtonText: '#a1a1a6', successBackground: '#1e3a1e', successBorder: '#30d158', successText: '#30d158' } } }); ``` ### Color Usage Notes - All color values accept standard CSS color formats (hex, rgb, rgba, named colors, etc.) - The `background` property supports gradients and advanced CSS background values - Dark mode colors are automatically applied when `darkMode: true` is set - If a color is not specified, the widget uses sensible defaults that match the original design - Colors are applied dynamically when the popup is created, allowing for runtime customization ## Usage Examples ### Basic Review Prompt ```javascript const reviewPopup = createReviewPopup({ heading: "Love Our App?", text: "Your 5-star review helps us reach more people!", autoTrigger: true, delay: 5000 }); ``` ### Interval-Based Review Prompts ```javascript // Show every 7 days, maximum 4 times over 30 days const reviewPopup = createReviewPopup({ heading: "Rate Our App", maxSessions: 4, timeframeDays: 30, initialDelay: 7, autoTrigger: true }); ``` ### Manual Trigger ```javascript const reviewPopup = createReviewPopup({ triggerElement: "#review-button", debugMode: true // for testing }); ``` ### Custom Color Branding ```javascript // Red theme for urgent review prompts const reviewPopup = createReviewPopup({ heading: "Love Our App?", text: "Your 5-star review helps us reach more people!", colors: { acceptButton: '#e74c3c', acceptButtonHover: '#c0392b', acceptButtonText: 'white', declineButton: '#f8d7da', declineButtonHover: '#f5c6cb', declineButtonText: '#721c24', headingText: '#dc3545', background: '#fff5f5' }, autoTrigger: true, debugMode: true }); ``` ## Rules to follow 1. First think through the problem, read the codebase for relevant files, and write a plan to tasks/todo.md. 2. The plan should have a list of todo items that you can check off as you complete them 3. Before you begin working, check in with me and I will verify the plan. 4. Then, begin working on the todo items, marking them as complete as you go. 5. Please every step of the way just give me a high level explanation of what changes you made 6. Make every task and code change you do as simple as possible. We want to avoid making any massive or complex changes. Every change should impact as little code as possible. Everything is about simplicity. 7. Finally, add a review section to the todo.md file with a summary of the changes you made and any other relevant information.