Subscription widget

The Subscription widget is a prompt and a launcher bell that invite website visitors to subscribe to push notifications, configured together as subscriptionWidget but switched on independently: the prompt alone, the bell alone, or both at once. Turning on either one replaces the push subscription button, the Custom Subscription Popup, and the Subscription Prompt — while at least one part is on, none of those three older widgets load on the page.

A visitor who has not decided yet sees the prompt’s ask. A visitor who already blocked notifications sees an explanation of how to unblock them instead.

Prerequisites

Make sure you’ve implemented Pushwoosh Web SDK 3.0 on your website. To do so, follow our integration guide.

1. Turn the prompt and the bell on

Add the subscriptionWidget parameter to the WebSDK initialization and set prompt.enabled and/or launcher.enabled to true:

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

No single top-level switch

A top-level subscriptionWidget.enable is not read. Setting only that field turns nothing on. See Migrating from the older widgets below.

Every field below is optional. An omitted one falls back to its default. In the init snippet, a number outside its range is silently clamped to the nearest bound and an invalid enum value silently falls back to its default, with no console warning. The Control Panel forms described further down validate each field and refuse to save an invalid one.

2. Configure the prompt and the bell

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 and position

prompt.layout sets the shape of the prompt:

• card — a compact card anchored to an edge or a corner. prompt.position accepts top, bottom, top-left, top-right, bottom-left, or bottom-right.
• bar — a bar spanning the full width of the page. prompt.position accepts top or bottom only.
• modal — a window centered on the page. prompt.position is always center.

Check the list above for the layout you set before picking a position. In the init snippet, a position the current layout doesn’t support is silently replaced with the layout’s default. The Control Panel form rejects the combination instead.

When to show the prompt

display.trigger controls what opens the prompt:

• auto — opens automatically display.delay seconds after the page loads, then again every display.cappingInterval hours if the visitor hasn’t decided, up to display.cappingCount times total (0 means no limit).
• launcher — never opens on a timer. Set this alongside launcher.enabled: true so a bell click can open it. The manual API still opens it regardless of this setting or of whether the bell is on.
• manual — opens only through Pushwoosh.moduleRegistry.subscriptionWidget, described below.

display.delay, display.cappingCount, and display.cappingInterval only apply to the auto trigger.

The launcher bell

launcher.enabled shows a floating bell to a visitor who can still act on the ask (not yet subscribed, or blocked), independent of the prompt and of display.trigger. The bell stays on screen while the prompt is open. launcher.position places it in one of the four corners. launcher.offset sets its distance from the edges, in pixels.

A bell click’s effect depends on the prompt. If prompt.enabled is true, the click toggles it: opens it, or closes it if it’s already open. If the prompt is off, the click asks the browser for permission directly, the same as Pushwoosh.subscribe() — unless the visitor already blocked notifications, when the click does nothing.

launcher.width and launcher.height set the bell’s size in pixels (16–200, default 48 each). launcher.imageUrl draws a picture instead of the round bell button. launcher.background and launcher.iconColor set the round button’s fill and glyph color. Left unset, launcher.background defaults to the palette’s accent color, and launcher.iconColor to a glyph color computed for contrast against it.

Texts and colors

texts.blockedTitle, texts.blockedMessage, and texts.closeText are shown instead of the ask once the browser reports the visitor blocked notifications — texts.acceptText and texts.declineText never appear in that state. texts.launcherLabel and texts.launcherBlockedLabel are the bell’s tooltip in each state. Every text field accepts up to 300 characters.

colors.accent, colors.background, colors.text, and colors.textSecondary take a hex value or a CSS color name. The Control Panel forms validate each of these, and launcher.background/launcher.iconColor, this way, up to 64 characters. The init snippet accepts any non-empty string for colors.* with no format or length check. For launcher.background/launcher.iconColor it checks neither format, but silently cuts the value to 64 characters.

Note

A dark-mode palette, launcher.zIndex, and a custom fontFamily are available as additional init-param-only fields. They aren’t exposed in the Control Panel forms described below.

Managing it in the Control Panel

Panel-managed applications only

The Control Panel cards are available only for applications with the Web platform in panel-managed mode (see Web Push SDK 3.0). For a snippet-configured application, set subscriptionWidget in the init snippet as shown above.

On a panel-managed application, go to Settings → Configure platforms → Web. The prompt and the bell are two separate cards there, each with its own On/Off badge and Configure button:

• Subscription invitation edits the prompt: Invitation (layout, position, icon), When to show (trigger, delay, capping), Texts, and Colors.
• Subscription bell edits the launcher: position, image URL, width/height, background and icon color, and its own tooltip texts.

Each card’s Configure button opens a live preview next to the form. The preview draws nothing while that card’s own switch is off. Once it’s on, a dropdown above the preview switches between the undecided-visitor ask and the blocked-visitor explanation. Saving a card replaces only its half of the panel’s copy of the widget config — the other card’s settings, and the WebSDK init snippet on your site, are untouched.

While an application is panel-managed, values saved in either card override the same keys in the site’s init snippet.

3. Control the prompt from your code

Once the widget bundle has loaded, it publishes an API at 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() and toggle() have no effect while prompt.enabled is false, and no effect for a visitor who already subscribed. Opening the prompt dispatches a show-subscription-widget event. Closing it dispatches hide-subscription-widget:

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');
});

Migrating from the older widgets

The push subscription button, the Custom Subscription Popup, and the Subscription Prompt keep working as documented on their own pages as long as the site’s subscriptionWidget.prompt.enabled and subscriptionWidget.launcher.enabled both stay unset or false. Turning either one on stops all three from loading, on both a snippet-configured and a panel-managed application.

Caution

An earlier version of the widget used a single top-level subscriptionWidget.enable switch instead of separate prompt.enabled/launcher.enabled. That shape is no longer read. A snippet still setting only enable: true now turns the widget off entirely: neither the prompt nor the bell draws anything, the WebSDK logs a console hint naming the two fields to set instead, and the three older widgets load as if subscriptionWidget were never set. Switching a panel-managed application to the new widget does not carry over the settings of whichever old widget it replaces either — each card starts from its own defaults.