JavaScript Async API

Getting Started

The PushEngage JavaScript Async API is used to gather information about your web push subscribers. The subscriber is a user, who clicks "allow" on your notification permission box, and subscribes to your website.

Note

Use JavaScript Async API, if you have added async installation code from the PushEngage dashboard on your website. Since it is an async API, it will only work on page load.

The PushEngage JavaScript API allows you to

  • Register Callback for New Subscription
  • Subscriber Hash for New Subscription
  • Geo Information for New Subscription
  • Get User Subscription Status
  • Add a Segment to a Subscriber
  • Remove a Subscriber from a Segment
  • Add Profile Id to a Subscriber

Register Callback for New Subscription

window._peq.push(['init',{}.pe,function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res);
    }
}]);

Subscriber Hash for New Subscription

window._peq.push(['init',{}.pe,function(res){
    if(res.statuscode==1)
    {
      //Get your subscriber hash in response 
      console.log(res.subscriber_hash);
    }
}]);

Geo Information for New Subscription

window._peq.push(['init',{}.pe,function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res.data.geoInfo);
    }
}]);
Response
{statuscode:1,status:"SUBSCRIBED",message:"User subscribed sucessfully",subscriber_hash:"UserUniqueId",data:{geoInfo:{country: "Your Country", state: "Your State", city: "Your City"}}}
{statuscode:2,status:"DENIED",message:"User denied push notification"}
{statuscode:3,status:"CLOSED",message:"User closed subscription Opt-in"}
{statuscode:0,message:"Something went wrong"}
{statuscode:20,message:"Your website url is not allowed, please configure in PushEngage correctly"}
{statuscode:21,message:"Your browser does not support PushEngage web push notification"}

User Subscription Status

This API call returns user subscription status in the form of object.

window._peq.push(['subscriber-status',function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res);
    }
}]);

Response

{statuscode:1,status:"SUBSCRIBED",message:"User subscribed sucessfully",data:{subscriber_hash:"UserUniqueId"}}
{statuscode:2,status:"DENIED",message:"User denied push notification"}
{statuscode:3,status:"CLOSED",message:"User closed subscription Opt-in"}
{statuscode:20,message:"Your website url is not allowed, please configure in PushEngage correctly"}
{statuscode:21,message:"Your browser does not support PushEngage web push notification"}
{statuscode:22,message:"User not subscribed"}

Add a Segment to a Subscriber

Add a segment to a subscriber and notification will be sent to only those subscribers which are subscribed with this segment. Segment name is a user defined name that is used to target the subscribers based on the location or category. Create a segment name from the PushEngage dashboard under Segmentation → Manage Segments.

Case a: Add a segment to a subscriber at the time of subscription by passing parameter as a "segmentName"

window._peq.push(['init','segmentName']);

OR,

window._peq.push(['init','segmentName',function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res);
    }
}]);

Response

{statuscode:1,status:"SUBSCRIBED",message:"User subscribed sucessfully",subscriber_hash:"UserUniqueId"}
{statuscode:2,status:"DENIED",message:"User denied push notification"}
{statuscode:3,status:"CLOSED",message:"User closed subscription Opt-in"}
{statuscode:0,message:"Something went wrong"}
{statuscode:20,message:"Your website url is not allowed, please configure in PushEngage correctly"}
{statuscode:21,message:"Your browser does not support PushEngage web push notification"}
Case b: Add a segment to a subscriber on page load of your site by passing parameter as a "segmentName"

window._peq.push(['add-to-segment','segmentName']);

OR,

window._peq.push(['add-to-segment','segmentName',function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res); 
    }
}]);

Response

{statuscode:1,message:"Segment added sucessfully"}
{statuscode:2,message:"Segment already added"}
{statuscode:3,message:"Segment not found"}
{statuscode:0,message:"Something went wrong"}
{statuscode:20,message:"Your website url is not allowed, please configure in PushEngage correctly"}
{statuscode:21,message:"Your browser does not support PushEngage web push notification"}
{statuscode:22,message:"User not subscribed"}
{statuscode:23,message:"Subscriber is not valid for request api"}
{statuscode:24,message:"Your given segment is not valid"}

Add a Dynamic Segment to a Subscriber

Case c: Add a dynamic segment to a subscriber on page load of your site by passing parameter as a "segmentName" and "days", where after the given number of days, subscriber will be removed from passed segment name.

window._peq.push(['add-to-dynamic-segment','segmentName',days]);

OR,

window._peq.push(['add-to-dynamic-segment','segmentName',days,function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res);
    }
}]);

Note

A subscriber can belong to multiple segments.

Remove a Subscriber from a Segment

Remove a subscriber from a particular segment by passing parameter as a "segmentName".

window._peq.push(['remove-to-segment','segmentName']);

OR,

window._peq.push(['remove-to-segment','segmentName',function(res){    
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res); 
    }
}]);

Response

{statuscode:1,message:"Segment removed sucessfully"}
{statuscode:2,message:"Segment already removed"}
{statuscode:0,message:"Something went wrong"}
{statuscode:20,message:"Your website url is not allowed, please configure in PushEngage correctly"}
{statuscode:21,message:"Your browser does not support PushEngage web push notification"}
{statuscode:22,message:"User not subscribed"}
{statuscode:23,message:"Subscriber is not valid for request api"}
{statuscode:24,message:"Your given segment is not valid"}

