Abonnement-Widget

Das Abonnement-Widget besteht aus einer Aufforderung und einer Launcher-Glocke, die Website-Besucher einladen, Push-Benachrichtigungen zu abonnieren. Beide werden gemeinsam als subscriptionWidget konfiguriert, aber unabhängig voneinander aktiviert: nur die Aufforderung, nur die Glocke oder beide zugleich. Sobald eines von beiden aktiviert ist, ersetzt es die Schaltfläche für Push-Abonnements, das benutzerdefinierte Abonnement-Popup und die Abonnement-Aufforderung — solange mindestens ein Teil aktiv ist, wird keines dieser drei älteren Widgets auf der Seite geladen.

Ein Besucher, der sich noch nicht entschieden hat, sieht die Aufforderung der Einladung. Ein Besucher, der Benachrichtigungen bereits blockiert hat, sieht stattdessen eine Erklärung, wie er sie entsperren kann.

Voraussetzungen

Stellen Sie sicher, dass Sie Pushwoosh Web SDK 3.0 auf Ihrer Website implementiert haben. Folgen Sie dazu unserem Integrationsleitfaden.

1. Aufforderung und Glocke aktivieren

Fügen Sie den Parameter subscriptionWidget zur WebSDK-Initialisierung hinzu und setzen Sie prompt.enabled und/oder launcher.enabled auf true:

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);

Kein einzelner Hauptschalter

Ein subscriptionWidget.enable auf oberster Ebene wird nicht ausgewertet. Wenn nur dieses Feld gesetzt ist, wird nichts aktiviert. Siehe Migration von den älteren Widgets weiter unten.

Jedes der folgenden Felder ist optional. Ein ausgelassenes Feld verwendet seinen Standardwert. Im Init-Snippet wird eine Zahl außerhalb ihres Bereichs stillschweigend auf die nächste Grenze begrenzt, und ein ungültiger Enum-Wert wird stillschweigend auf seinen Standardwert zurückgesetzt, ohne Konsolenwarnung. Die weiter unten beschriebenen Control-Panel-Formulare validieren jedes Feld und verweigern das Speichern eines ungültigen Werts.

2. Aufforderung und Glocke konfigurieren

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      layout: 'card',       // 'card' | 'bar' | 'modal'
      position: 'bottom-right',
      iconUrl: 'https://url-image.png',
      borderRadius: 12,     // 0–32
      overlay: false,
    },
    launcher: {
      enabled: true,
      position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
      offset: 20,           // 0–100
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    display: {
      trigger: 'auto',      // 'auto' | 'launcher' | 'manual'
      delay: 5,             // seconds, 0–3600
      cappingCount: 3,      // auto-shows per visitor, 0–100, 0 = unlimited
      cappingInterval: 24,  // hours between auto-shows, 0–8760
    },
    texts: {
      title: 'Stay in the loop',
      message: 'Get notified about news and updates.',
      acceptText: 'Allow',
      declineText: 'Not now',
      closeText: 'Close',
      blockedTitle: 'Notifications are blocked',
      blockedMessage: 'Enable notifications in your browser settings to stay updated.',
      launcherLabel: 'Subscribe to notifications',
      launcherBlockedLabel: 'Notifications are blocked',
    },
    colors: {
      background: '#ffffff',
      accent: '#4285f4',
      text: '#000000',
      textSecondary: '#666666',
    },
  }
}]);

Layout und Position

prompt.layout legt die Form der Aufforderung fest:

• card — eine kompakte Karte, verankert an einer Kante oder Ecke. prompt.position akzeptiert top, bottom, top-left, top-right, bottom-left oder bottom-right.
• bar — eine Leiste über die gesamte Seitenbreite. prompt.position akzeptiert nur top oder bottom.
• modal — ein auf der Seite zentriertes Fenster. prompt.position ist immer center.

Prüfen Sie die obige Liste für das von Ihnen eingestellte Layout, bevor Sie eine Position wählen. Im Init-Snippet wird eine vom aktuellen Layout nicht unterstützte Position stillschweigend durch den Standardwert des Layouts ersetzt. Das Control-Panel-Formular lehnt die Kombination stattdessen ab.

