Documentation: Push Notifications Onsite Messaging REST API
  1. Documentation
  2. Web Push Notifications
  3. JS API

Web Push JS API

This is the PushAlert JS API Documentation. Below, you'll find a full listing of all the available functions. As we add more functionality, they will be documented here as well.

If you need any help using the JS API or have any issue with its implementation, please send us a mail at api@pushalert.co.

For more information about a particular function, click on its name under the Resource header. You'll be taken to the function's documentation along with an example.

Methods and Callbacks

Resource Description
Subscription
onReady To add a callback when PushAlert API is ready.
onSuccess/onFailure To add a callback on success or failure of subscription.
getSubsInfo To get current subscription status and unique subscriber identifier.
disableAutoInit To disable automatic opt-in prompt.
triggerMe To trigger the selected Opt-in Box manually.
forceSubscribe To bring-up the subscription opt-in, can be used to create custom Subscribe, Unblock buttons.
unsubscribe To unsubscribe the user.
pa_localized_str To customize opt-in prompts in different languages or on a per-page basis
subs_id To get the subscriber ID of current user.
Attributes
addAttributes To add custom attributes for a subscriber.
Segmentation
subscribeToSegment To initiate subscription opt-in for the given segment.
addToSegment To add subscriber to a segment.
removeFromSegment To remove subscriber from a segment.
Custom Events
trackEvent To send automated notification on subscriber triggered event.
Automated Abandoned Cart Notifications
abandonedCart To send an automated notification on cart abandonment or delete the notification on order completion/cart cleared.

Subscription

onReady

A callback function to tell you when the PushAlert JS API is ready. This is a new endpoint and has been published for all customers, however, some may still have the old integration script cached in their browsers. If you get an error using this function, please head to Settings > Website in your PushAlert dashboard and click on Submit, this will force an update to the JS API for your account.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]);

function onPAReady() {
    console.log(PushAlertCo.subs_id); //if empty then user is not subscribed

    //YOUR CODE
}
Copy

onSuccess/onFailure

You can add your callback function when user successfully subscribes or fails to subscribe. Gives you the subscription ID of current subscriber.

Callback Parameters

onSuccess
Parameter Type Description
result.subscriber_id (string) Subscriber ID of the user who has already opted-in.
result.alreadySubscribed (boolean) Returns
false: If the user has just subscribed
true: Every next visit till user is subscribed.
onFailure
Parameter Type Description
result.status (int) Returns
-1: If notifications blocked by user
 0: If notification prompt cancelled
 1: If user has unsubscribed

Examples

onSuccess
(pushalertbyiw = window.pushalertbyiw || []).push(['onSuccess', callbackOnSuccess]);

function callbackOnSuccess(result) {
    console.log(result.subscriber_id); //will output the user's subscriberId
    console.log(result.alreadySubscribed); // False means user just Subscribed

    //YOUR CODE
}
Copy
onFailure
(pushalertbyiw = window.pushalertbyiw || []).push(['onFailure', callbackOnFailure]);

function callbackOnFailure(result) {
    console.log(result.status); //-1 - blocked, 0 - canceled or 1 - unsubscribed

    //YOUR CODE
}
Copy

getSubsInfo

Get subscription status of user and unique subscriber identifier (subs_id).

Parameter Type Description
status subscribed If the user has given permission to receive notifications.
unsubscribed If the user has unsubscribed from receiving notifications.
denied User has declined notification permission/blocked permission.
canceled User has selected Later option on the 2-step opt-in.
no_init PushAlert script initialization is disabled.
subs_id Subscriber Id Unique subscriber identifier in the form of a string.
false If Subscriber Id does not exist.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]);

function onPAReady() {
    var subs_info = PushAlertCo.getSubsInfo(); //You can call this method to get the subscription status of the subscriber
    console.log("Status: " + subs_info.status + ", subs_id: " + subs_info.subs_id);
}
Copy

Output

{status: "subscribed", subs_id: "dkoVhWiR+A645Q/cbFoOAQ=="}
Copy

disableAutoInit

Consider that you don't want the opt-in to be displayed automatically, you can use the following code. However, once auto initialization is disabled, you would have to call the init method to bring up the opt-in prompt.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['disableAutoInit', true]);
Copy

Bring up subscription opt-in manually

(pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]);

function onPAReady() {
    PushAlertCo.init(); //You can call this method to request subscription box manually
}
Copy

triggerMe

Trigger the selected opt-in manually.

Parameter Type Description
forceTrigger false Will trigger the appropriate opt-in as selected from Opt-in Settings. This will only trigger the opt-in if the user has not previously canceled the notification opt-in.
true This will trigger the appropriate opt-in even if the user has previously canceled the notification opt-in.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]);

