Skip to content

Web Push


This part of the documentation will give you an introduction into WebPush and how to use it.

What you can do with Web Push


Web Push allows you to send notifications to the users of your Website. It currently works with the following browsers:

  • Chrome

  • Firefox

  • Opera

For example with Firefox on Mac OS, it looks the following:

WP demo firefox

Getting Started with Web Push


To get Web Push running in your system, you need to have the following:

  1. Registered your Website in the Cloud Management Service

  2. Access to the HTML of your Website to integrate the Web Push code

  3. Created Web Push Messages and linked them to the registered Website

In the following Sections, each of these points will be discussed in detail.

Registering your Website


In order to get started with Web Push, you must first register your Website in the Cloud Management 2.0.

Overview of Websites

Please navigate to Settings / Websites. Here, you have an overview over all previously registered Websites.

WP website overview

In the column on the very left (1), you can see the name of the Website. In column (2), you see valid domains for this website. What a valid domain is and what it represents is described in more detail when we talk about creating Websites. The next two columns (3) and (4) represent the website credentials. These are necessary for registering your website with our backend. These are described in more detail in the …​ The last column (5) displays several actions you can perform with Websites: You can view, edit, or delete them (from left to right).

Lastly, there is the button CREATE (6). Click on it to create your first Website.

Creating Websites

Creating a new Website is very simple and only requires two steps.

(1) Choose a website name

Important

This field is required.

Tip

It is not required to have a unique name per website. However, it makes it simpler to identify websites if you use unique names.

To later be able to identify your website, you must choose a name. You can give a website any name that you like, but it must be less than 255 characters. With the number in the lower right of the input field, you can always check if you match this requirement.

(2) Restrict the website to certain domains

Warning

When using a website in production, you should always limit the number of domains to only the ones that you actually use. As the website credentials will be visible to everyone who reads the source code of your website, this is a way of ensuring that your credentials are not used with an unwanted website.

With this field, you can limit the usage of these website credentials to certain domains. A domain is the address of your website. For example, when you have a shoe shop at www.myshoeshop.com, this is also your domain. By default, any domain is permitted.

Domains must be of any of the following formats:

(a) domain.com
(b) subdomain.domain.com
(c) *.domain.com
(d) *

