Konfigurationsreferenz
Dieses Plugin hat keine System-Config-Einstellungsseite. Es gibt keine config.xml und daher auch keine Erweiterungen > Meine Erweiterungen > Konfigurieren-Seite für Ultimate Popups. Die gesamte Konfiguration liegt auf einzelnen Popup-Datensätzen, die unter Inhalte > Ultimate Popups in der Administration verwaltet werden.
Entity: ssd_popup
Die zentrale Entity. Eine Zeile = ein Popup.
| Spalte | DAL-Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id | id | UUID | Ja | Primärschlüssel. |
version_id | versionId | UUID | Ja | Shopware-Versionsschlüssel (in Produktion immer live). |
active | active | Boolean | — | Gibt an, ob das Popup aktiviert ist. Standard: false. Inaktive Popups werden nie angezeigt. |
name | name | String (255) | Ja | Interne Bezeichnung, nur in der Admin-Liste sichtbar. |
cms_page_id | cmsPageId | UUID | Ja | FK auf cms_page.id — das Desktop-CMS-Layout, das im Modal angezeigt wird. |
cms_page_version_id | cmsPageVersionId | UUID | Ja | Version der verknüpften CMS-Seite. |
mobile_cms_page_id | mobileCmsPageId | UUID | — | Optionales FK auf cms_page.id für Smartphone-Viewports (XS, SM). Fällt auf cms_page_id zurück, wenn NULL. |
mobile_cms_page_version_id | mobileCmsPageVersionId | UUID | — | Version der mobilen CMS-Seite. |
tablet_cms_page_id | tabletCmsPageId | UUID | — | Optionales FK auf cms_page.id für Tablet-Viewports (MD). Fällt auf cms_page_id zurück, wenn NULL. |
tablet_cms_page_version_id | tabletCmsPageVersionId | UUID | — | Version der Tablet-CMS-Seite. |
display_frequency | displayFrequency | String | — | Wie oft das Popup demselben Browser angezeigt wird. Standard: always. Siehe Anzeigehäufigkeit-Enum. Nicht gerätespezifisch. |
modal_size | modalSize | String | — | Bootstrap-Modal-Größenklasse für Desktop. Siehe Modalgröße-Enum. Gerätespezifisch. |
vertical_align | verticalAlign | String (20) | — | Vertikale Position für Desktop. Siehe Vertikale-Ausrichtung-Enum. Gerätespezifisch. |
hide_header | hideHeader | Boolean | — | Desktop-Header ausblenden. Blendet den Modal-Header aus; positioniert den Schließen-Button als Overlay. Standard: false. Gerätespezifisch. |
light_close_button | lightCloseButton | Boolean | — | Zeigt das Schließen-Symbol (×) in Weiß, damit es auf dunklem Popup-Hintergrund sichtbar bleibt. Gerätespezifisch. Standard: false. |
display_trigger | displayTrigger | String | — | Auslöser für Desktop. Standard: immediate. Siehe Anzeigeauslöser-Enum. Gerätespezifisch. |
display_delay | displayDelay | Integer (unsigned) | — | Desktop-Verzögerung in Sekunden vor dem Öffnen (Auslöser immediate) und Wartezeit als No-Hover-Fallback für exit_intent. NULL = keine Verzögerung (Standard 30 s für den Exit-Intent-Fallback). Gerätespezifisch. |
custom_css | customCss | LongText | — | Desktop-eigenes CSS, das für dieses Popup injiziert wird. Die Zeichenfolge </style> wird bei der Ausgabe entfernt. Gerätespezifisch. |
required_consent_cookies | requiredConsentCookies | JSON-Array | — | Desktop-Liste von Cookie-Namen, die der Besucher (im Cookie-Banner der Storefront) akzeptieren muss, bevor das Popup angezeigt wird. NULL/leer = unabhängig von der Einwilligung anzeigen. Gerätespezifisch. |
targeting_mode | targetingMode | String | — | Seiteneinschränkungsstrategie. NULL = alle Seiten. Siehe Zielmodus-Enum. |
target_routes | targetRoutes | JSON-Array | — | Array von Routen-Schlüsseln. Verwendet, wenn targeting_mode = 'page_restriction'. Siehe Zielrouten-Schlüssel. |
custom_urls | customUrls | JSON-Array | — | Array von relativen URL-Mustern. Verwendet, wenn targeting_mode = 'custom_url'. Unterstützt *-Wildcard. |
custom_fields | customFields | JSON | — | Shopware Custom-Fields-Erweiterungspunkt. |
created_at | createdAt | DateTime | — | Wird automatisch beim Erstellen gesetzt. |
updated_at | updatedAt | DateTime | — | Wird automatisch beim Aktualisieren gesetzt. |
Per-Viewport-Override-Spalten
Neun Einstellungen sind pro Gerät konfigurierbar. Die obige Basis-Spalte enthält den Desktop-Wert; jede hat zusätzlich nullable tablet_*- und mobile_*-Override-Spalten. NULL in einer Override-Spalte bedeutet Desktop-Wert übernehmen — dies ist der gesperrte Zustand (er wird nie aus Leerheit abgeleitet, weshalb custom_css das Flag AllowEmptyString trägt, damit ein explizit leerer Override erhalten bleibt). Die Auflösung ist ein flaches Coalesce: effectiveTablet = tablet ?? desktop, effectiveMobile = mobile ?? desktop (keine Tablet→Mobil-Kaskade).
| Feld | Desktop (Basis) | Tablet-Override | Mobil-Override |
|---|---|---|---|
| CMS Seite | cms_page_id (+ Version) | tablet_cms_page_id | mobile_cms_page_id |
| Modalgröße | modal_size | tablet_modal_size | mobile_modal_size |
| Vertikale Ausrichtung | vertical_align | tablet_vertical_align | mobile_vertical_align |
| Header ausblenden | hide_header | tablet_hide_header | mobile_hide_header |
| Helles Schließen-Symbol | light_close_button | tablet_light_close_button | mobile_light_close_button |
| Anzeigeauslöser | display_trigger | tablet_display_trigger | mobile_display_trigger |
| Verzögerung | display_delay | tablet_display_delay | mobile_display_delay |
| Eigenes CSS | custom_css | tablet_custom_css | mobile_custom_css |
| Erforderliche Cookie-Einwilligung | required_consent_cookies | tablet_required_consent_cookies | mobile_required_consent_cookies |
PopupEntity::getViewportConfig() gibt die aufgelöste { desktop, tablet, mobile }-Matrix zurück, die die Storefront an das JS-Plugin ausliefert. PHP löst nur die Vererbung auf; das JS wählt das aktive Gerät anhand des --sw-current-breakpoint des Themes und wendet die Werte dieses Geräts an (mit erneuter Anwendung bei Breakpoint-Wechsel).
Assoziationen auf ssd_popup
| Assoziation | Typ | Ziel-Entity | Pivot-Tabelle |
|---|---|---|---|
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-Tabellen
ssd_popup_rule
Verknüpft ein Popup mit Shopware-Rule-Builder-Regeln (UND-Logik — alle angehängten Regeln müssen zutreffen).
| Spalte | Typ | Beschreibung |
|---|---|---|
popup_id | BINARY(16) | FK auf ssd_popup.id |
ssd_popup_version_id | BINARY(16) | FK auf ssd_popup.version_id |
rule_id | BINARY(16) | FK auf rule.id |
ssd_popup_sales_channel
Verknüpft ein Popup mit Verkaufskanälen. Leer = auf allen Kanälen anzeigen.
| Spalte | Typ | Beschreibung |
|---|---|---|
popup_id | BINARY(16) | FK auf ssd_popup.id |
ssd_popup_version_id | BINARY(16) | FK auf ssd_popup.version_id |
sales_channel_id | BINARY(16) | FK auf sales_channel.id |
ssd_popup_category
Verknüpft ein Popup mit Kategorien. Wird nur geprüft, wenn target_routes 'category' enthält.
| Spalte | Typ | Beschreibung |
|---|---|---|
popup_id | BINARY(16) | FK auf ssd_popup.id |
ssd_popup_version_id | BINARY(16) | FK auf ssd_popup.version_id |
category_id | BINARY(16) | FK auf category.id |
category_version_id | BINARY(16) | FK auf category.version_id |
ssd_popup_product
Verknüpft ein Popup mit Produkten. Wird nur geprüft, wenn target_routes 'product' enthält.
| Spalte | Typ | Beschreibung |
|---|---|---|
popup_id | BINARY(16) | FK auf ssd_popup.id |
ssd_popup_version_id | BINARY(16) | FK auf ssd_popup.version_id |
product_id | BINARY(16) | FK auf product.id |
product_version_id | BINARY(16) | FK auf product.version_id |
Enums
Modalgröße-Enum
Werte für die Spalte modal_size.
| Wert | Bezeichnung | Bootstrap-Klasse |
|---|---|---|
modal-sm | Klein | modal-sm |
null | Standard (Desktop-Basis) | (keine) |
modal-md | Standard (Tablet/Mobil-Override) | (keine) — Sentinel für „expliziter Standard", damit der Override sich von NULL = vererben unterscheidet |
modal-lg | Groß | modal-lg |
modal-xl | Extra Groß | modal-xl |
modal-fullscreen | Vollbild | modal-fullscreen |
Vertikale-Ausrichtung-Enum
Werte für die Spalte vertical_align.
| Wert | Bezeichnung | Verhalten |
|---|---|---|
null | (keine) | Bootstrap-Standard — ausgerichtet nach oben. |
top | Oben | Wie Standard. |
center | Mitte | CSS-Flexbox align-items: center auf .modal-dialog. |
bottom | Unten | CSS-Flexbox align-items: flex-end auf .modal-dialog. |
Anzeigehäufigkeit-Enum
Werte für die Spalte display_frequency.
| Wert | Bezeichnung | Speicher |
|---|---|---|
always | Immer | Nichts gespeichert. |
once_per_session | Einmal pro Sitzung | Session-Cookie ssd_popup_<id> (ohne Ablauf, über Tabs hinweg geteilt, beim Schließen des Browsers gelöscht). |
once_per_day | Einmal pro Tag (24 h) | localStorage-Schlüssel ssd_popup_<id> mit Zeitstempel. |
once_ever | Einmalig | localStorage-Schlüssel ssd_popup_<id>. |
Anzeigeauslöser-Enum
Werte für die Spalte display_trigger.
| Wert | Bezeichnung | Verhalten |
|---|---|---|
immediate | Sofort (beim Seitenaufruf) | Öffnet nach display_delay Sekunden (oder sofort, wenn NULL). |
exit_intent | Exit-Intent (beim Verlassen der Seite) | Öffnet bei mouseleave von document.documentElement mit event.clientY < 0. Auf Nicht-Hover-Geräten (Touch) fällt es auf eine zeitgesteuerte Anzeige nach dem display_delay des Geräts zurück (Standard 30 s; 0 = sofort). |
Zielmodus-Enum
Werte für die Spalte targeting_mode.
| Wert | Bezeichnung | Verhalten |
|---|---|---|
null | (keine) | Popup erscheint auf allen Seiten. |
page_restriction | Seitenbeschränkung | Popup erscheint auf den in target_routes aufgeführten Routen. |
custom_url | Benutzerdefinierte URL | Popup erscheint auf Pfaden, die Muster in custom_urls entsprechen. |
Zielrouten-Schlüssel
Werte, die im JSON-Array target_routes gespeichert werden.
| Schlüssel | Shopware-Routenname | Standard-Storefront-Pfad |
|---|---|---|
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 | /<kategorie-seo-url> |
ACL-Berechtigungen (ssd_popup)
Das Modul registriert Berechtigungen im Shopware-Berechtigungssystem unter der Kategorie content mit dem Schlüssel ssd_popup.
| Rolle | Gewährt | Abhängigkeiten |
|---|---|---|
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 | Keine |
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 |
Weisen Sie diese Rollen unter Einstellungen > System > Berechtigungen zu, wenn Sie Admin-Benutzer auf Ansicht oder Bearbeitung beschränken möchten.
Storefront-Controller-Route
| Routenname | HTTP-Methode | Pfad | Beschreibung |
|---|---|---|---|
frontend.ssd-digital.popup.content | POST | /ssd-digital/popup/content/{id} | Nur XHR-Endpunkt. Akzeptiert ein device-Formularfeld (desktop, tablet, mobile). Gibt das gerenderte CMS-Seiten-HTML für dieses Popup und Gerät zurück. Vom JS-Plugin genutzt, um Popup-Inhalte bei Bedarf zu laden. |
Administration-API-Route
| Routenname | HTTP-Methode | Pfad | Beschreibung |
|---|---|---|---|
api.action.ssd-popup.consent-cookies | GET | /api/_action/ssd-popup/consent-cookies | Gibt die auswählbaren Cookie-Consent-Optionen ({ value, label }) für das Feld Erforderliche Cookie-Einwilligung zurück. Wird aus Shopwares registrierten Cookie-Gruppen aufgebaut, ohne die Gruppe „Erforderlich" und versteckte Einträge. Wird vom Popup-Editor verwendet. |
Entity-Erweiterungen
Das Plugin erweitert folgende Shopware-Core-Entities mit Back-Reference-Assoziationen (schreibgeschützt, intern genutzt):
| Entity | Erweiterungsfeld | Typ |
|---|---|---|
category | ssdPopups | Many-to-many-Rückverweis auf ssd_popup |
product | ssdPopups | Many-to-many-Rückverweis auf ssd_popup |
cms_page | ssdPopups | Many-to-many-Rückverweis auf ssd_popup |
rule | ssdPopups | Many-to-many-Rückverweis auf ssd_popup |
sales_channel | ssdPopups | Many-to-many-Rückverweis auf ssd_popup |
Cookie-Consent-Registrierung
Das Plugin registriert einen Eintrag im Shopware Cookie-Manager:
| Eigenschaft | Wert |
|---|---|
| Cookie-Gruppe | Erforderlich (cookie.groupRequired) |
| Snippet-Name | ssdUltimatePopup.cookie.name → „Ultimate Popup" |
| Cookie-Bezeichner | ssd_ultimate_popup |
| Ablauf | 30 Tage |
Die eigentlichen Häufigkeitsbeschränkungsdaten werden unter Schlüsseln nach dem Muster ssd_popup_<popup-id> gespeichert: Einmal pro Sitzung nutzt ein Session-Cookie (ohne Ablauf), Einmal pro Tag und Einmalig nutzen localStorage. Dieser ssd_ultimate_popup-Eintrag ist lediglich die Deklaration im Cookie-Manager, die den Besucher darüber informiert, dass das Plugin diesen erforderlichen Browser-Speicher nutzt; der 30-Tage-Wert gilt für den Deklarationseintrag, nicht für das Session-Cookie (das beim Schließen des Browsers gelöscht wird).