The WonderPush Developer Hub

Welcome to the WonderPush developer hub. You'll find comprehensive guides and documentation to help you start working with WonderPush as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Subscription Prompts

SETUP - Ready-made user interfaces to help you subscribe users to push notifications

Getting users to subscribe to push notifications is an important aspect of setting up push notifications. In this document we present ready-made user interfaces we've created to help you do just that with minimal effort.

These user interfaces are:

While the subscription dialog and the bell widget can be completely configured from your dashboard, the switch require a little bit of code.

Custom button click

The dialog, the bell and our other ready-made user interfaces have been tested and improved over time and their conversion is usually good. Of course, it is always possible to trigger subscription via a simple click of a button like this:

<a href="#" onclick="WonderPush.subscribeToNotifications(event); return false;">Click me to subscribe</a>

Subscription bell widget

The subscription bell widget is the easiest way to subscribe users. Users can use the subscription bell to:

  • Subscribe to push notifications
  • Opt out of push notifications
  • Download personal data
  • Clear personal data

The subscription bell sits at the bottom left or right corner of the page and looks like this:

Basic setup

You can configure it directly from your dashboard: go to Settings / Website and make sure the subscription bell is active:

General settings

To customize the subscription bell, click the Customize link.

Language

The subscription bell natively supports English and French and will switch automatically to the most appropriate based on the browser language. To force to a particular language, choose one here.

Position

By default the bell is displayed on the lower-left corner of the screen. Use this dropdown menu to set the position on the lower-right corner.

Color

Controls the color of the subscription bell widget.

Bell icon

Use this to change the bell icon. The file you provide will be used as a mask so it must be transparent.

CSS z-index

Controls the “altitude” of the bell widget on the page. Raise this value if something on the page is displayed on top of the bell.

Show unread-like badge

When this is active, the bell will display an unread-like count until the user places his mouse over the bell.

Texts

Use this section to customize the texts displayed by the bell widget.

Unsubscription dialog

The bell widget allows users to unsubscribe without losing the push permission. This allows them to sign-up again easily later. If you do not wish to let the bell unsubscribe users, check “Hide the bell to subscribed users”.

Other settings in this section let you customize the texts that appear in the unsubscription dialog.

Privacy settings

The bell lets users download or clear their WonderPush data.

If you do not wish to display these privacy settings, check “Hide privacy settings”.

Internationalization

The bell natively supports English and French. To support another language, you can use the above settings: they let you customize all the texts used by the bell widget.

You can also use the subscription bell init options to support more than one extra language.

Native prompt

This native dialog is the most straightforward way to let users subscribe. To setup the native dialog, make sure it is active in Settings / Website:

The native prompt cannot be customized but you can choose when it appears by clicking on Customize and choosing a schedule:

HTML dialog


The HTML dialog is an efficient way to subscribe users. It is configured directly from your dashboard.

The subscription dialog looks like this:

To activate the HTML dialog, go to Settings / Website and make sure the HTML dialog is active:

To customize the HTML dialog, click on the Customize link.

Showing the dialog automatically

The dialog shows automatically based on the criteria you specify in your dashboard:

Customizing the dialog content

You can customize the textual content of the dialog:

Customizing the dialog look & feel with CSS

You can change the visual aspect of the HTML dialog with CSS. The top-level element of the HTML dialog has a CSS class of wp-optin-dialog-container. You can add CSS rules to your page, or use the style attribute of the HTML dialog options.

Here's an example of how to set the dialog's background to plain white:

<style>
.wp-optin-dialog-container {
  background-image: none;
  background-color: white;
}
</style>

Advanced settings

CSS z-index

Controls the “altitude” of the HTML dialog on the page. Raise this value if something on the page is displayed on top of the bell.

Scroll behavior

Controls whether the dialog floats over the page and stays always visible or scrolls with the page content.

Position

Controls where the dialog is displayed.

Distance from the edge

Allows you to specify the distance between the top (or bottom) edge of the screen and the dialog.

📘

How to configurate HTML dialog to display one time in a hour or day

Use the following subscription dialog init options :

  • closeSnooze
    How long to force to wait before presenting the dialog again, if the user clicks the close button.
  • negativeSnooze
    How long to force to wait before presenting the dialog again, if the user clicks the negative button.

Internationalization

The dialog natively supports English only. To support another language, you can use the above settings: they let you customize all the texts used by the HTML dialog.

You can also use the subscription dialog init options to support more than one extra language.

Cross-domain subscription popup

You might want to subscribe users from a domain that is not your main notification domain. For instance, you might want to subscribe users from shop.mydomain.com when your notification domain is www.mydomain.com, or you're using a .by.wonderpush.com domain.

When this happens, WonderPush will open the cross-domain subscription pop, which you can control directly from your dashboard.

To enable cross-domain subscription, make sure Cross-domain is active in the Settings / Website section:

📘

If you deactivate Cross-domain, users won't be able to subscribe from any other domain than your notification domain. Projects using a .by.wonderpush.com notification domain cannot deactivate cross-domain.

Settings

The cross-domain settings let you control all the texts of the cross-domain popup window:

Subscription switch

The subscription switch is a very simple widget that can be placed anywhere on the page and allows users to subscribe to notifications and unsubscribe.

The subscription switch looks like this:

Basic setup

There's two ways of setting up the switch.

HTML, letting the Website SDK turn your element into a subscription switch at page load:

<div id="wonderpush-subscription-switch"
        data-sentence="Subscribe to notifications: "></div>

Or Javascript using the showSubscriptionSwitch function:

WonderPush.push(function() {
  WonderPush.showSubscriptionSwitch(
    document.getElementById('ID_OF_DESIRED_PARENT_NODE'),
    {
      sentence: "Subscribe to notifications: "
    }
  );
});

Customizing

Both methods allow the same customization options, described in the Subscription Switch Options section of the Website SDK documentation.

For example, to change the switch color, in HTML:

<div id="wonderpush-subscription-switch"
        data-colorOn="#ffcc33"></div>

In Javascript:

WonderPush.push(function() {
  WonderPush.showSubscriptionSwitch(
    document.getElementById('ID_OF_DESIRED_PARENT_NODE'),
    {
      colorOn: "#ffcc33"
    }
  );
});

Tag switch

Tag switches let users subscribe and tag themselves at the same time. There's a complete guide dedicated to their use.

Updated 7 months ago


Subscription Prompts


SETUP - Ready-made user interfaces to help you subscribe users to push notifications

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.