Configuration reference
This plugin has no system-config settings page. There is no config.xml and therefore no Extensions > My Extensions > Configure page for Ultimate Popups. All configuration lives on individual popup records, managed in Content > Ultimate Popups in the administration.
Entity: ssd_popup
The central entity. One row = one popup.
| Column | DAL field | Type | Required | Description |
|---|---|---|---|---|
id | id | UUID | Yes | Primary key. |
version_id | versionId | UUID | Yes | Shopware version key (always live in production). |
active | active | Boolean | — | Whether the popup is enabled. Defaults to false. Inactive popups are never shown. |
name | name | String (255) | Yes | Internal label visible in the admin list only. |
cms_page_id | cmsPageId | UUID | Yes | FK to cms_page.id — the desktop CMS layout to render inside the modal. |
cms_page_version_id | cmsPageVersionId | UUID | Yes | Version of the linked CMS page. |
mobile_cms_page_id | mobileCmsPageId | UUID | — | Optional FK to cms_page.id for phone viewports (XS, SM). Falls back to cms_page_id when NULL. |
mobile_cms_page_version_id | mobileCmsPageVersionId | UUID | — | Version of the mobile CMS page. |
tablet_cms_page_id | tabletCmsPageId | UUID | — | Optional FK to cms_page.id for tablet viewports (MD). Falls back to cms_page_id when NULL. |
tablet_cms_page_version_id | tabletCmsPageVersionId | UUID | — | Version of the tablet CMS page. |
display_frequency | displayFrequency | String | — | How often the popup shows to the same browser. Defaults to always. See Display frequency enum. Not per-viewport. |
modal_size | modalSize | String | — | Desktop Bootstrap modal size class. See Modal size enum. Per-viewport. |
vertical_align | verticalAlign | String (20) | — | Desktop vertical position. See Vertical alignment enum. Per-viewport. |
hide_header | hideHeader | Boolean | — | Desktop hide-header. Hides the modal header; floats the close button over the content. Defaults to false. Per-viewport. |
light_close_button | lightCloseButton | Boolean | — | Show the close (×) icon in white so it stays visible on dark popup backgrounds. Per-viewport. Defaults to false. |
display_trigger | displayTrigger | String | — | Desktop trigger. Defaults to immediate. See Display trigger enum. Per-viewport. |
display_delay | displayDelay | Integer (unsigned) | — | Desktop delay in seconds before opening (trigger immediate), and the no-hover fallback wait for exit_intent. NULL = no delay (defaults to 30 s for the exit-intent fallback). Per-viewport. |
custom_css | customCss | LongText | — | Desktop custom CSS injected for this popup. The </style> sequence is stripped on output. Per-viewport. |
required_consent_cookies | requiredConsentCookies | JSON array | — | Desktop list of cookie names the visitor must accept (in the storefront cookie-consent banner) before the popup is shown. NULL/empty = show regardless of consent. Per-viewport. |
targeting_mode | targetingMode | String | — | Page restriction strategy. NULL = all pages. See Targeting mode enum. |
target_routes | targetRoutes | JSON array | — | Array of route keys. Used when targeting_mode = 'page_restriction'. See Target route keys. |
custom_urls | customUrls | JSON array | — | Array of relative URL patterns. Used when targeting_mode = 'custom_url'. Supports * wildcard. |
custom_fields | customFields | JSON | — | Shopware custom fields extension point. |
created_at | createdAt | DateTime | — | Set automatically on create. |
updated_at | updatedAt | DateTime | — | Set automatically on update. |
Per-viewport override columns
Nine settings are configurable per device. The base column above holds the Desktop value; each also has nullable tablet_* and mobile_* override columns. NULL in an override column means inherit the Desktop value — this is the lock state (it is never inferred from emptiness, which is why custom_css carries the AllowEmptyString flag so an explicit empty override persists). Resolution is a flat coalesce: effectiveTablet = tablet ?? desktop, effectiveMobile = mobile ?? desktop (no tablet→mobile cascade).
| Field | Desktop (base) | Tablet override | Mobile override |
|---|---|---|---|
| CMS Page | cms_page_id (+ version) | tablet_cms_page_id | mobile_cms_page_id |
| Modal Size | modal_size | tablet_modal_size | mobile_modal_size |
| Vertical Alignment | vertical_align | tablet_vertical_align | mobile_vertical_align |
| Hide Header | hide_header | tablet_hide_header | mobile_hide_header |
| Light close icon | light_close_button | tablet_light_close_button | mobile_light_close_button |
| Display Trigger | display_trigger | tablet_display_trigger | mobile_display_trigger |
| Display Delay | display_delay | tablet_display_delay | mobile_display_delay |
| Custom CSS | custom_css | tablet_custom_css | mobile_custom_css |
| Required cookie consent | required_consent_cookies | tablet_required_consent_cookies | mobile_required_consent_cookies |
PopupEntity::getViewportConfig() returns the resolved { desktop, tablet, mobile } matrix that the storefront ships to the JS plugin. PHP resolves inheritance only; the JS picks the active device from the theme's --sw-current-breakpoint and applies that device's values (re-applying on breakpoint change).
Associations on ssd_popup
| Association | Type | Target entity | Pivot table |
|---|---|---|---|
rules | Many-to-many | rule | ssd_popup_rule |
salesChannels | Many-to-many | sales_channel | ssd_popup_sales_channel |
categories | Many-to-many | category | ssd_popup_category |
products | Many-to-many | product | ssd_popup_product |
cmsPage | Many-to-one | cms_page | — |
mobileCmsPage | Many-to-one | cms_page | — |
tabletCmsPage | Many-to-one | cms_page | — |
Pivot tables
ssd_popup_rule
Links a popup to Shopware Rule Builder rules (AND logic — all attached rules must match).
| Column | Type | Description |
|---|---|---|
popup_id | BINARY(16) | FK to ssd_popup.id |
ssd_popup_version_id | BINARY(16) | FK to ssd_popup.version_id |
rule_id | BINARY(16) | FK to rule.id |
ssd_popup_sales_channel
Links a popup to sales channels. Empty = show on all channels.
| Column | Type | Description |
|---|---|---|
popup_id | BINARY(16) | FK to ssd_popup.id |
ssd_popup_version_id | BINARY(16) | FK to ssd_popup.version_id |
sales_channel_id | BINARY(16) | FK to sales_channel.id |
ssd_popup_category
Links a popup to categories. Only checked when target_routes includes 'category'.
| Column | Type | Description |
|---|---|---|
popup_id | BINARY(16) | FK to ssd_popup.id |
ssd_popup_version_id | BINARY(16) | FK to ssd_popup.version_id |
category_id | BINARY(16) | FK to category.id |
category_version_id | BINARY(16) | FK to category.version_id |
ssd_popup_product
Links a popup to products. Only checked when target_routes includes 'product'.
| Column | Type | Description |
|---|---|---|
popup_id | BINARY(16) | FK to ssd_popup.id |
ssd_popup_version_id | BINARY(16) | FK to ssd_popup.version_id |
product_id | BINARY(16) | FK to product.id |
product_version_id | BINARY(16) | FK to product.version_id |
Enums
Modal size enum
Values for the modal_size column.
| Value | Label | Bootstrap class |
|---|---|---|
modal-sm | Small | modal-sm |
null | Default (Desktop base) | (none) |
modal-md | Default (Tablet/Mobile override) | (none) — sentinel for "explicit default" so the override stays distinct from NULL = inherit |
modal-lg | Large | modal-lg |
modal-xl | Extra Large | modal-xl |
modal-fullscreen | Fullscreen | modal-fullscreen |
Vertical alignment enum
Values for the vertical_align column.
| Value | Label | Behaviour |
|---|---|---|
null | (none) | Bootstrap default — aligns to top. |
top | Top | Same as default. |
center | Center | CSS flexbox align-items: center on .modal-dialog. |
bottom | Bottom | CSS flexbox align-items: flex-end on .modal-dialog. |
Display frequency enum
Values for the display_frequency column.
| Value | Label | Storage |
|---|---|---|
always | Always | Nothing stored. |
once_per_session | Once per Session | Session cookie ssd_popup_<id> (no expiry, shared across tabs, cleared on browser close). |
once_per_day | Once per Day (24 h) | localStorage key ssd_popup_<id> with timestamp. |
once_ever | Once Ever | localStorage key ssd_popup_<id>. |
Display trigger enum
Values for the display_trigger column.
| Value | Label | Behaviour |
|---|---|---|
immediate | Immediately (on page load) | Opens after display_delay seconds (or immediately if NULL). |
exit_intent | Exit Intent (when leaving page) | Opens on mouseleave from document.documentElement with event.clientY < 0. On no-hover (touch) devices it falls back to a timed display after the device's display_delay (default 30 s; 0 = immediate). |
Targeting mode enum
Values for the targeting_mode column.
| Value | Label | Behaviour |
|---|---|---|
null | (none) | Popup appears on all pages. |
page_restriction | Page Restriction | Popup appears on the routes listed in target_routes. |
custom_url | Custom URL | Popup appears on paths matching patterns in custom_urls. |
Target route keys
Values stored inside the target_routes JSON array.
| Key | Shopware route name | Default storefront path |
|---|---|---|
home | frontend.home.page | / |
cart | frontend.checkout.cart.page | /checkout/cart |
checkout_confirm | frontend.checkout.confirm.page | /checkout/confirm |
checkout_finish | frontend.checkout.finish.page | /checkout/finish |
login | frontend.account.login.page | /account/login |
product | frontend.detail.page | /detail/<id> |
category | frontend.navigation.page | /<category-seo-url> |
ACL permissions (ssd_popup)
The module registers permissions in the Shopware permission system under the content category with the key ssd_popup.
| Role | Grants | Dependencies |
|---|---|---|
viewer | ssd_popup:read, ssd_popup_rule:read, ssd_popup_category:read, ssd_popup_product:read, ssd_popup_sales_channel:read, cms_page:read, rule:read, category:read, product:read, sales_channel:read, sales_channel_type:read | None |
editor | ssd_popup:update, ssd_popup_rule:create, ssd_popup_rule:delete, ssd_popup_category:create, ssd_popup_category:delete, ssd_popup_product:create, ssd_popup_product:delete, ssd_popup_sales_channel:create, ssd_popup_sales_channel:delete | ssd_popup.viewer |
creator | ssd_popup:create | ssd_popup.viewer, ssd_popup.editor |
deleter | ssd_popup:delete | ssd_popup.viewer |
Assign these roles in Settings > System > Permissions when restricting admin users to view-only or editor access.
Storefront controller route
| Route name | HTTP method | Path | Description |
|---|---|---|---|
frontend.ssd-digital.popup.content | POST | /ssd-digital/popup/content/{id} | XHR-only endpoint. Accepts a device form field (desktop, tablet, mobile). Returns the rendered CMS page HTML for that popup and device. Used by the JS plugin to load popup content on demand. |
Administration API route
| Route name | HTTP method | Path | Description |
|---|---|---|---|
api.action.ssd-popup.consent-cookies | GET | /api/_action/ssd-popup/consent-cookies | Returns the selectable cookie-consent options ({ value, label }) for the Required cookie consent field. Built from Shopware's registered cookie groups, excluding the Required group and any hidden entries. Used by the popup editor. |
Entity extensions
The plugin extends the following Shopware core entities with back-reference associations (read-only, used internally):
| Entity | Extension field | Type |
|---|---|---|
category | ssdPopups | Many-to-many back-reference to ssd_popup |
product | ssdPopups | Many-to-many back-reference to ssd_popup |
cms_page | ssdPopups | Many-to-many back-reference to ssd_popup |
rule | ssdPopups | Many-to-many back-reference to ssd_popup |
sales_channel | ssdPopups | Many-to-many back-reference to ssd_popup |
Cookie Consent registration
The plugin registers one entry in the Shopware Cookie Manager:
| Property | Value |
|---|---|
| Cookie group | Required (cookie.groupRequired) |
| Snippet name | ssdUltimatePopup.cookie.name → "Ultimate Popup" |
| Cookie identifier | ssd_ultimate_popup |
| Expiration | 30 days |
The actual frequency-capping data is stored under keys matching ssd_popup_<popup-id>: Once per Session uses a session cookie (no expiry), while Once per Day and Once Ever use localStorage. This ssd_ultimate_popup entry is only the Cookie Manager declaration informing visitors that the plugin uses this required browser storage; the 30-day value applies to the declaration entry, not to the session cookie (which is cleared when the browser closes).