Cloud Management 2.0 Guide

 

 

1. Bitplaces Cloud Management

The Bitplaces cloud management is divided into 5 areas:

  • Map
  • Bitplaces
  • Messages
  • Analytics
  • Settings

1.1. Login

CM login

1.2. Language selection

CM language selection

After logging in, the so-called “Map View” appears with a map included existing Bitplaces.
The user can change the main language of the platform in the top menu bar.

1.3. Bitplaces View

CM bitplaces view

After clicking the gear icon the user can filter the Bitplaces shown in the map.

1.4. Map View

CM map view1

The Home screen map view is activated by clicking the globe icon in the menu on the left side.

CM map view2

The QuickView with first additional information about the selected Bitplaces can be activated by clicking on the Bitplaces icon on the map.

CM map view3

After activating the “more” button, the user receives detailed information about the selected Bitplace.

CM map view4

Clicking the “Analytics” provides access to first analytics details regarding the number of visitors in the last 7 days at this location and the currently active users.

2. Bitplaces

BP bitplace

By using the ‘Bitplaces’ tab the user can create new Bitplaces, view, edit, delete, change the status (active vs. inactive) and share existing Bitplaces with partner accounts.

2.1. Bitplaces import

BP import

With the help of the “Import Bitplaces” button the user can import a larger list of locations (Geofences or beacons) using a upload template in *.csv format.

BP import2

2.2. Creating a new Bitplace

BP create

When creating a New Bitplace, the user can choose the type Bitplace (Geofence Bitplace vs. Beacon Bitplace) and set additional parameters.

2.2.1. Creating a new Geofence-Bitplace

When choosing the Geofence Bitplace type, the user creates a geofence Bitplace for outdoors. You can use geofences to collect mobile users check in information. Geofences are virtual circles around any location with a freely selectable radius of 80 meters to a few kilometers.

BP creategeo

In addition to creating a Bitplace with a click on the map you can also use the quick menu “CreateNew”.
When choosing a geofence Bitplaces a geofence is created as an outdoor Bitplace.

2.2.2. Set the location of a Bitplace

BP create setlocation

A geofence Bitplace’s location can be set and adjusted via the address field and/or by setting the geo-coordinates directly and/or by dragging the Bitplace directly on the map.

2.2.3. Set the radius of a standard Bitplace

BP create setradius

The default radius of a Geofence Bitplace is set to 50m. It defines the Bitplace’s outer limits, setting its borders for IN- and OUT-event triggers. The size of the radius can be adjusted either by direct input of the figure or by dragging the slider until the desired radius size is reached.

2.2.4. Adding name and description for Geofence Bitplaces

BP create setname

Name is a mandatory field, the field description contains additional information about the created bitplace.

2.2.5. Show the bitplaces around

BP create showbparound

The check box “Show other Bitplace” shows or disable active bitplaces near the selected location.

2.2.6. Enable measurements

BP create enablemeasurement

The “Measure Bitplace” checkbox allows you to determine whether or not data should be collected for the selected location.

2.2.7. Select the Bitplace as a Campaign or shop Bitplace

BP create campaignorshop

In order to be able to perform extended reports, a Bitplace can be marked as campaign or shop Bitplace. This selection allows the automated calculation of message conversion (see also Analytics).

2.2.8. Managing the picture of a Bitplaces

BP create managepicture

The “Manage Picture” button triggers a pop up window. So the user can change the default image of a Bitplaces, either by uploading a new or selecting an already uploaded image. This image is displayed in the general message view page of an app (gallery view) next to each message, which was assigned to this Bitplace.

2.2.9. Other settings of geofence Bitplaces

Specifying the Campaign Labels of geofence Bitplace
BP create other

The “Other settings” button allows the user to assign labels to the Bitplace. So the label “Shop Bitplace” or “Campaign Bitplace” can use it later to illustrate the conversion of a campaign.
These labels represent a grouping mechanism for Bitplaces and messages, such as the grouping of all Bitplaces and messages belonging to a particular marketing campaign. Events and messages can then be evaluated and analyzed based on their membership in a campaign.

Setting the customer fields of geofence Bitplaces
BP customerfield

“Additional fields” enable individual categorizations of Bitplaces. So, for example, IDs from third party systems can be linked with the location information.