Add Profile Id to a Subscribers

Add profile id to a subscriber by passing parameter as a "profileId" and notifications will be sent to only those devices which are having this profile id. Profile id is a user defined name that is used to target particular subscribers with unique IDs.

window._peq.push(['add-to-profile','profileId']);

OR,

window._peq.push(['add-to-profile','profileId',function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res);
    }
}]);

Response

{statuscode:1,message:"Profile added sucessfully"}
{statuscode:2,message:"Profile already exists"}
{statuscode:0,message:"Something went wrong"}
{statuscode:20,message:"Your website url is not allowed, please configure in PushEngage correctly"}
{statuscode:21,message:"Your browser does not support PushEngage web push notification"}
{statuscode:22,message:"User not subscribed"}
{statuscode:23,message:"Subscriber is not valid for request api"}

Note

Using this Profile Id, you can send notification to specific subscribers.

Subscription on Button Click

Subscription on button click allows to get subscription pop up without any delay.

window._peq.push(['subscribe-on-click']);
OR,

window._peq.push(['subscribe-on-click',{}.pe,function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res);
    }
}]);
Response

{statuscode:1,status:"SUBSCRIBED",message:"User subscribed sucessfully",data:{subscriber_hash:"UserUniqueId"}}
{statuscode:2,status:"DENIED",message:"User denied push notification"}
{statuscode:3,status:"CLOSED",message:"User closed subscription Opt-in"}
{statuscode:20,message:"Your website url is not allowed, please configure in PushEngage correctly"}
{statuscode:21,message:"Your browser does not support PushEngage web push notification"}
{statuscode:22,message:"User not subscribed"}

Note

Available for single step opt-in only.

Segment Addition on Button Click

It allows to add segment at the time of subscription without any delay.

window._peq.push(['subscribe-on-click','segmentName']);

OR,

window._peq.push(['subscribe-on-click','segmentName',function(res){
    if(res.statuscode==1)
    {
      // Code to return response
      console.log(res); 
    }
}]);

Response

{statuscode:1,message:"Segment added sucessfully"}
{statuscode:2,message:"Segment already added"}
{statuscode:3,message:"Segment not found"}
{statuscode:0,message:"Something went wrong"}
{statuscode:20,message:"Your website url is not allowed, please configure in PushEngage correctly"}
{statuscode:21,message:"Your browser does not support PushEngage web push notification"}
{statuscode:22,message:"User not subscribed"}
{statuscode:23,message:"Subscriber is not valid for request api"}
{statuscode:24,message:"Your given segment is not valid"}

Note

Available for single step opt-in only.

Attribute Operation on Subscriber

Once you've integrated pushengage in your website, implementing Attribute is very straightforward - simply use the setAttribute/addAttribute/getAttribute/removeAttribute javascript api to work with attribute. To learn more about attributes, please take a look at PushEngage attributes.

Set Attributes

This api is used to set attributes to a subscriber. This will overwrite any other attributes previously associated with current subscriber. Use this api whenever you need to completely reset the attribute to a new values.

var newAttributes = {
  'name': 'Jon smith',
  'isAdmin': true,
  'lastActive': "2019-09-19T05:41:53.150Z",
};

window._peq.push(['set-attributes', newAttributes, function(res){
  if(res.statuscode == 1)
  {
    // handle response
    console.log(res);
  }
}]);
Response
{statuscode: 1, message: "Attribute replaced successfully", data: {…}}
{statuscode: xxxxx, message: "Error message", data: {…}}

Add Attributes

This api is used to add new attributes to the existing attribute of a subscriber. If there is already existing attribute with the given attribute key name then the value will be replaced with new value.

var attribute = {
  'gender': 'female',
  'postCode': '560024',
}
window._peq.push(['add-attributes', attribute, function(res){
 if(res.statuscode == 1)
 {
    // handle response
  console.log(res);
 }
}]);

Response

{statuscode: 1, message: "Attribute added successfully", data: {…}}
{statuscode: xxxxx, message: "Error message", data: {…}}

Get Attributes

Use this api to get the list of attributes associated with current subscriber.

window._peq.push(['get-attributes', function(res){
 if(res.statuscode == 1)
 {
    // handle response
  console.log(res);
 }
}]);

Response

{statuscode: 1, message: "", data: {'name': 'Jon smith','isAdmin': true,'lastActive': "2019-09-19T05:41:53.150Z",'gender': 'female','postCode': '560024'}}
{statuscode: xxxxx, message: "Error message", data: {…}}

Remove Attributes

Use this api to remove one or more attribute associated with current subscriber. The api accept the array of attribute name to remove from current subscriber. If you pass empty array then the api will remove all the attributes associated with subscriber.

// remove all attributes 
window._peq.push(['remove-attributes', [], function(res){
  if(res.statuscode == 1)
 {
    // handle response
  console.log(res);
 }
}]);

// remove name and age associated with current subscriber
window._peq.push(['remove-attributes', ['name', 'age'], function(res){
  if(res.statuscode == 1)
 {
    // handle response
  console.log(res);
 }
}]);
Response

{statuscode: 1, message: "Attribute removed successfully", data: {…}}
{statuscode: xxxxx, message: "Error message", data: {…}}