mhinspeya / inspeya-hyva-popup

1.1.6 2026-10-06 12:45 UTC

Requires

• mhinspeya/backend-mod: ^1.0.2

Suggests

• mhinspeya/backend-mod: Support Configuration

OSL-3.0

• MHinspeya

• magento
• magento 2
• MHinspeya

Published on Packagist.org on 2026-10-06 12:46 UTC

README

mhinspeya/inspeya-hyva-popup

A high-performance, responsive, and versatile on-site messaging extension for Magento 2 powered by Hyvä Themes (Alpine.js and Tailwind CSS).

Create dynamic modals, sticky announcement bars, lateral slide-in drawers, and intelligent cart FOMO popups directly from the Magento Admin Panel.

Table of Contents

1. Key Features & Highlights
2. Positioning & Layout Engine
3. Page-Level Targeting & Triggers
4. Shopping Cart Free Shipping & FOMO Rules
5. Administrative Audit Log
6. Documentation & In-Admin User Guide
7. Installation
8. Configuration
9. Hyvä & Alpine.js Architecture
10. Error Handling & Logging
11. Technical Specifications & Compatibility

Key Features & Highlights

• Hyvä First Architecture: Zero jQuery, zero RequireJS. Built exclusively with lightweight Alpine.js and Tailwind CSS.
• 100% Full Page Cache (FPC) Friendly: Dynamic asynchronous AJAX fetching ensures campaigns activate or deactivate immediately without flushing Varnish or LiteMage caches.
• Multi-Position Layout Engine: Choose from 10 display placements including Center Modal, Sticky Top Announcement Bar, Bottom Notification Bar, and Left/Right Slide-in Drawers.
• Precise Visitor Targeting: Segment by Store View, Customer Groups (Guest, General, Wholesale), and Date Schedule (Valid From / Valid To).
• Smart Display Triggers: Trigger popups immediately on page load, after a specified delay in seconds, or upon scrolling a percentage of the page height.
• Visitor Frequency Capping: Restrict impression frequency per shopper (Every time, Once per hour, Once per day, Once per week, Once per month).
• MSI Stock Urgency: Product Detail Page (PDP) popups display real-time inventory from Magento Multi-Source Inventory (MSI) to motivate immediate purchases.
• Built-in Administrative Audit Trail: Automatically logs admin campaign actions (Created, Updated, Deleted, Mass Deleted) with admin usernames, IP addresses, and timestamps.
• In-Admin Documentation: Interactive User Guide and Product Overview viewable directly from Magento System Configuration.

Positioning & Layout Engine

Clever Popup offers versatile screen placements:

Position	Viewport Behavior	Recommended Use Case
Center Modal	Centered dialog with backdrop blur	Major promotional campaigns, welcome vouchers, newsletter signup
Top Announcement Bar	Fixed sticky bar pinned above header	Site-wide alerts, flash sale coupon codes, shipping cutoffs
Bottom Notification Bar	Sticky ribbon along the footer	Cookie consent notices, active sale reminders, helpline info
Left Sidebar Drawer	Smooth slide-in drawer from the left edge	Vertical banners, brand storytelling, catalogue teasers
Right Sidebar Drawer	Smooth slide-in drawer from the right edge	Cross-sell product recommendations, VIP perks, social proof alerts
Corners (TL, TR, BL, BR)	Compact floating boxes in screen corners	Unobtrusive notifications, chat prompts, quick reviews

Visual Showcase:

Center Modal Popup

Sticky Top Announcement Bar

Sticky Bottom Notification Bar

Left & Right Slide-In Drawers

Left Slide-In Drawer	Right Slide-In Drawer

Page-Level Targeting & Triggers

Clever Popup supports contextual delivery across standard e-commerce pages:

Page Context	Endpoint	Description
Homepage	GetPopups	Sitewide branding, newsletter opt-ins, welcome incentives
Category Page	CategoryPopups	Targeted promotions scoped to specific category IDs
Product Page (PDP)	ProductsPopups	Real-time MSI stock countdowns and product cross-sells
CMS Pages	CmsPopups	Scoped to individual CMS page identifiers
Shopping Cart Page	CartPopups	Cart subtotal incentives and Free Shipping progress alerts

⚠️ Note: To protect conversion rates, popups are not displayed on the checkout page.

