Web SDK (Legacy)

The Website SDK is the legacy version of our client-side JavaScript library designed for browser environments. It enables push notifications on your website and is not intended for server-side use. Compatible with all major browsers, this library works on both HTTP and HTTPS sites and can easily be added to any website.

The SDK offers various methods and events to enhance your push notification experience. These methods include managing subscriptions, attributes, segments, profile IDs, unsubscription, permission prompts, subscription management widgets, and more. Events capture activities such as permission prompt displayed, allow, close, and interactions with notifications like displayed, click, and close.

info

All methods support a callback. The callback function is optional.

A callback in JavaScript is like asking a friend to call you back once they've finished a task. In the digital world, instead of asking a friend, you tell a function (a set of instructions) to run and, once it's done, to then run another function. This way, you ensure things happen in the order you want and don't have to wait idly in the meantime.

info

The subscriber_hash key in the response has been replaced with subscriber_id. Please note that subscriber_hash will be deprecated in the future.

The geoInfo key in the response has been replaced with geo_info. Please note that geoInfo will be deprecated in the future.

caution

The SDK methods and events will only function if the SDK is installed correctly.

Initialization code

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

JavaScript
window._peq.push(['init']);

Register Callback in Initialization Code

This callback executes after the completion of the subscription process and returns the subscriber hash/ID, status and geo details.

Syntax

JavaScript
window._peq.push(['init', undefined, callbackFunction]);

Parameters

callbackFunction: function (optional)

Usage

