WonderPush JavaScript SDK

Index

WonderPush JavaScript SDK Guide

Web Push notifications allow your users to opt-in to timely updates from your site and allow you to effectively re-engage them with customized, engaging content, even when your site is not being browsed.

This quick start guide shows you how to get push messaging up and running on your website within three minutes.

This SDK supports HTTP, HTTPS, and multiple subdomains websites! It currently works with Chrome 42+ and will soon support Safari, and Firefox.

Register your website in WonderPush

Log in or sign up on WonderPush.

Create your application. Make sure to check Web under the Platforms section.

Grab your webkey under the Settings / Keys menu.

Edit the required configuration for the Web platform right below.

Setup the SDK

Load the SDK

Copy/paste the following script before the closing <body> tag:

<script>
  (function(w, d, s, id, n){
    w[n] = w[n] || {q: [],
      init: function(o) {w[n].initOpts = o;},
      ready: function(c) {w[n].q.push(c);}};
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) {return;}
    js = d.createElement(s); js.id = id;
    js.src = "https://cdn.by.wonderpush.com/sdk/1.1/wonderpush-loader.min.js";
    fjs.parentNode.insertBefore(js, fjs);
  }(window, document, 'script', 'wonderpush-jssdk-loader', 'WonderPush'));
</script>

Initialize the SDK

You can call the WonderPush.init function whenever you want, there is no need to call it right away. For instance you can wait to retrieve the userId. Note however that the previous code block must appear before in the page.

For an easy initialization, use the following right after the previous codeblock (it can be within the same <script> tag too):

<script>
  WonderPush.init({
    webKey: '[YOUR_WEBKEY]', // Copy/paste the webkey found in your dashboard under the `Settings / Keys` menu
    userId: null,            // optional, default value: null
    // The following options will be overriden once you've updated your configuration in the dashboard
    customDomain: '[YOUR ALIAS]', // Please read the advice
    // The following options can be provided using your dashboard, or overridden here
    notificationDefaultUrl: '[YOUR_DEFAULT_NOTIFICATION_URL]',
    applicationName: '[YOUR_WEBSITE_NAME]',              // optional
    notificationIcon: '[YOUR_DEFAULT_NOTIFICATION_ICON]' // optional
  });
</script>

Replace:

  • [YOUR_WEBKEY] with the webkey you will find in your dashboard under the Settings / Keys menu.

  • [YOUR_ALIAS] with a simple alias uniquely representing your website, with no space, dots or uppercase letters.
    Example: "yourwebsite".
    This is an important option. The notifications will be shown are originating from https://yourwebsite.by.wonderpush.com and the notification permission and push subscriptions are tied to this domain.
    If you wish to use your very own domain here, contact us for instructions. Meanwhile, you can test your integration using a simple alias like shown above.

  • [YOUR_DEFAULT_NOTIFICATION_URL] with the proper URL to your website landing page.
    Example: "http://www.yourwebsite.com/".
    This URL will be used if none is already present on the clicked notification.

  • [YOUR_WEBSITE_NAME] with the display name of your website.
    Example: "My Website".
    Use proper casing for best results.

  • [YOUR_DEFAULT_NOTIFICATION_ICON] with the URL to an image representing your website, preferably using HTTPS.
    Example: "https://www.yourwebsite.com/img/notification-icon.png".
    The display of this image changes from browser to browser and platform to platform, but a square image around 100 pixels wide will do.
    This image is also shown during the registration process.

When the SDK will be initialized, the WonderPush.ready function will return the WonderPushSDK object to you. You can grab the SDK once and for all, or call this function whenever needed. Just be aware that the initialization is an asynchronous process.

Register to notifications

We recommend that you use a subscription switch, like on our website. This way, you register the user only when he decides. You just have to find an appropriate place in your page and use the code from the following page:

Push notification subscription switch sample code

However, you can also opt to register the user for push notifications either right away, or after some pages have been visited, or at any time. Using a non intrusive information message before asking the user for the notification permission yields better results than asking without prior notice.

WonderPush.ready(function(WonderPushSDK){
  if (WonderPushSDK.isNativePushNotificationSupported()) {
    // For best results, test if:
    // - user engagement is sufficient
    // - user is willing to accept notifications,
    //   using a non intrusive information message
    // or use a subscription switch instead:
    //   https://gist.github.com/ofavre/33b989284fc75997d65f
    WonderPushSDK.askNativePushNotificationPermission();
  }
});

Test push notifications

Go to your website, and register to push notifications.

Head to your dashboard.

You should now see yourself listed as pushable in the All users segment, accessible through Audience in the menu.

If not, please go back and check your steps, especially the customDomain value.

Go to Notification and click the Create notification button. Write a small message, target all users, and keep the default scheduling. Back in the notifications list, click the FIRE button in front of your new notification.

Allow a few seconds, and voila! You should have received your first push notification.

Finalize configuration

Once happy of the initialization options, put them in the dashboard.

Go in the Settings / Keys menu of your dashboard.

Edit the required configuration for the Web platform right below.

Please fill the Custom domain field using the value of the customDomain key, and remove it from the initialization options.

You can continue with the following fields, if you wish. This way you can omit them from the initialization options and update their value from the dashboard with having to update your website, while still being able to override them from the code.

Fill the Website name field using the value of the applicationName key.

Fill the Notification defaul URL field using the value of the notificationDefaultUrl key.

Fill the Notification icon field using the value of the notificationIcon key.

Click the Update keys button.

Note: The configuration is cached, so please allow 24 hours before expecting updates to be taken into account.
The first setup, however, should be available right away!

Developer note: The configuration is also cached in the browser in the Local Storage, you can try to update things (like customDomain) there, to go forward faster. If you update the customDomain, refresh the page, and update the configuration cached in the Local Storage of the new domain too.

Using the SDK

Adding tags and custom properties to the installation

You can then add tags to an installation using the WonderPushSDK#putInstallationCustomProperties function like this:

WonderPush.ready(function(WonderPushSDK){
  WonderPushSDK.putInstallationCustomProperties(properties);
  // For example:
  //   var properties = { string_subscribedCategories: ["world", "economics"] };
  // Note that the prefix is mandatory for indexation.
  // Consult the WonderPush documentation for more information.
});

If you even need to read the current custom properties of an installation, use the WonderPushSDK#getInstallation function like this:

WonderPush.ready(function(WonderPushSDK){
  WonderPushSDK.getInstallation().then(function(installation) {
    var custom = installation.custom || {};
    // For example:
    //   var subscribedCategories = custom.string_subscribedCategories || [];
  });
});

Tracking events

If your current plan allow it, you can then track an event using the WonderPushSDK#trackEvent function like this:

WonderPush.ready(function(WonderPushSDK){
  WonderPushSDK.trackEvent(type, parameters);
  // For example:
  //   var type = "newsRead";
  //   var properties = { string_categories: ["technologies", "economics"] };
  // Note that the prefix is mandatory for indexation.
  // Consult the WonderPush documentation for more information.
});

As opposed to an installation properties (like a tag), an event is set in time and expires after 3 months. You can for instance query against an event that occured within the last week. For example: with events, you can target users that have read world news 3 days ago but have not subscribed to this category.

Demo application

You can test it live here.

API Reference

Take a look at the methods exposed by the WonderPush and WonderPushSDK classes.