JavaScript API

Getting Started

The PushEngage JavaScript 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.

Register Callback for New Subscription

window._peq.push([
  "init",
  false,
  function (res) {
    if (res.statuscode == 1) {
      console.log(res);
    }
  },
]);

Subscriber Hash for New Subscription

window._peq.push([
  "init",
  false,
  function (res) {
    if (res.statuscode == 1) {
      console.log(res.subscriber_hash);
    }
  },
]);

Geo Information for New Subscription

window._peq.push([
  "init",
  false,
  function (res) {
    if (res.statuscode == 1) {
      console.log(res.data.geoInfo);
    }
  },
]);

Response

{statuscode:1,status:"SUBSCRIBED",message:"User subscribed successfully",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) {
      console.log(res);
    }
  },
]);

Response

{statuscode:1,status:"SUBSCRIBED",message:"User subscribed successfully",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 Audience → Segments.

Case a: Add a segment to a subscriber at the time of subscription by passing parameter as a "segmentName", It's data type can be string or, array of string.

Without callbackWith callback

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

window._peq.push([
  "init",
  ["segmentName1", "segmentName2"],
  function (res) {
    if (res.statuscode == 1) {
      console.log(res);
    }
  },
]);

Response

{statuscode:1,status:"SUBSCRIBED",message:"User subscribed successfully",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", It's data type can be string or, array of string.

Without callbackWith callback

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

window._peq.push([
  "add-to-segment",
  ["segmentName1", "segmentName2"],
  function (res) {
    if (res.statuscode == 1) {
      console.log(res);
    }
  },
]);

Response

{statuscode:1,message:"Segment added successfully"}
{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

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.

Without callbackWith callback

var days = 5;
window._peq.push(["add-to-dynamic-segment", "segmentName", days]);

or,

var dynamicSegments = [
  { name: "segment1", duration: 10 },
  { name: "segment2", duration: 20 },
  { name: "segment3", duration: 30 },
];
window._peq.push(["add-to-dynamic-segment", dynamicSegments]);

var days = 5;
var callback = function(res) {
    if (res.statuscode == 1) {
        console.log(res);
    }
}
window._peq.push(["add-to-dynamic-segment", "segmentName", days, callback]);

or,

var dynamicSegments = [
  { name: "segment1", duration: 10 },
  { name: "segment2", duration: 20 },
  { name: "segment3", duration: 30 },
];
var callback = function(res) {
    if (res.statuscode == 1) {
        console.log(res);
    }
}
window._peq.push(["add-to-dynamic-segment", dynamicSegments, callback]);

Response

{statuscode:1,message:"Segment added successfully"}
{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 or days is not valid"}

Remove a Segment to a Subscriber

Remove a subscriber from a segment by passing parameter as a "segmentName", It's data type can be string or, array of string.

Without callbackWith callback

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

window._peq.push([
  "remove-to-segment",
  ["segmentName1", "segmentName2"],
  function (res) {
    if (res.statuscode == 1) {
      console.log(res);
    }
  },
]);

Response

{statuscode:1,message:"Segment removed successfully"}
{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 Subscriber

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.

Without callbackWith callback

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

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

Response

{statuscode:1,message:"Profile added successfully"}
{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.

Without callbackWith callback

window._peq.push(["subscribe-on-click"]);

window._peq.push([
  "subscribe-on-click",
  {}.pe,
  function (res) {
    if (res.statuscode == 1) {
      console.log(res);
    }
  },
]);

Response

{statuscode:1,status:"SUBSCRIBED",message:"User subscribed successfully",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"}

Segment Addition on Button Click

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

Without callbackWith callback

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

window._peq.push([
  "subscribe-on-click",
  "segmentName",
  function (res) {
    if (res.statuscode == 1) {
      console.log(res);
    }
  },
]);

Response

{statuscode:1,message:"Segment added successfully"}
{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"}

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) {
      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) {
      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) {
      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 attributesRemove by name attributes

window._peq.push([
  "remove-attributes",
  [],
  function (res) {
    if (res.statuscode == 1) {
      console.log(res);
    }
  },
]);

window._peq.push([
  "remove-attributes",
  ["name", "age"],
  function (res) {
    if (res.statuscode == 1) {
      console.log(res);
    }
  },
]);

Response

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

Get Subscriber Details

Use this API to get subscriber details like segments, city, country, state, device, device type, timezone, created date and so on.

Without callbackWith callback

window._peq.push(["get-subscriber", callback]);

window._peq.push([
  "get-subscriber",
  { fields: ["segments", "city", "country", "device", "state", "timezone"] },
  callback,
]);

Response

{
  statuscode: 1,
  data: {
    segments:["news"],
    city: "Bangalore",
    country: "India",
    device: "desktop",
    device_type: "chrome",
    host: "pushengage.com",
    state: "Karnataka",
    subscription_url: "https://pushengage.com",
    timezone: "+05:30",
    ts_created: "2020-08-14T11:23:16.761Z",
  },
}
{statuscode:2,message:"subscriber 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"}

Subscription Management Widget Config

This widget provides an easy option for your users to manage push permissions. They can also opt in and opt out of the segments. Using JS API override existing configured settings.

Override only in case of settings enabled from dashboard.

Config Object

{
  "title": "Push Notification Settings",
  "modal_background_color": "#ffffff",
  "modal_text_color": "#111b21",
  "allow_text": "Show Notifications",
  "on_switch_color": "#3b43ff",
  "off_switch_color": "#bfbfbf",
  "enabled": true | false,
  "trigger_button": {
    "enabled": true | false,
    "size": "default" | "large" | "small,
    "position_x": "right" | "left",
    "position_y": "bottom" | "center" | "top",
    "offset_top": 100,
    "offset_bottom": 100,
    "icon_background_color": "#3b43ff",
    "icon_color": "#ffffff",
    "z_index": 99999
  },
  "segment_preference": {
    "enabled": true | false,
    "title": "Segment Preferences",
    "segments": [],
    "checkbox_background_color": "#ecebee",
    "checkbox_tick_color": "#4F00FF",
    "default_segment_selection": true | false
  },
  "unsubscribe_options": {
    "enabled": true | false,
    "confirm_message": "Are you sure? You will miss out on all our updates!",
    "ok_text": "Yes",
    "cancel_text": "No",
    "ok_button_background_color": "#3b43ff",
    "ok_button_text_color": "#ffffff",
    "cancel_button_background_color": "#ffffff",
    "cancel_button_text_color": "#47485d"
  },
  "personal_notification_options": {
    "enabled": true | false,
    "label": "Allow Personalized Notifications"
  }
}

Example

var subscriptionManagementWidget = {
  title: "New Notification setting",
  trigger_button: {
    enabled: false,
  },
};

window._peq.push([
  "config",
  { subscription_management_widget: subscriptionManagementWidget },
]);

Trigger Subscription Management Widget on Button Click

Show WidgetRemove Widget

window._peq.push(['show-subscription-management-widget']);

window._peq.push(['remove-subscription-management-widget']);