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.
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. |
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.
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]); function onPAReady() { console.log(PushAlertCo.subs_id); //if empty then user is not subscribed //YOUR CODE } </script>
You can add your callback function when user successfully subscribes or fails to subscribe. Gives you the subscription ID of current subscriber.
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. |
Parameter | Type | Description |
---|---|---|
result.status | (int) | Returns -1: If notifications blocked by user 0: If notification prompt cancelled 1: If user has unsubscribed |
<script> (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 } </script>
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['onFailure', callbackOnFailure]); function callbackOnFailure(result) { console.log(result.status); //-1 - blocked, 0 - canceled or 1 - unsubscribed //YOUR CODE } </script>
Get subscription status of user and unique subscriber identifier (subs_id).
Parameter | Values | 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. |
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]); function onPAReady() { PushAlertCo.getSubsInfo(); //You can call this method to get the subscription status of the subscriber } </script>
{status: "subscribed", subs_id: "dkoVhWiR+A645Q/cbFoOAQ=="}
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.
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['disableAutoInit', true]); </script>
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]); function onPAReady() { PushAlertCo.init(); //You can call this method to request subscription box manually } </script>
Trigger the selected opt-in manually.
Parameter | Values | 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. |
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]); function onPAReady() { PushAlertCo.triggerMe(false); //You can call this method to request the opt-in manually } </script>
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.
<script> (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. } </script>
<button onclick='PushAlertCo.forceSubscribe()'>Subscribe</button>
<button onclick='PushAlertCo.forceSubscribe()'>Unblock</button>
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.
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]); function onPAReady() { PushAlertCo.unsubscribe(); } </script>
<button onclick="PushAlertCo.unsubscribe()">Unsubscribe</button>
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.
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. |
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['onReady', onPAReady]); function onPAReady() { console.log(PushAlertCo.subs_id); //if empty then user is not subscribed //YOUR CODE } </script>
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.
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['addAttributes', {"user_id":10, "name":"John"}]); //add attributes in form of key-value pair </script>
Brings up the subscription opt-in box and if a segment ID is provided, subscribers are automatically added to the mentioned segment.
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['subscribeToSegment', 3383]); //You can get segment ID from dashboard or via REST API </script>
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
<script> (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 } </script>
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.
<script> (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 } </script>
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.
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). |
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['trackEvent', 'video', 'play', 'winter collection', '51']); //trackEvent(eventCategory, eventAction, eventLabel, eventValue) </script>
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.
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['abandonedCart', 'add-to-cart',{'first_name':'Alex','total_items':2}]); </script>
Delete an abandoned cart notification on order completion or when all products are removed from cart.
<script> (pushalertbyiw = window.pushalertbyiw || []).push(['abandonedCart', 'completed']); </script>