Wann die Aufforderung angezeigt wird

display.trigger steuert, wodurch die Aufforderung geöffnet wird:

• auto — öffnet sich automatisch display.delay Sekunden nach dem Laden der Seite, dann erneut alle display.cappingInterval Stunden, falls der Besucher sich nicht entschieden hat, bis zu display.cappingCount Mal insgesamt (0 bedeutet kein Limit).
• launcher — öffnet sich nie per Timer. Setzen Sie dies zusammen mit launcher.enabled: true, damit ein Klick auf die Glocke sie öffnen kann. Die manuelle API öffnet sie unabhängig von dieser Einstellung und davon, ob die Glocke aktiviert ist.
• manual — öffnet sich nur über Pushwoosh.moduleRegistry.subscriptionWidget, weiter unten beschrieben.

display.delay, display.cappingCount und display.cappingInterval gelten nur für den auto-Trigger.

Die Launcher-Glocke

launcher.enabled zeigt eine schwebende Glocke für einen Besucher an, der auf die Aufforderung noch reagieren kann (noch nicht abonniert oder blockiert), unabhängig von der Aufforderung und von display.trigger. Die Glocke bleibt auf dem Bildschirm sichtbar, während die Aufforderung geöffnet ist. launcher.position platziert sie in einer der vier Ecken. launcher.offset legt ihren Abstand von den Rändern in Pixeln fest.

Was ein Klick auf die Glocke bewirkt, hängt von der Aufforderung ab. Ist prompt.enabled auf true gesetzt, schaltet der Klick sie um: Er öffnet sie oder schließt sie, wenn sie bereits geöffnet ist. Ist die Aufforderung deaktiviert, fragt der Klick den Browser direkt nach der Berechtigung, genau wie Pushwoosh.subscribe() — es sei denn, der Besucher hat Benachrichtigungen bereits blockiert; dann bewirkt der Klick nichts.

launcher.width und launcher.height legen die Größe der Glocke in Pixeln fest (16–200, jeweils standardmäßig 48). launcher.imageUrl zeichnet ein Bild anstelle der runden Glockenschaltfläche. launcher.background und launcher.iconColor legen die Füllfarbe und die Symbolfarbe der runden Schaltfläche fest. Ohne Angabe verwendet launcher.background standardmäßig die Akzentfarbe der Palette und launcher.iconColor eine Symbolfarbe, die für einen guten Kontrast dazu berechnet wird.

Texte und Farben

texts.blockedTitle, texts.blockedMessage und texts.closeText werden anstelle der Aufforderung angezeigt, sobald der Browser meldet, dass der Besucher Benachrichtigungen blockiert hat — texts.acceptText und texts.declineText erscheinen in diesem Zustand nie. texts.launcherLabel und texts.launcherBlockedLabel sind der Tooltip der Glocke in jedem Zustand. Jedes Textfeld akzeptiert bis zu 300 Zeichen.

colors.accent, colors.background, colors.text und colors.textSecondary akzeptieren einen Hex-Wert oder einen CSS-Farbnamen. Die Control-Panel-Formulare validieren jedes dieser Felder sowie launcher.background/launcher.iconColor auf diese Weise, bis zu 64 Zeichen. Das Init-Snippet akzeptiert für colors.* jede nicht leere Zeichenfolge, ohne Format oder Länge zu prüfen. Für launcher.background/launcher.iconColor prüft es ebenfalls kein Format, kürzt den Wert aber stillschweigend auf 64 Zeichen.

Hinweis

Eine Dark-Mode-Palette, launcher.zIndex und eine benutzerdefinierte fontFamily sind als zusätzliche, nur über Init-Parameter verfügbare Felder vorhanden. Sie sind in den unten beschriebenen Control-Panel-Formularen nicht verfügbar.

Verwaltung im Control Panel

Nur für über das Panel verwaltete Anwendungen

