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.
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 |
|
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. |
![]() |
![]() |
![]() |
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 |
|
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
|
rejectCallback | Function | no | Promise rejection rejectCallback(status) status
|
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
|
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
|
rejectCallback | Function | no | Promise rejection rejectCallback(status) status
|