Web Push SDK

The Web SDK represents the Beta version of our client-side JavaScript library, specifically developed for use within browser environments. Its primary function is to enable push notifications on your website, ensuring that users receive real-time updates and alerts. However, this library is not designed for server-side implementation.

One of its key advantages is its broad compatibility, as it seamlessly supports all major web browsers. Additionally, the SDK is versatile in its deployment, functioning effectively on both HTTP and HTTPS websites. Its integration process is straightforward, allowing developers to easily add it to any website without extensive modifications.

The SDK provides various methods and events to improve your push notification experience. It includes tools for managing subscriptions, audience segments, unsubscriptions, permission prompts, and subscription widgets.

Events track key interactions, such as when a permission prompt is shown, accepted, or closed. It also captures notification interactions, including when they are displayed, clicked, or dismissed. These features help optimize notification delivery and user engagement.

Note

All methods return a promise.

When we say a method returns a promise, think of it as a system’s commitment to give you a result in the future. It’s a way in coding to handle tasks that might not complete immediately. A promise ensures that once the task completes, you’ll either get the expected result or be informed about an error.

Caution

• Chrome pushes will not work with self-signed certificates (https/ssl). You’ll need SSL certificate signed by trusted Authority.
• Push notifications don’t work in both Incognito and Guest mode.
• Auto subscription is not available for Safari.

Initialize the SDK

The initialization code is as follows. It’s a part of the SDK installation code:

Syntax

index.html

<script src="https://cdn.alertwise.net/alertwise/integrate/alert-wise.js"></script>
<script type="text/javascript">
  alertwise = window.alertwise || [];
  alertwise.push(["init", {appId: "6749d6ee72da9a4b348xxxxx"}]);
</script>

Property Name	Type	Required	Description
appId	String	Yes	A unique ID for the site. The SDK uses this ID to identify the corresponding site.
applicationServerPublicKey	String	No	Application Public key. If not provided will be fetched from System table.
segment	String | String[]	No	Allows customers to assign a segment or multiple segments to subscribers during the subscription process. For more details, refer to the Segment section.

Configuration

Update AppConfig

This method enables customization of the AlertWise SDK’s behavior, offering greater control for modifications based on specific pages or conditions. Currently, the configuration API supports only the Subscription Management Widget. Any settings defined here will override those set in the AlertWise Dashboard.

Syntax

updateAppConfig(appConfig);

Example

  alertwise.push(function () {
    alertwise.updateAppConfig({
        appId: "6749d6ee72da9a4b3-XXXXX",
        scope: "/root/page"
    })
});

Schema

  interface AppConfig {
    appId: string;
    alertwiseApiUrl?: string;
    scope?: string;
    language?: string;
    serviceWorkerUrl?: string | null;
    applicationServerPublicKey?: string;
    defaultNotificationImage?: string;
    defaultNotificationTitle?: string;
    segments?: string | string[];
}

Get Subscriber ID

This method retrieves a user’s unique subscriber ID, which AlertWise generates based on their subscription data. This ID, sometimes referred to as the subscriber_hash, remains unchanged unless the user’s subscription status changes. If the user is not subscribed, the method returns null.

Syntax

    getSubscriberId().then(successCallback).catch(errorCallback);

Parameters	Type	Required	Description
successCallback	function	No	A callback function to process/ handle success response
errorCallback	function	No	A callback function to process/ handle failure response

Example

  alertwise.push(function () {
    alertwise.getSubscriberId()
        .then(x => console.log(`Subscription Id received: ${x}`))
        .catch(error => console.log(error.message, error.details))
});

Get Subscriber Details

Update details

Syntax

updateAppConfig().then(successCallback).catch(errorCallback);

Parameters	Type	Required	Description
successCallback	function	No	A callback function to process/ handle success response
errorCallback	function	No	A callback function to process/ handle failure response

Example

alertwise.push(function () {
    alertwise.getSubscriber()
        .then(x => console.log(`Subscriber Details: ${JSON.stringify(x)}`))
        .catch(error => console.log(error.message, error.details))
});

Response Object

interface ISubscription {
    id: string,
    appId: string
    endpoint: string
    p256dh: string
    auth: string
    browser: string
    device: string
    os: string
    city: string
    region: string
    country: string
    currency: string
    language: string
    timeZone: string
    timeZoneOffset: number,
    subscriptionAt: string
}