Die Control-Panel-Karten sind nur für Anwendungen verfügbar, deren Web-Plattform im Modus über das Panel verwaltet läuft (siehe Web Push SDK 3.0). Für eine per Snippet konfigurierte Anwendung setzen Sie subscriptionWidget wie oben gezeigt im Init-Snippet.

Gehen Sie bei einer über das Panel verwalteten Anwendung zu Settings → Configure platforms → Web. Die Aufforderung und die Glocke sind dort zwei getrennte Karten, jeweils mit eigenem On/Off-Badge und eigener Schaltfläche Configure:

• Subscription invitation bearbeitet die Aufforderung: Invitation (Layout, Position, Symbol), When to show (Trigger, Verzögerung, Capping), Texts und Colors.
• Subscription bell bearbeitet den Launcher: Position, Bild-URL, Breite/Höhe, Hintergrund- und Symbolfarbe sowie eigene Tooltip-Texte.

Die Schaltfläche Configure jeder Karte öffnet neben dem Formular eine Live-Vorschau. Die Vorschau zeigt nichts an, solange der Schalter der jeweiligen Karte ausgeschaltet ist. Sobald er eingeschaltet ist, wechselt ein Dropdown über der Vorschau zwischen der Aufforderung für unentschlossene Besucher und der Erklärung für blockierte Besucher. Das Speichern einer Karte ersetzt nur deren Hälfte der Panel-Kopie der Widget-Konfiguration — die Einstellungen der anderen Karte und das WebSDK-Init-Snippet auf Ihrer Website bleiben unberührt.

Solange eine Anwendung über das Panel verwaltet wird, überschreiben die in einer der beiden Karten gespeicherten Werte dieselben Schlüssel im Init-Snippet der Website.

3. Die Aufforderung aus Ihrem Code steuern

Sobald das Widget-Bundle geladen wurde, veröffentlicht es eine API unter Pushwoosh.moduleRegistry.subscriptionWidget:

Pushwoosh.moduleRegistry.subscriptionWidget.show();          // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.hide();          // Closes the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.toggle();        // Toggles the current state
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true);    // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.isVisible();     // Returns whether the prompt is open

show() und toggle() haben keine Wirkung, solange prompt.enabled auf false steht, und keine Wirkung für einen Besucher, der bereits abonniert hat. Das Öffnen der Aufforderung löst ein show-subscription-widget-Ereignis aus. Das Schließen löst hide-subscription-widget aus:

Pushwoosh.addEventHandler('show-subscription-widget', function() {
  console.log('Triggered event: show-subscription-widget');
});

Pushwoosh.addEventHandler('hide-subscription-widget', function() {
  console.log('Triggered event: hide-subscription-widget');
});

Migration von den älteren Widgets

Die Schaltfläche für Push-Abonnements, das benutzerdefinierte Abonnement-Popup und die Abonnement-Aufforderung funktionieren weiterhin wie auf ihren eigenen Seiten dokumentiert, solange subscriptionWidget.prompt.enabled und subscriptionWidget.launcher.enabled der Website beide nicht gesetzt oder false bleiben. Wird eines von beiden aktiviert, stoppt das Laden aller drei, sowohl bei einer per Snippet konfigurierten als auch bei einer über das Panel verwalteten Anwendung.

Vorsicht

Eine frühere Version des Widgets verwendete statt separater Schalter prompt.enabled/launcher.enabled einen einzigen subscriptionWidget.enable-Schalter auf oberster Ebene. Diese Form wird nicht mehr ausgewertet. Ein Snippet, das weiterhin nur enable: true setzt, schaltet das Widget jetzt vollständig aus: Weder die Aufforderung noch die Glocke zeigt etwas an, das WebSDK gibt in der Konsole einen Hinweis mit den beiden stattdessen zu setzenden Feldern aus, und die drei älteren Widgets werden geladen, als wäre subscriptionWidget nie gesetzt worden. Auch das Umstellen einer über das Panel verwalteten Anwendung auf das neue Widget übernimmt nicht die Einstellungen des alten Widgets, das es ersetzt — jede Karte startet mit ihren eigenen Standardwerten.