Business Messenger Webpush - SDK

Supports
Chrome, Firefox

Prerequisities
To proceed with the integration of HPRO Web Push SDK to your HTTPS web site you must meet the following conditions:

  • Locate your formUuid from HORISEN nGage Application,
  • Download or use HPRO web push sdk.

To use our Webpush, your site needs to have SSL certificate or you can use localhost domain during development

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.

SDK parameters

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)

Upload downloaded file (service-worker.js) to the top-level root of your site directory, making them publicly accessible.

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.

Property Type Description
notifyButton Object
Property Type Description
enable Boolean
hideAfterSubscribe Boolean If user is subscribed auto hide button
tooltip Object Text when hover on button text
Property Type Default Value
subscribe String Subscribe to notifications
unsubscribe String Unsubscribe from notifications
notification Object Notification info text after subscription success/error.
Property Type Default Value
subscribe String You are successfully subscribed to notifications
unsubscribe String You have successfully unsubscribed
error String Subscribed to notifications failed
dialog Object Dialog question when try to subscribe/unsubscribe
Property Type Default Value
subscribe String Subscribe to notifications
unsubscribe String Unsubscribe from notifications
position String
String
top-left
top-right
bottom-left
bottom-right
theme String
String
default
light
dark
iceberg

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

Methods which are listed in documentation, can be used after init method is called and hproWebPush object is created.

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
});

identifier key in customData object use for update subscription data for specific contact

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.

identifier is special key in customData object which we use for updating subscription

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");

Upload downloaded file (service-worker.js) to the top-level root of your site directory, making them publicly accessible.

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.
SDK parameters example wordpress parameters example wordpress settings example

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)
    ;
});
Property Type Description
applicationServerKey String VAPID key
formUuid String Form UUID that is used to identify the subscription
data Object Custom data to send
whenUnsubscribed String keep_identity - or - remove_identity

Default: keep_identity

By default, when unsubscribe is finished, in local storage, identifier exist. After subscription, contact will be updated.

When remove_identity is set, after unsubscribe local storage identifier will be deleted. After subscription, new contact will be created.
autoSubscribe Boolean By default when sdk use notifyButton - autoSubscribe is true, in advanced mode is false

added in version 1.1.0
logEnable Boolean Enable log which give use detailed subscription info

added in version 1.1.0
notifyButton Object
Property Type Description
enable Boolean
hideAfterSubscribe Boolean If user is subscribed auto hide button
tooltip Object Text when hover on button text
Property Type Default Value
subscribe String Subscribe to notifications
notification Object Notification info text after subscription success/error.
Property Type Default Value
subscribe String You are successfully subscribed to notifications
unsubscribe String You have successfully unsubscribed
error String Subscribed to notifications failed
dialog Object Dialog question when try to subscribe/unsubscribe
Property Type Default Value
subscribe String Subscribe to notifications
unsubscribe String Unsubscribe from notifications
position String or Object
String
top-left
top-right
bottom-left
bottom-right

10. API

10.1 init

init(config, resolveCallback, rejectCallback)

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

  • Do not call this method twice
  • This call is required before any other function is called

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');
    });
});

Methods which are listed in documentation, can be used after init method is called and hproWebPush object is created.

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