Property Name	Type	Required	Description
id	String	Yes	A unique ID for each subscriber, generated by AlertWise using subscription details. It identifies the subscriber and only changes if the subscription details change.
appId	String	Yes	A unique ID for the Application.
browser	String	Yes	The browser in which the subscriber opted in.
timezone	String	Yes	Displays the subscriber’s timezone. It updates automatically if the subscriber changes their timezone and revisits the site. The value is presented in the format +/-HH:MM.
subscriptionAt	String	Yes	The subscription date of the subscriber, following the format YYYY-MM-DDTHH:MM:SSZ.
device	String	Yes	The device type from which the subscriber opted in, such as desktop or mobile.
language	String	Yes	The language of the browser for subscriber.
attributes	Object	Yes	Key-value pairs set by the site owner for the subscriber. The data can be any key-value format. If nothing is set, it defaults to an empty object. Further details are in the “Attributes” section.
segments	String[]	Yes	Segments target specific subscriber groups. This shows the names of the segments to which a subscriber belongs. If they aren’t linked with any segment, it returns an empty array. Further details are in the “Segment” section.
country	String	No	Shows the country from which the subscriber opted in. It updates when they change their location and revisit the site. This detail is only accessible when “Enable Geolocation” is turned on in the “Site Details” dashboard.
region	String	No	Represents the state from which the subscriber opted in. It updates when the subscriber changes location and revisits the site. This detail is accessible only when “Enable Geolocation” is turned on in the “Site Details” dashboard.
city	String	No	Denotes the city from which the subscriber opted in. It updates when the subscriber changes their location and revisits the site. This detail is accessible only when “Enable Geolocation” is enabled in the “Site Details” dashboard section.

Check for Push Notification Support

This method checks whether the browser supports push notifications. It returns a boolean value.

Syntax

isPushNotificationSupported().then(successCallback).catch(errorCallback);

Parameters	Type	Required	Description
successCallback	function	No	A callback function to process/ handle success response
errorCallback	function	No	A callback function to process/ handle failure response

Example

alertwise.push(function () {
    alertwise.isPushNotificationSupported()
        .then(x => console.log(`isPushNotificationSupported: ${x}`))
        .catch(error => console.log(error.message, error.details))
});

Unsubscribe Subscriber

This method allows you to unsubscribe the current subscriber from receiving push notifications. After unsubscribing, the subscriber will no longer receive any push notifications.

Syntax

unsubscribe().then(successCallback).catch(errorCallback);

Parameters	Type	Required	Description
successCallback	function	No	A callback function to process/ handle success response
errorCallback	function	No	A callback function to process/ handle failure response

Example

alertwise.push(function () {
    alertwise.unsubscribe()
        .then(x => console.log(`unsubscribe response: ${JSON.stringify(x)}`))
        .catch(error => console.log(error.message, error.details))
});

Response Sample

{
  "message": "<response Message>"
}

Get User Permission

This method enables you to determine the current user’s permission status for notifications. The possible values are default, granted, or denied.

Syntax

getPermission().then(successCallback).catch(errorCallback);

Parameters	Type	Required	Description
successCallback	function	No	A callback function to process/ handle success response
errorCallback	function	No	A callback function to process/ handle failure response

Example

alertwise.push(function () {
    alertwise.getPermission()
        .then(x => console.log(`getPermission response: ${JSON.stringify(x)}`))
        .catch(error => console.log(error.message, error.details))
});

Event

These events enable you to listen for specific actions from the PushEngage SDK. You can use them to monitor subscription changes, track permission prompt actions (such as display, allow, or close), and observe interactions with notifications (like display, click, or close).

Events	Description
AlertWise.onReady	To add a callback when AlertWise SDK is ready.
AlertWise.onSDKError	To add a callback when AlertWise SDK encounters any unhandled exception.
AlertWise.onSWError	To add a callback when AlertWise Service Worker encounters any unhandled exception.
AlertWise.onSubscriptionChange	To add a callback on Subscription or re-Subscription.
AlertWise.onUnsubscribe	To add a callback on UnSubscription.
AlertWise.onPermissionPromptDisplayed	To add a callback when Permission Prompt displayed.
AlertWise.onPermissionPromptGranted	To add a callback when Permission Prompt closed with ‘Allow’.
AlertWise.onPermissionPromptDenied	To add a callback when Permission Prompt closed with denied.
AlertWise.onNotificationDisplayed	To add a callback when Notification is displayed to the user.
AlertWise.onNotificationClick	To add a callback when Notification is clicked by the user.
AlertWise.onNotificationClose	To add a callback when Notification is closed by the user.

