nGage

Webpush

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

Setup

Account

Register your Horisen PRO account.

nGage Form

In nGage 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 example

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.0.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.0.0/hpro-wp-sw.js");

Release Archive:

Version Download
latest link
1.0.0 link

Step 2 - SDK

Include SDK script in your page:

<script type="text/javascript" src="https://content.horisen.pro/js/webpush/1.0.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 nGage app.

Step 3 - Integration

For more information about Configuration Parameters you can check here

For more information about:

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

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
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 Unubscribe from notifications
notification Object Notification info text after subscribtion succes/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 Unubscribe from notifications
position String
String
top-left
top-right
bottom-left
bottom-right
theme String
String
default
light
dark
iceberg

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

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

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.0.0 version here)

service-worker.js

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

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

Configuration

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

1. nGage App 2. hproWebpush Plugin | General Settings 3. hproWebpush Plugin | Notify Button Settings
In Opt-in/Opt-out Forms section inside nGage 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.
sdk parameters example wordpress parameters example wordpress settings example

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.
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 subscribtion succes/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 Unubscribe from notifications
position String or Object
String
top-left
top-right
bottom-left
bottom-right

API

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

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

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

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 successfull subscription is done
rejectCallback Function no Promise rejection
rejectCallback(status)

status
  • denied
    When notification permission state is denied
  • notPermitted
    All other condittions

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 successfull unsubscribe is done
rejectCallback Function no Rejects with notification permission status

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

Properties

Property Type Required Description
customData Object no Custom data to send
resolveCallback Function no Promise resolving
resolveCallback(status)

status
  • updated
    when a successfull subscription is done
rejectCallback Function no Promise rejection
rejectCallback(status)

status
  • denied
    When notification permission state is denied
  • notPermitted
    All other condittions