When you enter a value that matches this format, the + button (3) the right will turn red. With clicking on it, you add this domain to the list of valid domains.
Let us take a closer look at the examples:

  1. This is very restrictive. It allows use of the website credentials only via http://domain.com. Also access via http://www.domain.com is not permitted in this case.

  2. With this pattern, you can selectively add subdomains that should be able to use the website credentials. If you use (a) and add www.domain.com (with www as the subdomain), the credentials can be used when accessing the website via both http://domain.com and http://www.domain.com, but no other URL. You can also add further subdomains, e.g. shop.domain.com in this manner for access via shop.domain.com.

  3. This is the recommended way of restricting your website credentials. With this option, you can use any subdomain (i.e, http://domain.com, http://www.domain.com, http://shop.domain.com) without having to add a single entry for each.

  4. This leads to the same result as an empty list. All domains can use these website credentials. It does not matter what other fields contain.

Warning

Be careful when using * as a valid domain. This overwrites all other limitations.

WP create website

Example

For this example, you own a shop that sells shoes and its name is ShoeShop and you its website is at http://www.shopshoes.com. You can access the domain also via http://shopshoes.com and http://shop.shopshoes.com.

Therefore, you create a Website with the name Shoe Shop. Since you want to register all users that enter the website through any of the links, you can add one domain entry for each of the URLs:

shopshoes.com
www.shopshoes.com
shop.shopshoes.com

However, this is a bit verbose. Also, you do not have any other subdomains and nobody else is using the same domain. With the - (4) next to the domains, you delete theese domains. Therefore, you change the valid domains to

*.shopshoes.com

Afterwards, you click on Create (5) to create the website.

Website Info

After you have created a website, or when clicking on the website name, you can see the website info. Here, you can see the name (1) and the valid domains you just added (2).

Furthermore, you can see a Website Id (3) and a Website Secret (4). These are autogenerated upon creation and necessary for identifying your website later on with our backend.

Tip

The Website Id has the format <10 random characters>_<the first two words of the name>. Therefore, if you choose the name of the website wisely, you can easily see to which website the Website Id belongs to. However, they are only generated upon creation of the website; therefore, they do not adjust to a new name.

At (5) you see a field "Web-Push Integration Into Website". This is by default collapsed. When you click on the arrow to the right, the field expands (as seen in the image). Here, you can see a small code snippet that can help you when Integrating Web Push into your Website.

With the buttons Delete (6) you can delete this Website. There will pop up a dialog that asks you to confirm this action. With Edit (7) you can edit the name and the valid domains of this Website.

WP website info

Editing Websites

When you edit a website, there the same to consider as for Creating Websites.

Integrating the Web Push Code into your Website


In this section we will integrate the web push functionality into your website. As there is a simple and a more complex approach, we will cover both here. The simple approach goes very well in hand with the code snippet in the Website Info.

Important

To use web push, your website must use https:// by default. For testing localhost is sufficient.

Simple Approach

In the Website Info you saw a small code snippet that is supposed to help you with the integration. To do this, you first need to download two JavaScript files for webpush Here. These you now need to place in the same folder as your HTML file (e.g. index.html) that you want to integrate webpush in. Afterwards, copy and paste the code and place at the end of the html file, just before the </body> tag. Now, when requesting the website, you should be asked whether or not you want to allow web push.
Viola! It worked.

WP show notifications

Warning

You need to have the website running in a server. Simply opening the HTML file in your web browser does not work. NOTE: If you have multiple pages, you need to repeat this for every html file.

Folder structure for the simple approach:

/website
| -- index.html
| -- bpl-serviceworker.min.js
| -- bitplaces-webpush.min.js

Example code for index.html:

<html>
    <head>
        <title>Example for Bitplaces Web Push</title>
    </head>
    <body>
        <h1>This is a Webpush Example</h1>
        When loading the page for the first time, you should be asked
        whether you want to receive web push notifications.

        <script src="bitplaces-webpush.min.js"></script> 
        <script type="text/javascript">
            var BitplacesOptions = {
                clientId: "kfy5JYyv0s_shoe_shop", 
                clientSecret: "PI6Ioj99fZ" 
            };
            BitplacesSDK.initialize(BitplacesOptions); 
        </script>
   </body>
</html>
  • The place where you insert the code snippet from the website info

  • This needs to be the content of the Website Id in the Website Info.

  • This needs to be the content of the Website Secret in the Website Info.

  • This triggers the Web Push Registration Process.

Advanced Approach

Of course, this approach is not very well suited for complex websites which span over multiple files or use a different folder structure. As for the simple approach, you first need to download two JavaScript files for webpush Here.

Let us say that your folder structure here is as follows:

/website
| -- assets
|    |-- js
| -- index.html

Therefore, after you placed the downloaded javascript files in /websites/assets/js, the tree looks the following:

/website
|-- assets
|    `-- js
|        |-- bpl-serviceworker.min.js
|        `-- bitplaces-webpush.min.js
|-- index.html

Also, you do not want to automatically ask the user for permission. Instead, he should activate it via a button. The code in index.html then looks the following:

<html>
    <head>
        <title>Advanced Web Push demo</title>
    </head>
    <body>
        <h1>This is a Webpush Example</h1>
        Please click on this button to activate WebPush:
        <button click="activateWebPush();">Activate Web Push</button>

        <script src="assets/js/bitplaces-webpush.min.js"></script> 
        <script type="text/javascript">
            var BitplacesOptions = {
                clientId: "kfy5JYyv0s_shoe_shop",
                clientSecret: "PI6Ioj99fZ",
                serviceWorkerPath: "assets/js/bpl-serviceworker.min.js"  
            };
            function activateWebPush() { 
                BitplacesSDK.initialize(BitplacesOptions);
            }
        </script>
   </body>
</html>
  • You need to make sure to adjust the path to the javascript file. This file needs to be loaded before the BitplacesSDK.initialize(BitplacesOptions); is executed.

  • You need to pass the adjusted path to the service worker.

  • You can put BitplacesSDK.initialize(BitplacesOptions); any place you want. In this case, inside a function call. Only after this is executed, the registration takes place.

Tip

If you want to rename the javascript files, feel free to do so! However, you need to make sure to adjust the paths in (1) and (2) accordingly.

Documentation

Files

There are two files necessary to integrate Web Push.

  1. bitplaces-webpush.min.js - This includes the logic for registering the users with our api services. It takes care of asking users whether they want to allow web push notifications.

  2. bpl-serviceworker.min.js - This is an important file as it takes care of displaying the push notifications after the users' browser has received them. You need to make sure that the ServiceWorker registration was successful. You can read more about Service Workers here: Service Workers: an Introduction

BitplacesSDK

The bitplaces-webpush.min.js offers a variable BitplacesSDK, which can be used to register a user with our Web Push Services.

BitplacesSDK.initialize
BitplacesSDK.initialize( options );

Triggers the Web Push registration process with the given options, i.e. registering the user with our backend services and asking him whether he wants to enable web push notifications for this website. Needs to be called if a user should receive web push notifications.

Parameter options

var options = {
    clientId: "",
    clientSecret: "",
    serviceWorkerPath: "./bpl-serviceworker.min.js",
    enableWebPush: true
};
Fields for the parameter options
Field Required? Default Value Description

clientId

YES

Needs to be the Website Id that is generated when creating a website. This is used for linking your website to the website registration in the backend.

clientSecret

YES

Needs to be the Website Secret that is generated when creating a website. This is used for linking your website to the website registration in the backend.

serviceWorkerPath

NO

./bpl-serviceworker.min.js

Needs to be the path to the service worker file. By default, it looks for it in the same folder.

enableWebPush

NO

true

If set to to true, WebPush is activated. If false, registration will not take place

Web Push Messages


After you have registered your website and integrated the necessary code into your website, we can finally get to creating and sending web push messages.

Message Overview

To get to the overview of Web Push Messages, you should navigate to Web Push Messages in the menu. Here you first see a list of all existing Web Push Messages. In the column on the very left (1), you can see the title of the web push message. The next column (2) shows the content of this web push message, i.e. the body of it. The url column (3) shows the url that is opened when the user clicks on the web push notification. To the very right (4) you have buttons to view, edit, delete the web push message.

To create a new Web Push Message, click on the Create button on the top right (5).

WP message overview

Creating a Web Push Message

After clicking on the Create button, you can create a new web push message. For this, you first enter a title for this message (1). This is used as the most prominent text in the notification, as you can see in the preview on the right (6). In the Push Content field (2), you can enter more text that is displayed beneath the title. These two fields are required. Optionally, you can also specify an icon to be displayed in the notification (3). Currently, this needs to be a URL to the icon. Also optional is a url that is opened when clicking on the notification (4).

Note

Make sure that the icon is accessible on the open web because otherwise the user might not be able to see it.

Lastly, you need to specify which websites this web push message should be attached to (5). In our example, we only want to send it to users of our shoe shop, therefore we select the website with the Name "Shoe Shop".

After we have done all this, we can create the message (7).

WP create message

Web Push Message Info

After you created a new web push message, you can view it in the "Web Push Message Info" view. This view is also opened when you click on a message in the Web Push Mesage Overview.

Here, you can see all information that you specified when creating the message. You have the title (1), the push content (2), the url that is opened when clicking on it (3) and the websites, to which it is assigned (4). The notification icon url is not directly visible, but you can see the image behind it (5). You also have a preview for what the message will look like (6).

With a click on the Delete (7) button, you can delete this web push message. You will be asked to confirm this action. With the Edit (8) button you can edit the web push message.

Lastly, you have the option to broadcast the message to all website users (9).

WP message info

Editing a Web Push Message

Editing a Web Push Message is very similar to creating a Web Push message.

Broadcasting a Web Push Message

After clicking on Broadcast in the Web Push Message Info, you will be asked to confirm this action. Afterwards the message should have been successfully sent and you should receive your first Web Push Notification, if you followed all previous steps!

WP broadcast