JavaScript
window._peq.push([
  'init',
  undefined,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "data": {
    "subscriber_id": "<Subscriber ID>",
    "geo_info": {
      "country": "<Country Name>",
      "state": "<State Name>",
      "city": "<City Name>"
    }
  },
  "message": "<Response Message>",
  "status": "<Status>"
}

Response Object

Property Name	Type	Required	Description
statuscode	Number	Yes	Indicates the response status code.
message	String	Yes	Indicates the response message.
status	String	No	Indicates the push notification permission status for the user.
data	Subscriber	No	Includes additional information like the geo-details of a subscriber, which encompasses country, state, and city. This information is available only when a subscriber is subscribed.

Subscriber Statuscode

statuscode	Description
1	Indicates that the user has successfully subscribed to push notifications.
2	Indicates that the user denied push notification permissions.
3	Indicates that the user either closed the native permission prompt or closed all HTML popup modals. The next popup will appear after the cookie duration.
0	Indicates that the method did not proceed due to an error.
22	Indicates that the user is not subscribed.

Subscriber Status

status	Description
SUBSCRIBED	Indicates that the user has successfully subscribed to push notifications.
DENIED	Indicates that the user denied push notification permissions.
CLOSED	Indicates that the user either closed the native permission prompt or closed all HTML popup modals. The next popup will appear after the cookie duration.
DEFAULT	The user has not been prompted yet to allow or deny notifications.

Subscriber Object

Property Name	Type	Required	Description
subscriber_id	String	No	Represents a unique ID for each subscriber, generated by PushEngage using the subscription details. This ID identifies the subscriber and only changes if the subscription details change. This information is available only when a subscriber is subscribed.
geo_info	Object	No	Include the geo information like country, state, city.
geo_info.country	String	No	Denotes the country from which the subscriber opted in. It's updated 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.
geo_info.state	String	No	Represents the state from which the subscriber opted in. It's updated 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.
geo_info.city	String	No	Denotes the city from which the subscriber opted in. It's updated 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.

Assigning Segments through Initialization Code

You can assign segments during the initialization process. The data type for the segment can be a single string or an array of strings. This capability enables customers to categorize subscribers into specific segments right at the point of subscription. For a more in-depth understanding, please refer to the Segment section.

Syntax

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

Parameters

segmentName: string | string[]

callbackFunction: function (optional)

Usage

JavaScript
var segmentName = 'book';

window._peq.push([
  'init',
  segmentName,
  function (res) {
    console.log(res);
  },
]);

JavaScript
var segmentNames = ['shorts', 'tshirts'];

window._peq.push([
  'init',
  segmentNames,
  function (res) {
    console.log(res);
  },
]);

Config Options

This method allows for the customization of the appearance and behavior of the PushEngage SDK, providing enhanced control for adjustments based on specific pages or conditions. Presently, the configuration API exclusively supports the Subscription Management Widget. All settings specified here take precedence over those configured in the PushEngage Dashboard.

Syntax

window._peq.push([
  'config',
  {
    subscription_management_widget: typeOfSubscriptionManagementWidget,
  },
]);

{
  enabled?: boolean;
  title?: string;
  modal_background_color?: string;
  modal_text_color?: string;
  allow_text?: string;
  on_switch_color?: string;
  off_switch_color?: string;
  trigger_button?: {
    enabled?: boolean;
    size?: 'default' | 'large' | 'small';
    position_x?: 'right' | 'left';
    position_y?: 'bottom' | 'top' | 'center';
    offset_top?: number;
    offset_bottom?: number;
    icon_background_color?: string;
    icon_color?: string;
    icon_type?:
      | 'default'
      | 'bell'
      | 'bell_badge'
      | 'bell_ring'
      | 'bell_circle'
      | 'bell_check'
      | 'bell_plus';
    z_index?: number;
  };
  segment_preference?: {
    enabled?: boolean;
    title?: string;
    segments?: string[];
    checkbox_background_color?: string;
    checkbox_tick_color?: string;
    default_segment_selection?: boolean;
    subscribed_title?: string;
    exclude_subscribed_segments?: string[];
    show_all_subscribed_segment?: boolean;
  };
  unsubscribe_options?: {
    enabled?: boolean;
    confirm_message?: string;
    ok_text?: string;
    cancel_text?: string;
    ok_button_background_color?: string;
    ok_button_text_color?: string;
    cancel_button_background_color?: string;
    cancel_button_text_color?: string;
  };
  personal_notification_options?: {
    enabled?: boolean;
    label?: string;
  };
};

Display Native Permission Prompt / Single Step Opt-in

This method displays the single step opt-in prompt for users. By using this opt-in, users can subscribe to push notifications. It's especially useful when you want to trigger the opt-in through a button or link click. This function accepts an optional parameter as a segment, which can be either a string or an array of strings. Even if all opt-ins are disabled from the PushEngage Dashboard, this method will still function.

Syntax

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

Parameters

segmentName: undefined | string | string[]

callbackFunction: function (optional)

Usage

Without Segment
With Segment

JavaScript
window._peq.push([
  'subscribe-on-click',
  undefined,
  function (res) {
    console.log(res);
  },
]);

JavaScript
var segmentName = 'mobiles';

window._peq.push([
  'subscribe-on-click',
  segmentName,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "data": {
    "subscriber_id": "<Subscriber ID>",
    "geo_info": {
      "country": "<Country Name>",
      "state": "<State Name>",
      "city": "<City Name>"
    }
  },
  "message": "<Response Message>",
  "status": "<Status>"
}

Get User Permission

This method allows you to determine the notification permission status for the current user. The possible values are DEFAULT, SUBSCRIBED, DENIED, or CLOSED.

DEFAULT: The user has not been prompted yet to allow or deny notifications.
SUBSCRIBED: The user has granted permission to receive notifications.
DENIED: The user has opted out of receiving notifications.
CLOSED: This status indicates the user either closed the native opt-in permission prompt or closed all opt-in prompts.

Syntax

JavaScript
window._peq.push(['subscriber-status', callbackFunction]);

Parameters

callbackFunction: function (optional)

Usage

JavaScript
window._peq.push([
  'subscriber-status',
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "data": {
    "subscriber_id": "<Subscriber ID>",
    "geo_info": {
      "country": "<Country Name>",
      "state": "<State Name>",
      "city": "<City Name>"
    }
  },
  "message": "<Response Message>",
  "status": "<Status>"
}

Retrieve Subscriber Details

This method retrieves the user's subscriber details, such as subscriber ID, automated notification status, subscription date, geo information, device, browser details and more. It returns a JSON object with all these details.

Syntax

JavaScript
window._peq.push(['get-subscriber', callbackFunction]);

Parameters

callbackFunction: function (optional)

Usage

JavaScript
window._peq.push([
  'get-subscriber',
  function (res) {
    console.log(res);
  },
]);

Response Object

Property Name	Type	Required	Description
statuscode	Number	Yes	Indicates the response status code.
message	String	No	The message is only available when the statuscode is `0` and indicates the reason for the failure.
data	Subscriber	No	Includes additional information like the geo-details of a subscriber, which encompasses country, state, and city. This information is available only when a subscriber is subscribed.

Subscriber Statuscode

statuscode	Description
1	Indicates the operation was successful.
0	Indicates an error prevented the operation from proceeding.
22	Indicates the user is not subscribed.

Subscriber Object

Property Name	Type	Required	Description
subscriber_id	String	Yes	This represents a unique ID for each subscriber, generated by PushEngage using the subscription details. It identifies the subscriber and only changes if the subscription details change.
subscription_url	String	Yes	This is the URL where the subscriber opted in. It can be either a website URL or a landing page URL.
automated_notification	Boolean	Yes	Indicates if automated/personalized notifications for the user are enabled or disabled. Automated notifications cover all types of triggered campaigns. Further details are in the "Automated Notifications" section.
browser	String	Yes	This denotes the browser in which the subscriber opted in.
timezone	String	Yes	Display 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.
subscription_at	String	Yes	Indicates the subscription date of the subscriber, following the format YYYY-MM-DDTHH:MM:SSZ.
device	String	Yes	Denotes the device type from which the subscriber opted in, such as desktop or mobile.
attributes	Object	Yes	These are 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.
state	String	No	Represents the state from which the subscriber opted in. It's updated 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's updated 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.
profile_id	String	No	This is the unique ID given to the subscriber by the site owner. More insights can be found in the "Profile ID" section.

Unsubscribe Subscriber

This method enables you to unsubscribe the current subscriber from receiving push notifications. Once unsubscribed, the subscriber will no longer receive any push notifications.

Syntax

JavaScript
window._peq.push(['unsubscribe-on-click', callbackFunction]);

Parameters

callbackFunction: function (optional)

Usage

JavaScript
window._peq.push([
  'unsubscribe-on-click',
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>"
}

Segments

Segments are used to group subscribers so that you can send personalized notifications. Segments can be created based on attributes, categories, and more. Each subscriber can belong to up to 50 segments. You can create segments either through the PushEngage Dashboard or using the rest APIs.

Response Object

Property Name	Type	Required	Description
statuscode	Number	Yes	Indicates the response status code.
message	String	Yes	Indicates the response message.

Segment Statuscode

statuscode	Description
1	Indicates the operation was successful.
0	Indicates an error prevented the operation from proceeding.
22	Indicates the user is not subscribed.

Add a Subscriber to Segments

This method allows adding the current subscriber to one or multiple segments.

Syntax

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

Parameters

segmentName: string | string[]

callbackFunction: function (optional)

Usage

JavaScript
var segmentName = 'books';

window._peq.push([
  'add-to-segment',
  segmentName,
  function (res) {
    console.log(res);
  },
]);

JavaScript
var segmentNames = ['shorts', 'tshirts'];

window._peq.push([
  'add-to-segment',
  segmentNames,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>"
}

Add a Subscriber to a Segment with Duration

This method enables you to add the current subscriber to a segment for a specified duration, measured in days. After this period, the segment will be automatically removed from the subscriber.

Syntax

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

Parameters

segmentName: string

days: number

callbackFunction: function (optional)

Usage

JavaScript
var segmentName = 'mobiles';
var days = 5;

window._peq.push([
  'add-to-dynamic-segment',
  segmentName,
  days,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>"
}

Add a Subscriber to Segments with the Duration

This method enables adding the current subscriber to multiple segments for a specified duration in days. After this period, the segments will automatically be removed from the subscriber.

Syntax

JavaScript
window._peq.push([
  'add-to-dynamic-segment',
  segmentNamesWithDuration,
  callbackFunction,
]);

Parameters

segmentNamesWithDuration: object[] {name: string, duration: number}[]

callbackFunction: function (optional)

Usage

JavaScript
var segmentNamesWithDuration = [
  { name: 'computers', duration: 1 },
  { name: 'tablets', duration: 2 },
];

window._peq.push([
  'add-to-dynamic-segment',
  segmentNamesWithDuration,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>"
}

Remove a Subscriber from Segments

This method enables the removal of the current subscriber from one or multiple segments.

caution

The key name remove-to-segment has been renamed to remove-segment, but remove-to-segment will still be supported.

Syntax

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

Parameters

segmentName: string | string[]

callbackFunction: function (optional)

Usage

JavaScript
var segmentName = 'web-stories';

window._peq.push([
  'remove-segment',
  segmentName,
  function (res) {
    console.log(res);
  },
]);

JavaScript
var segmentNames = ['politics', 'matermonial'];

window._peq.push([
  'remove-segment',
  segmentNames,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>"
}

Profile ID to Subscriber

Profile IDs serve as unique identifiers for your subscribers, enabling you to recognize them across multiple devices and browsers. Each subscriber can be assigned just one profile ID. This ID should be a string, and you have the flexibility to use any value, such as an email or phone number.

This method allows you to set a profile ID for the current subscriber. If a profile ID already exists, it will be replaced with the new value.

Response Object

Property Name	Type	Required	Description
statuscode	Number	Yes	Indicates the response status code.
message	String	Yes	Indicates the response message.

Profile ID Statuscode

statuscode	Description
1	Indicates the operation was successful.
0	Indicates an error prevented the operation from proceeding.
22	Indicates the user is not subscribed.

Syntax

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

Parameters

profileId: string

callbackFunction: function (optional)

Usage

JavaScript
var profileId = '[email protected]';

window._peq.push([
  'add-to-profile',
  profileId,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>"
}

Attributes

Attributes are key-value pairs that allow you to store additional information about your subscribers. You can use attributes to segment your subscribers and send personalized notifications. Each subscriber can have a maximum of 50 attributes. The key of an attribute can be up to 64 characters long, and the value can be up to 128 characters long in the case of a string.

You first need to create attributes before using them. You can create them from the PushEngage Dashboard.

Response Object

Property Name	Type	Required	Description
statuscode	Number	Yes	Indicates the response status code.
message	String	Yes	Indicates the response message.
data	Object	No	Includes the existing attributes. This property only appears when the operation succeeds.

Attribute Statuscode

statuscode	Description
1	Indicates the operation was successful.
0	Indicates an error prevented the operation from proceeding.
22	Indicates the user is not subscribed.

Add Attributes to Subscriber

Use this method to add or update attributes for a subscriber. If an attribute with the specified key already exists, the existing value will be replaced.

Syntax

JavaScript
window._peq.push(['add-attributes', attributes, callbackFunction]);

Parameters

attributes: object { [key: string]: string | number | boolean }

callbackFunction: function (optional)

Usage

JavaScript
var attributes = {
  gender: 'female',
  email: '[email protected]',
};

window._peq.push([
  'add-attributes',
  attributes,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "data": {}
}

Set Attributes for Subscriber

This method allows you to set attributes for a subscriber, replacing any previously associated attributes. Use this method when you need to entirely reset the attributes with new values.

Syntax

JavaScript
window._peq.push(['set-attributes', attributes, callbackFunction]);

Parameters

attributes: object { [key: string]: string | number | boolean }

callbackFunction: function (optional)

Usage

JavaScript
var attributes = {
  name: 'Jon smith',
  isAdmin: true,
};

window._peq.push([
  'set-attributes',
  attributes,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "data": {}
}

Get Attributes for Subscriber

Retrieve the attributes associated with the current subscriber using this method.

Syntax

JavaScript
window._peq.push(['get-attributes', callbackFunction]);

Parameters

callbackFunction: function (optional)

Usage

JavaScript
window._peq.push([
  'get-attributes',
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "data": {}
}

Remove Attributes for Subscriber

This method allows you to remove one or more attributes from the current subscriber. Provide an array of attribute names you wish to remove. If no keys are provided, it will result in the removal of all the subscriber's attributes.

Syntax

JavaScript
window._peq.push(['remove-attributes', attributeNames, callbackFunction]);

Parameters

attributeNames: string[] (optional)

callbackFunction: function (optional)

Usage

JavaScript
var attributeNames = ['name'];

window._peq.push([
  'remove-attributes',
  attributeNames,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "data": {}
}

This widget allows subscribers to manage their subscription preferences, including Segment Choices and Automated/personalized Notifications. It can be embedded on any page of your website as needed. Additionally, you can customize the widget's appearance and behavior either from the PushEngage Dashboard or through the Config Options.

Response Object

Property Name	Type	Required	Description
statuscode	Number	Yes	Indicates the response status code.
message	String	Yes	Indicates the response message.

statuscode	Description
1	Indicates the operation was successful.
0	Indicates an error prevented the operation from proceeding.

This method triggers the display of the subscription management widget at the center of the current page. It's particularly useful if you want control over when the widget appears, such as through a custom button or link click. While the default behavior uses a bell design for subscription management.

Syntax

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

Parameters

callbackFunction: function (optional)

Usage

JavaScript
window._peq.push([
  'show-subscription-management-widget',
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "Success or, Error Message"
}

This method removes the subscription management widget from the current page.

Syntax

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

Parameters

callbackFunction: function (optional)

Usage

JavaScript
window._peq.push([
  'remove-subscription-management-widget',
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "Success or, Error Message"
}

Identifying Subscribers

This method allows you to identify subscribers using a unique identifier. The identifier can be an email, phone number, or any other value. This method is particularly useful for recognizing subscribers across multiple devices and browsers. This method accepts fixed keys, the details of which are listed below. If you want to use other keys, use the attributes method.

Key	Type	Required	Description
first_name	String	No	The first name of the subscriber. The maximum length is 32 characters.
last_name	String	No	The last name of the subscriber. The maximum length is 32 characters.
email	String	No	The email address of the subscriber. The maximum length is 128 characters.
phone	String	No	The phone number of the subscriber. It should be in E.164 format. Spaces are not allowed in the phone number.
gender	String	No	The gender of the subscriber. It should be `male`, `female`, or `other`.
dob	String	No	The date of birth of the subscriber. It should be in ISO 8601 format.
language	String	No	The language of the subscriber should be in ISO 639-1 (Alpha-2) codes. ISO 639-1 codes are two-letter codes that represent languages. It should be in lowercase. This field value is always available to subscribers by default.
profile_id	String	No	The unique ID given to the subscriber by the site owner. The maximum length is 64 characters.
country	String	No	The subscriber's country name (maximum length of 64 characters). PushEngage automatically captures this based on the subscriber's IP address. When updating manually, use title case for the country name (e.g., "India", "United States").
city	String	No	The subscriber's city name (maximum length of 64 characters). PushEngage automatically captures this based on the subscriber's IP address. When updating manually, use title case for the city name (e.g., "Mumbai", "New York").
state	String	No	The subscriber's state name (maximum length of 64 characters). PushEngage automatically captures this based on the subscriber's IP address. When updating manually, use title case for the state name (e.g., "Uttar Pradesh", "California").
zip	String	No	The zip code of the subscriber. The maximum length is 16 characters.

Syntax

JavaScript
window._peq.push(['identify', subscriberFields, callbackFunction]);

Parameters

subscriberFields: object { [key: string]: string | number | boolean }

callbackFunction: function (optional)

Usage

JavaScript
var subscriberFields = {
  first_name: 'John',
  last_name: 'Doe',
};

window._peq.push([
  'identify',
  subscriberFields,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>",
  "details": "<The reason for the error in case of failure>"
}

Logout

This method allows you to delete the identifiers that were added through the identifying subscribers API. Provide an array of subscribed field names you wish to remove. If no field names are provided, it will result in the removal of the fields that store personal data, which are first_name, last_name, email, phone, gender, dob, and profile_id.

Syntax

JavaScript
window._peq.push(['logout', subscriberFieldNames, callbackFunction]);

Parameters

subscriberFieldNames: string[] (Optional)

callbackFunction: function (optional)

Usage

JavaScript
var subscriberFieldNames = ['first_name', 'last_name'];

window._peq.push([
  'logout',
  subscriberFieldNames,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>",
  "details": "<The reason for the error in case of failure>"
}

Track Event

Track a custom event for the current subscriber. Custom events are used to trigger or exit workflows based on subscriber activity on your website, such as adding items to a cart, completing a purchase, or any custom action you define.

Prerequisite

The subscriber must already be subscribed to push notifications on the current browser for this method to work.

Server-side alternative

To send events from your server use the Track Event REST API instead.

Syntax

JavaScript
window._peq.push(['track-event', customEvent, callbackFunction]);

Parameters

customEvent: object — the event payload.

Key	Type	Required	Description
event_name	String	Yes	The name of the custom event. Must not start with `PushEngage.` (reserved for internal events). Maximum length is 64 characters.
profile_id	String	No	An optional profile ID to associate with the event. Useful when you have your own user identifiers.
data	Object	No	Key-value pairs sent with the event. Keys must start with a letter or digit and contain only letters, digits, hyphens, or underscores (max 255 characters). Values must be `string`, `number`, `boolean`, or `Date`. Maximum payload size is 4KB.

callbackFunction: function (optional) — called with a response object containing statuscode and message.

Usage

JavaScript
var customEvent = {
  event_name: 'AddToCart',
  data: {
    product_name: 'Running Shoes',
    price: 99.99,
    in_stock: true,
  },
};

window._peq.push([
  'track-event',
  customEvent,
  function (res) {
    console.log(res);
  },
]);

Example of Response from Callback Function
{
  "statuscode": "<Status Code>",
  "message": "<Response Message>"
}

Events

These events allow you to listen to specific actions from the PushEngage SDK. Utilize these events to monitor subscription changes, track permission prompt actions (display, allow, or close), and observe interactions with notifications (display, click, or close).

Subscription Changed

This event monitors changes in subscriptions. It's triggered either when a subscription is received for the first time or when there's a change in the existing subscription. The event details provide the subscriber ID or hash.

This event is beneficial if you intend to store the subscriber ID or hash in your database for tasks such as sending personalized notifications.

Syntax

JavaScript
window.addEventListener('PushEngage.onSubscriptionChange', callbackFunction);

Parameters

callbackFunction: function

Usage

JavaScript
window.addEventListener('PushEngage.onSubscriptionChange', function (event) {
  console.log(event.detail);
});

Example of Event Details Response
{
  "subscriber_id": "<Subscriber ID/Hash>"
}

Permission Prompt Displayed

Track when the permission prompt is displayed to the user using this event. It triggers when either the HTML popup modal or the native browser prompt is shown. The event details specify the prompt type (either 'html' or 'native') and the popup modal's name.

Syntax

JavaScript
window.addEventListener(
  'PushEngage.permissionPrompt.displayed',
  callbackFunction,
);

Parameters

callbackFunction: function

Usage

JavaScript
window.addEventListener(
  'PushEngage.permissionPrompt.displayed',
  function (event) {
    console.log(event.detail);
  },
);

Example of Event Details Response
{
  "prompt": "<native/html>",
  "name": "<Popup Modal Name>"
}

Permission Prompt Allow

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. The details outline the prompt type (either 'html' or 'native') and the popup modal's name.

Syntax

JavaScript
window.addEventListener('PushEngage.permissionPrompt.allow', callbackFunction);

Parameters

callbackFunction: function

Usage

JavaScript
window.addEventListener('PushEngage.permissionPrompt.allow', function (event) {
  console.log(event.detail);
});

Example of Event Details Response
{
  "prompt": "<native/html>",
  "name": "<Popup Modal Name>"
}

Permission Prompt Close

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. The details encapsulate the prompt type (either 'html' or 'native') and the popup modal's name.

Syntax

JavaScript
window.addEventListener('PushEngage.permissionPrompt.close', callbackFunction);

Parameters

callbackFunction: function

Usage

JavaScript
window.addEventListener('PushEngage.permissionPrompt.close', function (event) {
  console.log(event.detail);
});

Example of Event Details Response
{
  "prompt": "<native/html>",
  "name": "<Popup Modal Name>"
}

Notification Displayed

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

Syntax

JavaScript
window.addEventListener('PushEngage.notification.displayed', callbackFunction);

Parameters

callbackFunction: function

Usage

JavaScript
window.addEventListener('PushEngage.notification.displayed', function (event) {
  console.log(event.detail);
});

Example of Event Details Response
{
  "title": "<Title of Notification>"
}

Notification Click

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

Syntax

JavaScript
window.addEventListener('PushEngage.notification.click', callbackFunction);

Parameters

callbackFunction: function

Usage

JavaScript
window.addEventListener('PushEngage.notification.click', function (event) {
  console.log(event.detail);
});

Example of Event Details Response
{
  "title": "<Title of Notification>"
}

Notification Close

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

Syntax

JavaScript
window.addEventListener('PushEngage.notification.close', callbackFunction);

Parameters

callbackFunction: function

Usage

JavaScript
window.addEventListener('PushEngage.notification.close', function (event) {
  console.log(event.detail);
});

Example of Event Details Response
{
  "title": "<Title of Notification>"
}

Web SDK (Legacy)

Initialization code​

Register Callback in Initialization Code​

Syntax​

Parameters​

Usage​

Response Object​

Subscriber Statuscode​

Subscriber Status​

Subscriber Object​

Assigning Segments through Initialization Code​

Syntax​

Parameters​

Usage​

Config Options​

Syntax​

Type of Subscription Management Widget​

Display Native Permission Prompt / Single Step Opt-in​

Syntax​

Parameters​

Usage​

Get User Permission​

Syntax​

Parameters​

Usage​

Retrieve Subscriber Details​

Syntax​

Parameters​

Usage​

Response Object​

Subscriber Statuscode​

Subscriber Object​

Unsubscribe Subscriber​

Syntax​

Parameters​

Usage​

Segments​

Response Object​

Segment Statuscode​

Add a Subscriber to Segments​

Syntax​

Parameters​

Usage​

Add a Subscriber to a Segment with Duration​

Syntax​

Parameters​

Usage​

Add a Subscriber to Segments with the Duration​

Syntax​

Parameters​

Usage​

Remove a Subscriber from Segments​

Syntax​

Parameters​

Usage​

Profile ID to Subscriber​

Response Object​

Profile ID Statuscode​

Syntax​

Parameters​

Usage​

Attributes​

Response Object​

Attribute Statuscode​

Add Attributes to Subscriber​

Syntax​

Parameters​

Usage​

Set Attributes for Subscriber​

Syntax​

Parameters​

Usage​

Get Attributes for Subscriber​

Syntax​

Parameters​

Usage​

Remove Attributes for Subscriber​

Syntax​

Parameters​

Usage​

Initialization code

Register Callback in Initialization Code

Syntax

Parameters

Usage

Response Object

Subscriber Statuscode

Subscriber Status

Subscriber Object

Assigning Segments through Initialization Code

Syntax

Parameters

Usage

Config Options

Syntax

Type of Subscription Management Widget

Display Native Permission Prompt / Single Step Opt-in

Syntax

Parameters

Usage

Get User Permission

Syntax

Parameters

Usage

Retrieve Subscriber Details

Syntax

Parameters

Usage

Response Object

Subscriber Statuscode

Subscriber Object

Unsubscribe Subscriber

Syntax

Parameters

Usage

Segments

Response Object

Segment Statuscode

Add a Subscriber to Segments

Syntax

Parameters

Usage

Add a Subscriber to a Segment with Duration

Syntax

Parameters

Usage

Add a Subscriber to Segments with the Duration

Syntax

Parameters

Usage

Remove a Subscriber from Segments

Syntax

Parameters

Usage

Profile ID to Subscriber

Response Object

Profile ID Statuscode

Syntax

Parameters

Usage

Attributes

Response Object

Attribute Statuscode

Add Attributes to Subscriber

Syntax

Parameters

Usage

Set Attributes for Subscriber

Syntax

Parameters

Usage

Get Attributes for Subscriber

Syntax

Parameters

Usage

Remove Attributes for Subscriber

Syntax

Parameters

Usage

Subscription Management Widget