Business Messenger Webpush - SDK

1. Introduction

Business Messenger Webpush SDK is a javascript library that provides subscription mechanism for Web Push notifications for your website/domain.

After a visitors subscribes you will be able to notify him with updates using standard Business Messenger campaigns.

The SDK can be configured either as a small subscription button widget or used directly from javascript so that you can build your own custom subscription forms and collect some other information to be populated per contact in Business Messenger Contact Manager.

Setup

ACCOUNT

Register your HORISEN PRO account.

BUSINESS MESSENGER FORM

In Business Messenger App go to Opt-in/Opt-out Forms section, create a Form and find your formUuid which you will use later in configuring the SDK.

2. Typical Setup

STEP 1 - SERVICE WORKER

Download or Create a service-worker.js and import a script from our CDN

(Download latest version here) or (Download 1.1.0 version here)

service-worker.js

importScripts("https://content.horisen.pro/js/webpush/1.1.0/hpro-wp-sw.js");

Release Archive:

Version	Download
latest	link
1.1.0	link

STEP 2 - SDK

Include SDK script in your page:

<script type="text/javascript" src="https://content.horisen.pro/js/webpush/1.1.0/hpro-wp-sdk.js" async></script>

Configure the Web Push SDK:

For more information about Configuration Parameters, you can check in 9. SDK API section of this document.

var hproWebPush = hproWebPush || [];

hproWebPush.push(function () {
    // before all init first
    hproWebPush.init({
        formUuid: 'YOUR_FORM_UUID',
        applicationServerKey: 'YOUR_WEBPUSH_PUBLIC_KEY'
    }).then(function initResolve() {
    // code for resolve
    }, function initReject() {
    // code for reject
    });
});

formUuid (YOUR_FORM_UUID) and applicationServerKey (YOUR_WEBPUSH_PUBLIC_KEY) parameter need to replace with real value from Opt-in/Opt-out Forms section inside Business Messenger app.

STEP 3 - INTEGRATION

For more information about Configuration Parameters, you can check in 9. SDK API section of this document.

For more information about:

• Basic usage - implementation, please find in section 3. of this document.
• Advanced usage - implementation, please find in section 5. of this document.
• SDK methods - information, please find in section 10. of this document.

3. Basic Usage

Notify button

If you want to default subscription widget take care of your subscription process, you need to configure NotifyButton parameter inside init method.

notifyButton: {
    enable: true
}

Check code block below to see example:

var hproWebPush = hproWebPush || [];

hproWebPush.push(function () {
    // before all init first
    hproWebPush.init({
        formUuid: 'YOUR_FORM_UUID',
        applicationServerKey: 'YOUR_WEBPUSH_PUBLIC_KEY',
        notifyButton: {
            enable: true
        }
    }).then(function initResolve() {
    // code for resolve
    }, function initReject() {
    // code for reject
    });
});

4. Customization

In table below you have properties that you can use inside notify Button object. If you want to change some default behavior of widget.

5. Advanced Usage

USAGE

If you want to your form (from your website) take care of your subscription process, you need to check methods bellow.

The main advantage of using this way of implementation is that you can collect data from subscribers which want to subscribe on web push service.

var hproWebPush = hproWebPush || [];

hproWebPush.push(function () {
    // before all init first
    hproWebPush.init({
        formUuid: 'YOUR_FORM_UUID',
        applicationServerKey: 'YOUR_WEBPUSH_PUBLIC_KEY'
    }).then(function initResolve() {
        // METHODS
        // Example
        hproWebPush.isSubscribed().then(function isSubscribedResolve() {
            // code for resolve
        }, function isSubscribedReject() {
            // code for reject
        });
    }, function initReject() {
        // code for reject
    });
});

METHODS

Check subscription

hproWebPush.isSubscribed().then(function isSubscribedResolve() {
    // code for resolve
}, function isSubscribedReject() {
    // code for reject
});

Subscribe

hproWebPush.subscribe(customData).then(function subscribeResolve() {
    // code for resolve
}, function subscribeReject() {
    // code for reject
});

Unsubscribe

hproWebPush.unsubscribe().then(function unsubscribeResolve() {
    // code for resolve
}, function unsubscribeReject() {
    // code for reject
});

Unsubscribe specific contact

hproWebPush.unsubscribe({identifier: 'YOUR_CONTACT_ID'}).then(function unsubscribeResolve() {
    // code for resolve
}, function unsubscribeReject() {
    // code for reject
});

6. Custom Data

"Custom Data" is data that you can send to our service when subscribe method is triggered. With that way of gathering data, you will have more information about your subscriber.

Key	Type	Values	Description
first_name	String		First Name
last_name	String		Last Name
nick_name	String		Nick Name
second_name	String		Second Name
gender	String	male female	Gender Female -or- Male
birthday	String		Birthday Format: 2018-01-03
salutation	String		Salutation
fax	String		Fax
language	String (lowercase)	en.wikipedia.org/wiki/List_of_ISO_639-1_codes	Language Example: 'en' for English
nationality	String (uppercase)	en.wikipedia.org/wiki/ISO_3166-1	Nationality Example: "GB" for United Kingdom
mobile	String		Mobile Example: +41 78 123 45 67
phone	String		Phone Example: +41 78 123 45 67
title	String		Title
zip	String		Zip
address	String		Address
city	String		City
region	String		Region
country	String (uppercase)	en.wikipedia.org/wiki/ISO_3166-1	country Example: "GB" for United Kingdom
b_address	String		Business address
b_city	String		Business city
b_company	String		Company name
b_country	String (uppercase)	en.wikipedia.org/wiki/ISO_3166-1	Business Country example: 'DE' for German
b_department	String		Business Department
b_email	String		Business Email
b_job_title	String		Job Title
b_mobile	String		Business Mobile Example: +41 78 123 45 67
b_phone	String		Business Phone Example: +41 78 123 45 67
b_reception_code	String		Business Reception code
b_region	String		Business Region
b_zip	String		Business Zip

