# Custom subscription Popup

**Custom Subscription Popup** is a pop-up window displayed on the web page and suggesting users to subscribe to web push notifications. It’s implemented with [Pushwoosh WebSDK](/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration) and allows to overcome the browser restrictions on a native subscription prompts displaying. A native subscription popup can be shown to a particular user only twice. If a user doesn’t allow push notifications and closes the native subscription popup two times in a row, it won’t be shown again and push notifications are considered blocked. A **Custom Subscription Popup** in its turn can be displayed as many times as needed unless a user subscribes to or blocks push notifications explicitly.

A **Custom Subscription Popup** can contain any text explaining the advantages of subscription to push notifications and two customizable buttons — a one for an "Ask later" option and a one for "Subscribe." 

Once a user presses a "Subscribe" button, a native subscription popup appears.

When a user presses an "Ask Later" button or simply closes the window, the Custom Subscription Popup will appear again in a specified time (by default, in a week after; a delay to retry can be customized via the "retryOffset" parameter).

## Implementation

To enable and customize a **Custom Subscription Popup**, use the following script while initializing [Pushwoosh WebSDK](/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration):

```javascript title="Example"
Pushwoosh.push('init', {
    // . . .,
    subscribePopup: {
        enable: true,                      // (boolean) popup activation
        text: 'Text on popup',             // (string) a text to display on the popup
        confirmSubscriptionButtonText: 'Subscribe', // (string) custom text for the “Subscribe” button

        manualToggle: false,               // (boolean) manual control for showing the popup
        delay: 60,                         // (integer) a delay between the page loading and popup appearance
        retryOffset: 604800,               // (integer) an offset in seconds to display the popup again

        iconUrl: 'https://...',            // (string) custom icon URL
        iconAlt: 'Descriptive text for your icon', // (string) ALT text for the icon
        overlay: false,                    // (boolean) enables page overlaying when popup is displayed
        position: 'top',                   // (string) position on the page. Possible values: ’top' | 'center' | 'bottom’
        mobileViewMargin: '10px',          // (string) margin for mobile view

        bgColor: '#fff',                   // (string) popup’s background color
        borderColor: 'transparent',        // (string) popup’s border color
        boxShadow: '0 3px 6px rgba(0,0,0,0.16)', // (string) popup’s shadow

        textColor: '#000',                 // (string) popup’s text color
        textSize: 'inherit',               // (string) popup’s text size
        textWeight: 'normal',              // (string) popup’s text weight
        fontFamily: 'inherit',             // (string) popup’s text font

        subscribeBtnBgColor: '#4285f4',         // (string) “Subscribe” button’s background color
        subscribeBtnTextColor: '#fff',          // (string) “Subscribe” button text’s color
        subscribeBtnTextWeight: 'bold',         // (string) “Subscribe” button text weight
        subscribeBtnBorderColor: 'transparent', // (string) “Subscribe” button border color
        subscribeBtnBorderRadius: '4px',        // (string) “Subscribe” button border radius

        askLaterButtonText: 'Not now',          // (string) custom text for the “Ask later” button
        askLaterBtnBgColor: 'transparent',      // (string) “Ask later” button’s background color
        askLaterBtnTextColor: '#000',           // (string) “Ask later” button text’s color
        askLaterBtnBorderColor: 'transparent',  // (string) “Ask later” button border color
        askLaterBtnBorderRadius: '4px',         // (string) “Ask later” button border radius
        askLaterBtnTextWeight: 'normal',        // (string) “Ask later” button text weight

        theme: 'material',               // (string) popup theme, possible values: 'material' | 'topbar'
        viewport: 'desktop'              // (string) target viewport, possible values: 'desktop' | 'mobile'
    }
});
```


### Accessing the Custom Subscription Popup Instance

The **Custom Subscription Popup** instance is available via `Pushwoosh.moduleRegistry.subscribePopup`.

**Note:** This instance becomes accessible only after the `subscribe-popup-ready` event is triggered. However, it will **not be available if the user is already subscribed to push notifications.**

The instance provides a `toggle()` method that allows you to manually show or hide the popup:

```javascript
// Show or hide the Custom Subscription Popup manually
Pushwoosh.moduleRegistry.subscribePopup.toggle(); // Toggles visibility
Pushwoosh.moduleRegistry.subscribePopup.toggle(true); // Shows the popup
Pushwoosh.moduleRegistry.subscribePopup.toggle(false); // Hides the popup
```

This allows for more control over the popup’s behavior directly from your code.

## Themes

By default, the Subscription Popup uses a **'material' theme** and overlays some part of a screen when shown, thus hiding some content from a website visitor.

<img src="/web-push-notifications-custom-subscription-popup-1.webp" alt="'Material' theme"/>

To avoid hiding valuable content by the Subscription Popup, use the **'topbar' theme** so that the popup is shown as a narrow bar on the top of the screen.

<img src="/web-push-notifications-custom-subscription-popup-2.webp" alt="'Topbar' theme"/>

## Custom Subscription Popup Events

The following events are available for tracking interactions with the **Custom Subscription Popup**:

```javascript
// Executed when the custom subscription popup is loaded and ready to be shown
// Note: This event will NOT trigger if the user is already subscribed to push notifications.
Pushwoosh.addEventHandler('subscribe-popup-ready', function() {
  console.log("Triggered event: subscribe-popup-ready");
});

// Executed when the custom subscription popup is shown
Pushwoosh.addEventHandler('subscribe-popup-show', function() {
  console.log("Triggered event: subscribe-popup-show");
});

// Executed when a user clicks on the 'Subscribe' button in the pop-up window
Pushwoosh.addEventHandler('subscribe-popup-accept', function() {
  console.log("Triggered event: subscribe-popup-accept");
});

// Executed when a user clicks on the 'Ask later' button in the pop-up window
Pushwoosh.addEventHandler('subscribe-popup-decline', function() {
  console.log("Triggered event: subscribe-popup-decline");
});

// Executed when the popup hides
Pushwoosh.addEventHandler('subscribe-popup-hide', function() {
  console.log("Triggered event: subscribe-popup-hide");
});
```