Skip to content

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.

ColumnDAL fieldTypeRequiredDescription
ididUUIDYesPrimary key.
version_idversionIdUUIDYesShopware version key (always live in production).
activeactiveBoolean—Whether the popup is enabled. Defaults to false. Inactive popups are never shown.
namenameString (255)YesInternal label visible in the admin list only.
cms_page_idcmsPageIdUUIDYesFK to cms_page.id — the desktop CMS layout to render inside the modal.
cms_page_version_idcmsPageVersionIdUUIDYesVersion of the linked CMS page.
mobile_cms_page_idmobileCmsPageIdUUID—Optional FK to cms_page.id for phone viewports (XS, SM). Falls back to cms_page_id when NULL.
mobile_cms_page_version_idmobileCmsPageVersionIdUUID—Version of the mobile CMS page.
tablet_cms_page_idtabletCmsPageIdUUID—Optional FK to cms_page.id for tablet viewports (MD). Falls back to cms_page_id when NULL.
tablet_cms_page_version_idtabletCmsPageVersionIdUUID—Version of the tablet CMS page.
display_frequencydisplayFrequencyString—How often the popup shows to the same browser. Defaults to always. See Display frequency enum. Not per-viewport.
modal_sizemodalSizeString—Desktop Bootstrap modal size class. See Modal size enum. Per-viewport.
vertical_alignverticalAlignString (20)—Desktop vertical position. See Vertical alignment enum. Per-viewport.
hide_headerhideHeaderBoolean—Desktop hide-header. Hides the modal header; floats the close button over the content. Defaults to false. Per-viewport.
light_close_buttonlightCloseButtonBoolean—Show the close (×) icon in white so it stays visible on dark popup backgrounds. Per-viewport. Defaults to false.
display_triggerdisplayTriggerString—Desktop trigger. Defaults to immediate. See Display trigger enum. Per-viewport.
display_delaydisplayDelayInteger (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_csscustomCssLongText—Desktop custom CSS injected for this popup. The </style> sequence is stripped on output. Per-viewport.
required_consent_cookiesrequiredConsentCookiesJSON 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.
typetypeString (20)—What the message is. Defaults to popup. See Type enum. Saving banner needs Pro.
banner_positionbannerPositionString (30)—Where a banner sits in the page. Required for banners. See Banner position enum.
banner_prioritybannerPriorityInteger—Stacking order of banners in the same position, higher on top. Defaults to 0. Equal values: oldest first.
targeting_modetargetingModeString—Page restriction strategy. NULL = all pages. See Targeting mode enum.
target_routestargetRoutesJSON array—Array of route keys. Used when targeting_mode = 'page_restriction'. See Target route keys.
custom_urlscustomUrlsJSON array—Array of relative URL patterns. Used when targeting_mode = 'custom_url'. Supports * wildcard.
custom_fieldscustomFieldsJSON—Shopware custom fields extension point.
created_atcreatedAtDateTime—Set automatically on create.
updated_atupdatedAtDateTime—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).

FieldDesktop (base)Tablet overrideMobile override
CMS Pagecms_page_id (+ version)tablet_cms_page_idmobile_cms_page_id
Modal Sizemodal_sizetablet_modal_sizemobile_modal_size
Vertical Alignmentvertical_aligntablet_vertical_alignmobile_vertical_align
Hide Headerhide_headertablet_hide_headermobile_hide_header
Light close iconlight_close_buttontablet_light_close_buttonmobile_light_close_button
Display Triggerdisplay_triggertablet_display_triggermobile_display_trigger
Display Delaydisplay_delaytablet_display_delaymobile_display_delay
Custom CSScustom_csstablet_custom_cssmobile_custom_css
Required cookie consentrequired_consent_cookiestablet_required_consent_cookiesmobile_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 ​

AssociationTypeTarget entityPivot table
rulesMany-to-manyrulessd_popup_rule
salesChannelsMany-to-manysales_channelssd_popup_sales_channel
categoriesMany-to-manycategoryssd_popup_category
productsMany-to-manyproductssd_popup_product
cmsPageMany-to-onecms_page—
mobileCmsPageMany-to-onecms_page—
tabletCmsPageMany-to-onecms_page—

Pivot tables ​

ssd_popup_rule ​

Links a popup to Shopware Rule Builder rules (AND logic — all attached rules must match).

ColumnTypeDescription
popup_idBINARY(16)FK to ssd_popup.id
ssd_popup_version_idBINARY(16)FK to ssd_popup.version_id
rule_idBINARY(16)FK to rule.id

ssd_popup_sales_channel ​

Links a popup to sales channels. Empty = show on all channels.