7. Wordpress Usage

Download plugin

Download hproWebpush.zip plugin to your plugin folder and extract inside wp-content/plugins

(Download latest version here)

Service Worker

Download or Create a service-worker.js to your site ROOT directory and import a script from our CDN

(Download latest version here) or (Download 1.1.0 version here)

service-worker.js

importScripts("https://content.horisen.pro/js/webpush/1.1.0/hpro-wp-sw.js");

8. Configuration

After login to your site. Activate hproWebpush plugin. In nGage Webpush menu section open General settings

1. Business Messenger App	2. hproWebpush Plugin - General Settings	3. hproWebpush Plugin - Notify Button Settings
In Opt-in/Opt-out Forms section inside Business Messenger app copy parameters	Paste parameters formUuid (YOUR_FORM_UUID) and applicationServerKey (YOUR_WEBPUSH_PUBLIC_KEY) inside wordpress plugin.	Check "Enable" checkbox to enable widget for subscription. If you want to configure optional parameters for Notify Button Widget.

9. SDK API

Usage

Our API functions can be called asynchronously in two ways:

hproWebPush.push(function () {
    hproWebPush.functionName(param1, param2);
});

or

hproWebPush.push(['apiFunction', param1, param2]);

Configuration

var hproWebPushConfig = {
    applicationServerKey: 'YOUR_WEBPUSH_PUBLIC_KEY',
    formUuid: 'YOUR_FORM_UUID'
};

function resolveInit() {};
function rejectInit() {};

hproWebPush.push(['init', hproWebPushConfig, resolveInit, rejectInit])
// or with
.then(resolveInit)
.catch(rejectInit)
;

or

function resolveInit() {};
function rejectInit() {};

hproWebPush.push(function () {
    hproWebPush.init(hproWebPushConfig, resolveInit, rejectInit)
    // or with
    .then(resolveInit)
    .catch(rejectInit)
    ;
});

10. API

10.1 init

init(config, resolveCallback, rejectCallback)

Call this function from your page where you want to use hproWebPush.

Return

Promise

Usage:

var hproWebPush = hproWebPush || [];

hproWebPush.push(function () {
    hproWebPush.init({
        formUuid: 'YOUR_FORM_UUID',
        applicationServerKey: 'YOUR_WEBPUSH_PUBLIC_KEY'
    }, function () {
        console.log('initialized');
    }, function(){
        console.log('Not initialized');
    });
});

Properties

Property	Type	Required	Description
config	Object	yes
resolveCallback	Function	no	Promise resolve
rejectCallback	Function	no	Promise Rejection

10.2 isSubscribed

isSubscribed( resolveCallback, rejectCallback )

Check to see if you are already subscribed. Each callback will return the permission state.

Return

Promise

Usage:

hproWebPush.isSubscribed().then(function (permissionState) {
    console.log('subscribed', permissionState);
}).catch(function (permissionState) {
    console.log('not subscribed or no permission granted', permissionState);
});

Properties

Property	Type	Required	Description
resolveCallback	Function	no	Resolves with notification permission status
rejectCallback	Function	no	Rejects with notification permission status

10.3 permit

permit ( resolveCallback, rejectCallback )

Trigger the browsers notification permission dialog.

Return

Promise

Usage:

hproWebPush.permit().then(function (permissionState) {
    console.log('permitted', permissionState);
}).catch(function (permissionState) {
    console.log('not permitted', permissionState);
});

Properties

Property	Type	Required	Description
resolveCallback	Function	no	Resolves with notification permission status
rejectCallback	Function	no	Rejects with notification permission status

10.4 subscribe

subscribe(customData, resolveCallback, rejectCallback)

Do a subscription process

Return

Promise

Usage:

hproWebPush.subscribe().then(function (status) {
    console.log('subscribed', status);
}).catch(function (permissionState) {
    console.log('not subscribed', status);
});

Properties

Property	Type	Required	Description
customData	Object	no
resolveCallback	Function	no	Promise resolving resolveCallback(status) status subscribed when a successful subscription is done
rejectCallback	Function	no	Promise rejection rejectCallback(status) status denied When notification permission state is denied notPermitted All other conditions

10.5 unsubscribe

unsubscribe(customData, resolveCallback, rejectCallback)

Unsubscribe current subscription

Return

Promise

Usage:

hproWebPush.unsubscribe().then(function (responseCode) {
    console.log('unsubscribed', responseCode);
}).catch(function (responseCode) {
    console.log('not unsubscribed', responseCode);
});

Properties

Property	Type	Required	Description
customData	Object	no	Custom data to send
resolveCallback	Function	no	Promise resolving resolveCallback(status) status unsubscribed when a successful unsubscribe is done
rejectCallback	Function	no	Rejects with notification permission status

10.6 update

update(customData, resolveCallback, rejectCallback)

Update current subscription

Return

Promise

Usage:

hproWebPush.update({ identifier: 'YOUR_CONTACT_ID' }).then(function (responseCode) {
    console.log('updated', responseCode);
}).catch(function (responseCode) {
    console.log('not updated', responseCode);
});

Property	Type	Required	Description
customData	Object	no	Custom data to send
resolveCallback	Function	no	Promise resolving resolveCallback(status) status updated when a successful subscription is done
rejectCallback	Function	no	Promise rejection rejectCallback(status) status denied When notification permission state is denied notPermitted All other conditions