2.2.10. Assign message to a Bitplace

BP create assignmessage1

The “Manage Messages” button triggers a popup, via which the user can assign Messages to a Bitplace or create new Messages directly from the popup.

BP create assignmessage2

These Messages are sent to the mobile app when an app-user creates the according event based on the chosen Message and Bitplace settings.

2.2.11. Creating a beacon Bitplace

When choosing a “Beacon Bitplaces” an indoor Bitplace is created. Just as with a geofence Bitplace the user can also in case of a beacon Bitplaces specify the location of Bitplaces, manage the image of a Bitplaces, assign a Bitplace campaigns labels, assign a Bitplace categories and assign a Bitplace messages. In addition to these options there are three Beacon types:

  • iBeacon (Apple default)
  • Eddystone Beacon (Google Standard)
  • Physical Web URL (Google Chrome browser support)
Creating an iBeacon
BP create ibeacon

Selecting the Bitplaces type “Beacon” opens the setting options for this type of indoor Bitplaces.

The UUID of a beacon Bitplace

The UUID is the primary iBeacon identifier. The UUID-field is pre-filled for every iBeacon with the specific account-UUID. In the default scenario, each iBeacon is synced with this account-UUID. Its also possible to add additional (multiple) UUIDs to the account. By doing so, there is no need to reconfigure already existing beacons in order to use them.

The Major and the Minor a beacon Bitplace

The Major and Minor are the secondary iBeacon identifiers. If left blank, they will be filled with arbitrary values, which do not repeat within one account. By doing so, there is the need to configure your beacon with the Major and Minor in order to use them.

The Beacon ID of a beacon Bitplaces

The Beacon ID is another a further secondary iBeacon identifier. It is unique and can serve the purpose to sync the iBeacon and the Beacon-Bitplace. The internal identifier can left blank.

Creating an Eddystone Beacon Bitplace

This can only be used with the operating system Android. iOS Smartphones will not recognize an Eddystone Beacon in the background.

BP create eddystone
Creating an Eddystone namespace

The Namespace is the primary Eddystone Beacon identifier. The Namespace field is pre-filled for every Eddystone Beacon with the specific account-Namespace. In the default scenario, each Eddystone Beacon is synced with this account-Namespace. Its also possible to add additional (multiple) Namespaces to the account. By doing so, there is no need to reconfigure already existing beacons in order to use them.

Creating an Eddystone Instance ID

The Instance ID is the secondary Eddystone Beacon identifier. If left blank, it will be filled with an arbitrary value, which do not repeat within one account.

Creating a Physical Web URL

The Physical Web allows to send push notifications with an URL to Android Chrome browsers nearby an Eddystone Beacon. There is no need to install an app for that. If a URL is saved the first time a shortened link is created and displayed. This link is a permanent link and needs to be synced on the Eddystone Beacon. At any time the URL in the Bitplaces Cloud Management can be changed and the shortened link will point to the new URL. This allows to change the content for the Physical Web without changing anything on the Eddystone Beacon. Google has specific requirements on URL storage be send via an Eddystone Beacon. We recommend to use an URL validator to check an URL beforehand.

BP physicalweb

2.2.12. Show, sort, search and edit existing Bitplaces

BP show search edit

In the “Bitplaces” tab you can view, edit, sort or change the status (active vs. inactive) of existing Bitplaces with the help of the action buttons.

Perform group-edits on Bitplaces
BP group edit1

After selecting the checkbox of a Bitplace an “edit” and a “delete” button will appear above the Bitplace- List. Those buttons enable you to perform operations on all checked Bitplaces at once.

By clicking the delete-button you can delete all selected Bitplaces in one step.

When you click on the edit button you can decide if you want to change the status (active vs. inactive), change the radius or enable/disable measurement for all selected Bitplaces.

By choosing one of this options, a Pop-up window will appear, that allows you to perform the desired operation.

BP group edit2
Filtering, searching or sorting Bitplaces
BP filter search sort

The user can filter which Bitplace type is to be displayed in the Bitplaces overview and can sort or search for keywords.