function onPAReady() {
    PushAlertCo.triggerMe(false); //You can call this method to request the opt-in manually
}
Copy

forceSubscribe

Brings up the subscription opt-in, even if previously declined. Circumvents the opt-in settings, and shows the native browser opt-in directly. If you want to show the 2-step opt-in (selected in Settings > Opt-in Box) use triggerMe function. Can be used to create Subscribe and Unblock buttons, check examples below.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]);

function onPAReady() {
    PushAlertCo.forceSubscribe(); //This will bring up the subscription opt-in, if it is not blocked. If blocked, it will show steps to unblock notifications.
}
Copy

Subscribe Button

<button onclick="PushAlertCo.forceSubscribe()">Subscribe</button>
Copy

Unblock Button

<button onclick="PushAlertCo.forceSubscribe()">Unblock</button>
Copy

unsubscribe

For opting-out of Push Notifications. User won't receive any notifications if successfully unsubscribed. Can also be used to create separate Unsubscribe button on website.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]);

function onPAReady() {
    PushAlertCo.unsubscribe();
}
Copy

Unsubscribe Button

<button onclick="PushAlertCo.unsubscribe()">Unsubscribe</button>
Copy

pa_localized_str

For multi-language websites and for per-page customization of PushAlert subscription opt-in prompts. This can be used to customize the text shown on opt-in prompts. If any fields are left, the default value would be picked from the database. You can generate custom text for prompts with the help of Localized String Generator, for more details see Localization.

subs_id

To get subscription ID of current user. This can be used to associate subscriber to a particular segment or send notification to that individual.

Parameter Type Description
PushAlertCo.subs_id (string) Returns subscription ID of current user. If empty, then user is not subscribed.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]);

function onPAReady() {
    console.log(PushAlertCo.subs_id); //if empty then user is not subscribed

    //YOUR CODE
}
Copy

Attributes

addAttributes

To add custom attributes to a subscriber. This function will do nothing if the user is not subscribed, else mentioned attributes will be added to the subscriber. These attributes can be used in personalizing notifications and for targeting particular sets of subscribers. Maximum key length is 32 characters and value length is 128 characters.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['addAttributes', {"user_id":10, "name":"John"}]); //add attributes in form of key-value pair
Copy

Segmentation

subscribeToSegment

Brings up the subscription opt-in box and if a segment ID is provided, subscribers are automatically added to the mentioned segment.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['subscribeToSegment', 3383]); //You can get segment ID from dashboard or via REST API
Copy

addToSegment

To add a user to a particular segment. This function will do nothing if the user is not subscribed, else they will be automatically added to mentioned segment. Additionally you can mention a callback function. To bring up a subscription prompt for a specific segment, you can use the above function - subscribeToSegment

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['addToSegment', 993, callbackFunction]); //You can get segment ID from dashboard or via REST API

function callbackFunction(result){
    console.log(result.success) // True or False
    //Your Code
}
Copy

removeFromSegment

To remove a user from a particular segment. This function will do nothing if the user is not subscribed, else they will be automatically removed from the mentioned segment. Additionally you can mention a callback function.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['removeFromSegment', 993, callbackFunction]); //You can get segment ID from dashboard or via REST API

function callbackFunction(result){
    console.log(result.success) // True or False
    //Your Code
}
Copy

Custom Events

trackEvent

To send automated notification when a subscriber triggers an event. Add the following script on the page where you want to track an event. You can track multiple events on the same page.

Request Parameters

Parameter Type Description
eventCategory (string or integer) Required The object or page that was interacted with (e.g. 'Video').
eventAction (string or integer) Required The type of interaction (e.g. 'play','pause','stopped').
eventLabel (string or integer) Optional Used for categorizing events. (e.g. 'Launch Campaign').
eventValue (integer) Optional A numeric value associated with the event (e.g. 2017).

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['trackEvent', 'video', 'play', 'winter collection', '51']); //trackEvent(eventCategory, eventAction, eventLabel, eventValue)
Copy

Automated Abandoned Cart Notifications

abandonedCart

Use this function to schedule/update a notification when a cart is abandoned on your eCommerce store or delete it when the order is completed/cart is cleared.

You can use two parameters to personalize notifications - first_name and total_items. You can choose to include either one or both of them. Where 'first_name' is the first or full name of the customer, while 'total_number' is the number of items in cart.
For e.g. {'first_name':'Alex','total_items':2}

Schedule an abandoned cart notification or update an existing notification when the cart is changed.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['abandonedCart', 'add-to-cart',{'first_name':'Alex','total_items':2}]);
Copy

Delete an abandoned cart notification on order completion or when all products are removed from cart.

Example

(pushalertbyiw = window.pushalertbyiw || []).push(['abandonedCart', 'completed']);
Copy