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 here
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 here
For more information about:
- Basic usage - implementation check here
- Advanced usage - implementation check here
- SDKmethods - information check here
3. Basic Usage
Notify button
If you want to default subscribtion widget take care of your subscribtion 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 behaviour 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) |
https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes | Language Example: 'en' for English |
nationality | String (uppercase) |
https://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) |
https://en.wikipedia.org/wiki/ISO_3166-1 | country Example: "GB" for United Kingdom |
b_address | String | Bussiness address | |
b_city | String | Bussiness city | |
b_company | String | Company name | |
b_country | String (uppercase) |
https://en.wikipedia.org/wiki/ISO_3166-1 | Bussiness Country example: 'DE' for German |
b_department | String | Bussiness Department | |
b_email | String | Bussiness Email | |
b_job_title | String | Job Title | |
b_mobile | String | Bussiness Mobile Example: +41 78 123 45 67 |
|
b_phone | String | Bussiness Phone Example: +41 78 123 45 67 |
|
b_reception_code | String | Bussiness Reception code | |
b_region | String | Bussiness Region | |
b_zip | String | Bussiness 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 subscribtion. 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 suscription | |||||||||||||||||||||||||||||||||||||||||||||||||||||
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 verison 1.1.0 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||
logEnable | Boolean | Enable log which give use detailed subscription info
added in verison 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
|