It is possible to specify the search even further, by entering a keyword and search only for the ID, name, adress or description of the bitplace.
For that one have to write the following into the searchfield:

  • id: 12345, in order to search for a bitplace with id 12345
  • name: testName, in order to search by name only
  • adress: testAddress, in order to search by adress only
  • descr: testDescription, in order to search by description only

By default (if no keyword is provided) the search is by name, adress and description.

3. Messages

MSG messages

By using the ‘Messages’ tab the user can create new Messages, view, edit or delete them.

MSG summary

Using the “Create Messages” quick menu the user can create new messages or view, edit and delete existing messages.

3.1. Creating a new message

MSG create

When the user creates message different types of messages and content can be set. This feature requires the integration of the Bitplaces “Toolbox” framework.
The following message types, which differ in the graphical representation and the use of the routing function to the location, can be selected:

  • Announcement
  • Offer
  • Alert
  • Promotion
  • Ticket

In addition, you can select the following content types:

  • Text
  • Link
  • HTML

3.1.1. Message types

Creating a Text Message
MSG create textmes
MSG create linkmes

A link message will open the entered URL inside the application.

Creating an HTML message
MSG create html

The content of an HTML message can be created and adapted in a WYSIWYG HTML editor.

3.1.2. Setting the push content to a message

MSG create setpushcontent

If no push message content is defined, the app user receives only an inbox message without push notification (background notification)
Emojis can be selected and sent via the push notification.

3.1.3. Setting the title of a message

MSG create settitle

The title of a message will appear in the message overview of the app, as well as in the message itself, as the heading of message body.

3.1.4. Setting the body of a message

MSG create setbody

The message body is displayed in the message view of the app and is the main content of each message. It can take various formats, such as text, HTML, or the form of an URL that links directly to external content.

3.1.5. The image of a message

MSG create image

The “Upload Image” button creates a pop-up window that allows the user to attach an individual picture to the message, either by uploading a new or selecting an existing image. This image is displayed in the message view of the app. (single message view)

3.1.6. Assigning labels to a message

MSG create assinglabel

Under “Labels” the message can be provided with individual labels. These labels provide a group mechanism for Bitplaces and Messages, which e.g. belong to the same marketing campaign. Events and messages can then be evaluated and analyzed based on which campaigns the respective Bitplaces and/or Messages belong to.

3.1.7. Save settings

MSG create save

The ‘Save’ button saves the message settings.

3.1.8. Assign a message to a Bitplace

MSG create assingbp1

The button “Manage Bitplaces” generates a pop-up window that allows you to assign a message to a Bitplace.

MSG create assingbp2

The message is delivered to this Bitplace when the app user triggers events defined in the message- and bitplaces settings.

3.1.9. Other Settings

MSG create other

The Configure Settings button brings the user to additional settings.

3.1.10. Location-based Messages features

MSG create lbsmsgfeatures

The option “Location Dependent” offers different setting options for sending messages to specified locations.

3.1.11. Interests tags

MSG create interesttags

This message setting allows the selection of interest tags that are displayed in the app and can be selected by the app users. The interest tags allow sending a targeted message to app users with matching content.

MSG create timesettings

You can set different rules for the date, time, and period to send messages.

One can choose if the message should be send immediately after the triggering event occured, after a specified time passed by or even enter a precise time of the day.

In addition, the user can set, on which days and at what time the message should be ‘active’; E.g. if the message is to be sent only during specific opening times or on specific weekdays. A start and end date can also be set here so that the message is not sent before and afterwards. If no start date is defined, the message is active immediately after saving.

Changing the settings in the field “Time Settings” (Immediately, All day, no start date, no end date) is optional.

3.1.13. Setting the event trigger of a message

MSG create settrigger

The primary message settings let the user define if the message should be sent to the app-user when he enters the Bitplace connected to this message (BitplaceIN), or when he exists this Bitplace (BitplaceOUT), or after the app-user remains in this Bitplace for a chosen amount of minutes (Stay).

3.1.14. Setting the delivery time

MSG create setdeliverytime

Under “Delivery Time”, the user can choose whether to send a message immediately after the occurrence of the selected event, specify a specific time delay or also an exact time of the day.

Changing the settings “Message Settings”, (BitplacesIN) is optional.

3.1.15. The Inbox settings

MSG create inboxsettings