onReady Event

A callback function to tell you when the AlertWise SDK is ready.

Syntax

window.addEventListener('AlertWise.onReady', callbackFunction);

Example

window.addEventListener('AlertWise.onReady', function (event) {
  console.log(event.detail);
});

onSDKError Event

To add a callback when AlertWise SDK encounters any unhandled exception.

Syntax

  window.addEventListener('AlertWise.onSDKError', callbackFunction);

Example

  window.addEventListener('AlertWise.onSDKError', function (event) {
    console.log(event.detail);
});

Event Details response

{
  "message": "Internal error: <process> fail!",
  "error": {
  }
}

onSWError Event

To add a callback when AlertWise Service Worker encounters any unhandled exception.

Syntax

  window.addEventListener('AlertWise.onSWError', callbackFunction);

Example

  window.addEventListener('AlertWise.onSWError', function (event) {
    console.log(event.detail);
});

Event Details response

{
  "message": "Internal error: <process> fail!",
  "error": {
  }
}

onUnsubscribe Event

This event monitors changes in subscriptions. It’s triggered either when an existing subscription is removed.

Syntax

  window.addEventListener('AlertWise.onUnsubscribe', callbackFunction);

Example

  window.addEventListener('AlertWise.onUnsubscribe', function (event) {
    console.log(event.detail);
});

Event Details response

{
  "subscriberId": "<old subscriber-id>"
}

onPermissionPromptDisplayed Event

This event monitors when a notification is displayed to the user. The details provided include the notification’s title.

Syntax

  window.addEventListener('AlertWise.onPermissionPromptDisplayed', callbackFunction);

Example

  window.addEventListener('AlertWise.onPermissionPromptDisplayed', function (event) {
    console.log('AlertWise.onPermissionPromptDisplayed');
});

onPermissionPromptGranted Event

This event tracks when a user grants permission through the prompt. It’s activated when the ‘Allow’ button is clicked on either the HTML popup modal or the native browser prompt.

Syntax

  window.addEventListener('AlertWise.onPermissionPromptGranted', callbackFunction);

Example

  window.addEventListener('AlertWise.onPermissionPromptGranted', function (event) {
    console.log(event.detail);
});

onPermissionPromptDenied Event

This event monitors when a notification is displayed to the user. The details provided include the notification’s title.

Syntax

  window.addEventListener('AlertWise.onPermissionPromptDenied', callbackFunction);

Example

  window.addEventListener('AlertWise.onPermissionPromptDenied', function (event) {
    console.log(event.detail);
});

onPermissionPromptDenied Event

Utilize this event to track when the permission prompt is closed. It triggers when the ‘Close’ button is clicked on either the HTML popup modal or the native browser prompt.

Syntax

  window.addEventListener('AlertWise.onPermissionPromptDenied', callbackFunction);

Example

  window.addEventListener('AlertWise.onPermissionPromptDenied', function (event) {
    console.log(event.detail);
});

onNotificationDisplayed Event

This event monitors when a notification is displayed to the user. The details provided include the notification’s title.

Syntax

  window.addEventListener('AlertWise.onNotificationDisplayed', callbackFunction);

Example

  window.addEventListener('AlertWise.onNotificationDisplayed', function (event) {
    console.log(event.detail.title);
});

onNotificationClick Event

This event monitors when a user clicks on a notification. The details provided include the notification’s title.

Syntax

  window.addEventListener('AlertWise.onNotificationClick', callbackFunction);

Example

  window.addEventListener('AlertWise.onNotificationClick', function (event) {
    console.log(event.detail.title);
});

onNotificationClose Event

This event monitors when a notification is closed by the user. The details provided include the notification’s title.

Syntax

  window.addEventListener('AlertWise.onNotificationClose', callbackFunction);

Example

  window.addEventListener('AlertWise.onNotificationClose', function (event) {
    console.log(event.detail.title);
});