Shopping Cart Free Shipping & FOMO Rules

Clever Popup transforms standard cart abandonment into an average order value (AOV) driver:

• Cart Price Rule Integration: Evaluates active Magento Free Shipping cart price rules.
• Dynamic Amount Calculation: Calculates current basket subtotal and dynamically indicates how much more to add: "Add €15.00 more to qualify for FREE Delivery!"
• FOMO (Fear Of Missing Out) Urgency: Displays countdown alerts that encourage rapid checkout before promotional discounts expire.

Administrative Audit Log

Path: Inspeya → Clever Popup → Clever Popup Audit Log

Clever Popup includes an enterprise audit log for accountability across multi-admin teams:

• Tracks Created, Updated, Deleted, and Mass Deleted events.
• Records Admin Username, Client IP Address, Campaign Title, and UTC Timestamp.
• Fully searchable UI component grid with date range filtering.

Documentation & In-Admin User Guide

Merchants can review the complete visual User Guide and Product Overview directly inside the Magento Admin:

1. Navigate to: Stores → Configuration → MHinspeya.de → Clever Popup
2. In the General Settings group, click:
   • View User Guide: Opens the complete step-by-step user manual with high-resolution screenshots.
   • View Overview: Opens the product executive summary and feature guide.

Documentation files are also available locally in the module directory:

• USER_GUIDE.md & USER_GUIDE.html
• OVERVIEW.md & OVERVIEW.html

Installation

Method 1: Composer (Recommended)

composer require mhinspeya/inspeya-hyva-popup
bin/magento module:enable MHinspeya_BackendMod MHinspeya_Popup
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Method 2: Manual Installation

1. Copy the module files to app/code/MHinspeya/Popup.
2. Enable and compile:

   bin/magento module:enable MHinspeya_BackendMod MHinspeya_Popup
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   

Configuration

Global Settings

Navigate to: Stores → Configuration → MHinspeya.de → Clever Popup

• Documentation & User Guide: Action buttons to view offline and online user manuals.
• License Key: Enter your commercial license key.
• Module Enable: Master toggle for the entire extension.
• Page-Type Switches: Enable or disable popups individually on Homepage, CMS Pages, Category Pages, Product Pages, and Cart Page.

Campaign Management

Navigate to: Inspeya → Clever Popup → Clever Popup List

Click Add New Popup to configure:

• Popup Information: Title, Status, Store Scope, Customer Groups, Scheduling (Valid From / Valid To).
• Content: HTML / WYSIWYG editor supporting custom text, CTA buttons, and coupon codes.
• Layout & Dimensions: Position (Center, Top, Bottom, Left, Right, Corners), custom width/height.
• Triggers & Delay: When to show (Immediate, Delay in seconds, Scroll %), Auto-dismiss timer.
• Display Frequency: Per-visitor frequency cap (Every time, 1 hour, 1 day, 1 week, 1 month).

Hyvä & Alpine.js Architecture

• Pure Alpine.js Component: Light footprint (~15 KB runtime); zero blocking scripts.
• Tailwind CSS Styling: Full responsive utility classes with smooth CSS opacity and transform transitions.
• FPC Cache Independence: Toggling popup campaigns in Magento Admin takes effect immediately on storefront visits via dynamic AJAX without invalidating the Full Page Cache.

Error Handling & Logging

All controllers implement structured exception handling:

• Admin Controllers: Safe handling with user-friendly notices and detailed debugging traces.
• Storefront AJAX Endpoints: Guarded with try/catch blocks returning safe fallback JSON {error: true} instead of HTTP 500 errors.
• Dedicated Log File: Logged to var/log/popup.log.

Technical Specifications & Compatibility

Specification	Requirement / Support
Magento Version	2.4.4, 2.4.5, 2.4.6, 2.4.7, 2.4.8
PHP Version	PHP 8.1, PHP 8.2, PHP 8.3, PHP 8.4
Theme Compatibility	Hyvä Themes (v1.1.x, v1.2.x, v1.3.x)
Frontend Libraries	Alpine.js 2.x / 3.x, Tailwind CSS
Inventory Support	Multi-Source Inventory (MSI) Real-time Stock
ACL Permission	MHinspeya_Popup::config_popup, MHinspeya_Popup::auditlog

© MHinspeya — All Rights Reserved