The “Inbox Settings” pop-up allows you to specify how long the message should be displayed in the user’s inbox (Message Lifetime) and whether a message is sent to the same user more than once.

3.1.16. Settings for the number of messages

MSG create numofmsg

Under “Number of messages”, the user defines the time interval in which the message is to be sent and how many of these messages are to be sent per Bitplace and in total.

3.1.17. App specific settings

MSG create appsettings

Under “apps” you can define / change to which apps the message is to be assigned.
Changing the settings in the field, “Application Settings” is optional.

3.2. Creating a new Local broadcast message

With the radio button “At a specific time” the user can create a new local broadcast message. So you can specify whether the local broadcast message should be sent immediately or at what date and at what time.

3.2.1. Assign a Bitplaces and send a local broadcast

MSG localbroadcast assingbp

Created the user a local broadcast, he can assign it to a Bitplace using the “Bitplace manage / assign” button. All app users that are in this Bitplaces will receive the broadcast immediately (default) or later, depending on the time and date settings in the “Time settings”. You can also use the “Select users” button to filter message recipients based on their interests that they have selected in the app.

3.3. Creating a new broadcast message

MSG broadcast create

“Configure Settings” allows the user to create a new broadcast message or to define already created messages as a broadcast message.

3.3.1. Setting Properties of a broadcast message

After activating the broadcast radio button, you can change the following settings of the broadcast message:

MSG broadcast settings

“Interests tags” defines whether the broadcast is be sent only to app users, which have selected certain interests in the app.
“Starting Time” defines if the shipment is immediately (default) or later, depending on the time and date settings will be made.
In addition, it is possible to determine the lifetime of the message in the app’s inbox and to select the apps to which the message has to be sent.

3.4. Show, edit and delete existing messages

MSG edit

In the message list view you can activate messages using the corresponding action buttons, view, edit or delete.

4. Analytics

The Analytics part is divided into three areas:

  • Dashboard
  • Bitplaces Analytics
  • Message Analytics

4.1. Dashboard

Dashboard

The Dashboard provides an overview of user data (registered apps, allowing push) and the inventory (number of messages, number of Bitplaces).

4.2. Analyzing visits, visitors and visitors frequencies

ANALYTICS visits1

The “Analytics” menu item offers a variety of widgets, which display standard information differently and which can be customized with the help of setting options.

ANALYTICS visits2

When analyzing bitplaces, the graph can be customized to show visits, visitors, app users, visit frequency, the number of new and returning visitors, and the dwell times for selected time periods, bitplaces, operating systems, and apps.
Activating the checkbox “Comparison to the previous period” displays or disables the alternative data in the selected widget.
Visitor frequency widgets and the dwell time give a deep insight into the selected locations.

ANALYTICS visits3

Positive or negative percentages in the “Visits” column provide a quick view of the performance of a location.
The analysis of individual bitplaces in detail is possible after clicking on the analysis button in the table view of the bitplaces.

ANALYTICS visits4

Shown is there in addition the current number of active users and a 12 hours summary overview of the selected Bitplace.

4.2.1. Selecting analysis period

ANALYTICS visits selectperiod

The fastest results are obtained by selecting one of the predefined time periods. Choose from ‘Today’, ‘Last Day’, ‘Last 7 Days’, ‘Last 14 Days’, ‘Last 30 Days’, ‘Last Calendar Week’ and ‘Last Calendar Month’.

In addition, there is the possibility to select the time period individually.

4.2.2. Selecting analyze granularity: hour, day, week, month

ANALYTICS visits selectgranularity

Each selected time span can be displayed in different granularities.

For short periods, the setting ‘hour’ makes the most sense and is only available for the selection “today” and “yesterday”. For longer periods (from one week) the setting “Day” or “Week” should be selected.

4.2.3. Selecting the mobile app releases to be analyzed

ANALYTICS visits selectrelease

A further refinement of the evaluation can be done by selecting the app release. The user can choose his own releases, from his partner or a combination of both to evaluate bitplaces events and messages in a given period of time.

4.2.4. Selecting the bitplaces to be analyzed

The user can either analyze all bitplaces at a time, or only view bitplaces relevant to him. These can be selected individually or by campaign affiliation..