ColumnTypeDescription
popup_idBINARY(16)FK to ssd_popup.id
ssd_popup_version_idBINARY(16)FK to ssd_popup.version_id
sales_channel_idBINARY(16)FK to sales_channel.id

ssd_popup_category ​

Links a popup to categories. Only checked when target_routes includes 'category'.

ColumnTypeDescription
popup_idBINARY(16)FK to ssd_popup.id
ssd_popup_version_idBINARY(16)FK to ssd_popup.version_id
category_idBINARY(16)FK to category.id
category_version_idBINARY(16)FK to category.version_id

ssd_popup_product ​

Links a popup to products. Only checked when target_routes includes 'product'.

ColumnTypeDescription
popup_idBINARY(16)FK to ssd_popup.id
ssd_popup_version_idBINARY(16)FK to ssd_popup.version_id
product_idBINARY(16)FK to product.id
product_version_idBINARY(16)FK to product.version_id

Enums ​

Values for the modal_size column.

ValueLabelBootstrap class
modal-smSmallmodal-sm
nullDefault (Desktop base)(none)
modal-mdDefault (Tablet/Mobile override)(none) — sentinel for "explicit default" so the override stays distinct from NULL = inherit
modal-lgLargemodal-lg
modal-xlExtra Largemodal-xl
modal-fullscreenFullscreenmodal-fullscreen

Vertical alignment enum ​

Values for the vertical_align column.

ValueLabelBehaviour
null(none)Bootstrap default — aligns to top.
topTopSame as default.
centerCenterCSS flexbox align-items: center on .modal-dialog.
bottomBottomCSS flexbox align-items: flex-end on .modal-dialog.

Display frequency enum ​

Values for the display_frequency column.

ValueLabelStorage
alwaysAlwaysNothing stored.
once_per_sessionOnce per SessionSession cookie ssd_popup_<id> (no expiry, shared across tabs, cleared on browser close).
once_per_dayOnce per Day (24 h)localStorage key ssd_popup_<id> with timestamp.
once_everOnce EverlocalStorage key ssd_popup_<id>.

Display trigger enum ​

Values for the display_trigger column.

ValueLabelBehaviour
immediateImmediately (on page load)Opens after display_delay seconds (or immediately if NULL).
exit_intentExit 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).

Type enum ​

Values for the type column.

ValueLabelBehaviour
popupPopupA modal window opened by the trigger. Free.
bannerBannerA strip rendered inside the page layout. Needs Pro. Without Pro it is not rendered and the API rejects saving it.

Values for the banner_position column.

ValueLabelPlacement
above_headerAbove headerBefore the header.
below_navigationBelow navigationBetween the header and the page content.
above_footerAbove footerBetween the page content and the footer.
below_footerBelow footerAfter the footer.

Targeting mode enum ​

Values for the targeting_mode column.

ValueLabelBehaviour
null(none)Popup appears on all pages.
page_restrictionPage RestrictionPopup appears on the routes listed in target_routes.
custom_urlCustom URLPopup appears on paths matching patterns in custom_urls.

Target route keys ​

Values stored inside the target_routes JSON array.

KeyShopware route nameDefault storefront path
homefrontend.home.page/
cartfrontend.checkout.cart.page/checkout/cart
checkout_confirmfrontend.checkout.confirm.page/checkout/confirm
checkout_finishfrontend.checkout.finish.page/checkout/finish
loginfrontend.account.login.page/account/login
productfrontend.detail.page/detail/<id>
categoryfrontend.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.

RoleGrantsDependencies
viewerssd_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:readNone
editorssd_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:deletessd_popup.viewer
creatorssd_popup:createssd_popup.viewer, ssd_popup.editor
deleterssd_popup:deletessd_popup.viewer

Assign these roles in Settings > System > Permissions when restricting admin users to view-only or editor access.


Storefront controller route ​

Route nameHTTP methodPathDescription
frontend.ssd-digital.popup.contentPOST/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 nameHTTP methodPathDescription
api.action.ssd-popup.consent-cookiesGET/api/_action/ssd-popup/consent-cookiesReturns 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):

EntityExtension fieldType
categoryssdPopupsMany-to-many back-reference to ssd_popup
productssdPopupsMany-to-many back-reference to ssd_popup
cms_pagessdPopupsMany-to-many back-reference to ssd_popup
rulessdPopupsMany-to-many back-reference to ssd_popup
sales_channelssdPopupsMany-to-many back-reference to ssd_popup

The plugin registers one entry in the Shopware Cookie Manager:

PropertyValue
Cookie groupRequired (cookie.groupRequired)
Snippet namessdUltimatePopup.cookie.name → "Ultimate Popup"
Cookie identifierssd_ultimate_popup
Expiration30 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).

Your Vision. Signed, Sealed, Delivered.