4.2.5. Analyzing all Bitplaces

By default, all bitplaces are included in the overall analysis of the ‘Tools and Analytics’ tab.

4.2.6. Analyzing campaigns

The Campaign selection list allows the user to select all the bitpaces associated with a particular campaign. If he clicks on “Refresh Visit Report” after selection, only the analysis of the events and messages of the corresponding campaign will be displayed.

4.3. Analyzing sent, push and read messages

ANALYTICS msg1

After clicking the Messages button, the graphics show the number of sent messages and sent push messages for selected time periods, messages, and apps. The information is displayed in different widgets and it additionally allows a comparison with the results of the previous period.
The click rate (CTR) represents the ratio between the sent and the read messages. Push CTR refers exclusively to the sent push messages.

ANALYTICS msg2

The CTR widget shows how the click rate has evolved over a period of time and allows you to compare to the previous time period.

The message distribution graph summarizes information about sent, read, and pushed messages, and it also compares them with a previous period of time.

ANALYTICS msg3

The tabular view and the representation of percent changes in the reference period allow a quick overview of the success or failure of a sent message.

4.3.1. Selecting period, granularity and app release for the message analysis

As with the Bitplace analysis, it is also possible to use analysis time, analysis granularity, and mobile app releases for message analysis.

5. Settings

SETTINGS

In the ‘Settings’ section, the user can make general account settings and also:

5.1. Managing the account

SETTINGS manageaccount

Upload a company logo and edit the contact details.

5.2. Assigning and managing apps

SETTINGS apps1

The tabular view of the connected app provides information about the owner of the app, the name, the ID, the creation date, the ID of the push certificate for iOS (including the date of validity), and the status. It also allows the owner of the app to edit or delete the app.

SETTINGS apps2

You can use the Apps menu item to add or manage new apps to the account. A new iOS or Android app can be assigned to the account with the required certificates (for iOS). In addition, additional settings, e.g. The maximum number of push messages per day, can be set.

SETTINGS apps3

5.3. Beacon list view

SETTINGS beaconlist

The sub-item “Beacon UUIDs” lists the UUIDs of all beacons used in tabular form.

SETTINGS graphics

Under the menu item “Gallery”, the graphics used can be displayed and removed or new graphics can be added.
When importing a graphic, it can be cropped manually after selection.

6. Web Push

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

6.1. 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

6.2. 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.

6.3. Registering your Website

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

6.3.1. 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.

6.3.2. 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.

6.3.3. 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

6.3.4. Editing Websites

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

6.4. 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.

6.4.1. 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> (1)
        <script type="text/javascript">
            var BitplacesOptions = {
                clientId: "kfy5JYyv0s_shoe_shop", (2)
                clientSecret: "PI6Ioj99fZ" (3)
            };
            BitplacesSDK.initialize(BitplacesOptions); (4)
        </script>
   </body>
</html>
  1. The place where you insert the code snippet from the website info
  2. This needs to be the content of the Website Id in the Website Info.
  3. This needs to be the content of the Website Secret in the Website Info.
  4. This triggers the Web Push Registration Process.

6.4.2. 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> (1)
        <script type="text/javascript">
            var BitplacesOptions = {
                clientId: "kfy5JYyv0s_shoe_shop",
                clientSecret: "PI6Ioj99fZ",
                serviceWorkerPath: "assets/js/bpl-serviceworker.min.js"  (2)
            };
            function activateWebPush() { (3)
                BitplacesSDK.initialize(BitplacesOptions);
            }
        </script>
   </body>
</html>
  1. 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.
  2. You need to pass the adjusted path to the service worker.
  3. 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.

6.4.3. 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
};
Table 1. 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

6.5. 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.

6.5.1. 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

6.5.2. 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

6.5.3. 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

6.5.4. Editing a Web Push Message

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

6.5.5. 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

7. Imprint

Publisher

BITPLACES GmbH
Bismarckstraße 10-12
10625 Berlin
Tel.: +49 30 69 2067 330
Fax: +49 30 69 2067 339
contact@bitplaces.com
http://www.bitplaces.com

EDDYSTONE is a trademark of Google Inc.
iBeacon is a trademark of Apple Inc.

Copyright: Bitplaces 2017