Web SDK

The Website SDK is the latest 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 return a promise.

When we say a method returns a "promise," think of it as a system's commitment to give you a result in the future. It's a way in coding to handle tasks that might not complete immediately. A promise ensures that once the task completes, you'll either get the expected result or be informed about an error.

caution

The SDK methods and events will only function if the SDK is installed correctly. There are multiple ways to install the SDK; please visit the PushEngage Dashboard for instructions.

Initialization Options

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

JavaScript
PushEngage.push([
  'init',
  {
    appId: 'Your Site App ID',
    // Other initialization options
  },
]);

The SDK can be initialized with the following options:

Property Name	Type	Required	Description
appId	String	Yes	A unique ID for the site. The SDK uses this ID to identify the corresponding site.
disabledDefaultPrompt	Boolean	No	Determines whether the default prompt is displayed. When set to true, the default prompt will not be displayed to the user. The default value is false. This option provides site owners with the ability to control the display of the popup, allowing for custom triggering, such as a button or link click. Since its default value is false, the popup modal will appear by default.
segment	String \| String[]	No	Allows customers to assign a segment or multiple segments to subscribers during the subscription process. For more details, refer to the Segment section.

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

JavaScript
updateAppConfig(config);

Parameters

config: object { subscriptionManagementWidget?: SubscriptionManagementWidget }

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.updateAppConfig({
    subscriptionManagementWidget: { enabled: false },
  });
});

{
  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
showNativePermissionPrompt(params)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

params: object (optional) { segment?: string | string[] }

successFunctionCallback: function

errorFunctionCallback: function

Usage

Without Segment
With Segment

JavaScript
PushEngage.push(function () {
  PushEngage.showNativePermissionPrompt()
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

JavaScript
var segmentName = 'sports';

PushEngage.push(function () {
  PushEngage.showNativePermissionPrompt({ segment: segmentName })
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "is_permission_changed": "<Boolean>",
  "permission": "<Current permission of subscriber>",
  "subscriber_id": "<Subscriber ID/Hash>",
  "geo_info": {
    "country": "<Country>",
    "state": "<State>",
    "city": "<City>"
  }
}

Response Object

Property Name	Type	Required	Description
permission	String	Yes	Indicates the push notification permission status for the user. It can be one of the following values: `granted`: The user has granted permission to receive push notifications. `denied`: The user has denied permission to receive push notifications. `default`: The user has not yet granted or denied permission to receive push notifications.
is_permission_changed	Boolean	Yes	Indicates whether the user's permission status has changed. The possible values are: `true`: The user's permission status has changed. `false`: The user's permission status remains the same. For instance, if a user newly grants permission to receive push notifications, `is_permission_changed` will return `true`. However, if a user who has already granted permission attempts to subscribe again, `is_permission_changed` will return `false`.
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.

This method triggers a popup modal for users, depending on the dashboard's popup settings. If the popup has been disabled from the dashboard, invoking this method will have no effect. It's particularly valuable if you intend to display the popup at a specific time, rather than immediately on page load.

note

To make this method effective, you must initialize the SDK with the disabledDefaultPrompt option set to disable the popup on page load. See the disabledDefaultPrompt property in the initialization code for more details.

Syntax

JavaScript
showPermissionPrompt()
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.showPermissionPrompt()
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "is_permission_changed": "<Boolean>",
  "permission": "<Current permission of subscriber>",
  "subscriber_id": "<Subscriber ID/Hash>",
  "geo_info": {
    "country": "<Country>",
    "state": "<State>",
    "city": "<City>"
  }
}

Response Object

Property Name	Type	Required	Description
permission	String	Yes	Indicates the push notification permission status for the user. It can be one of the following values: `granted`: The user has granted permission to receive push notifications. `denied`: The user has denied permission to receive push notifications. `default`: The user has not yet granted or denied permission to receive push notifications.
is_permission_changed	Boolean	Yes	Indicates whether the user's permission status has changed. The possible values are: `true`: The user's permission status has changed. `false`: The user's permission status remains the same. For instance, if a user newly grants permission to receive push notifications, `is_permission_changed` will return `true`. However, if a user who has already granted permission attempts to subscribe again, `is_permission_changed` will return `false`.
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.

Retrieve Subscriber ID

This method retrieves the unique subscriber ID for a user. PushEngage generates this ID for every user based on their subscription data. Sometimes, this ID is referred to as the 'subscriber_hash'. The subscriber ID remains consistent unless there's a change in the user's subscription. If the user is not subscribed, it will return a null value.

Syntax

JavaScript
getSubscriberId().then(successFunctionCallback).catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.getSubscriberId()
    .then(function (subscriberId) {
      console.log(subscriberId);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

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. It operates only for subscribed users; otherwise, it throws an error.

Syntax

JavaScript
getSubscriber().then(successFunctionCallback).catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.getSubscriber()
    .then(function (subscriber) {
      console.log(subscriber);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Response 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.

Check Push Notification Support in Browser

This method checks whether the browser supports push notifications. It returns a boolean value.

Syntax

JavaScript
isPushNotificationSupported()
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.isPushNotificationSupported()
    .then(function (status) {
      console.log(status);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

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
unsubscribe().then(successFunctionCallback).catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.unsubscribe()
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

Get User Permission

This method enables you to determine the current user's permission status for notifications. The possible values are default, granted, or denied.

default: The user has not been prompted yet to allow or deny notifications.
granted: The user has given permission to receive notifications.
denied: The user has chosen not to receive notifications.

Syntax

JavaScript
getPermission().then(successFunctionCallback).catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.getPermission()
    .then(function (notificationPermission) {
      console.log(notificationPermission);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Automated/Personalized Notifications

Automated notifications include all types of triggered campaigns, such as cart abandonment, price drop, back in stock, and browse abandonment. By default, automated notifications are enabled for all subscribers.

Enabled Automated Notifications for Subscriber

This method allows you to enable automated notifications for the current subscriber.

Syntax

JavaScript
automatedNotification(params: { status: 'enabled' })
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

params: object { status: 'enabled' }

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.automatedNotification({ status: 'enabled' })
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

Disabled Automated Notifications for Subscriber

This method allows you to disable automated notifications for the current subscriber.

The subscriber will still receive other types of notifications such as Push Broadcasts, Drip Autoresponders, RSS auto push notifications, and more.

Syntax

JavaScript
automatedNotification(params: { status: 'disabled' })
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

params: object { status: 'disabled' }

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.automatedNotification({ status: 'disabled' })
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "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.

Add a Subscriber to Segments

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

Syntax

JavaScript
addSegment(segmentName)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

segmentName: string | string[]

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
var segmentName = 'books';

PushEngage.push(function () {
  PushEngage.addSegment(segmentName)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

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

PushEngage.push(function () {
  PushEngage.addSegment(segmentNames)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "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
addSegmentWithDuration(segmentNameWithDuration)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

segmentNameWithDuration: object { name: string, duration: number }

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
var segmentNameWithDuration = {
  name: 'mobiles',
  duration: 1,
};

PushEngage.push(function () {
  PushEngage.addSegmentWithDuration(segmentNameWithDuration)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

Add a Subscriber to Segments with 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
addSegmentWithDuration(segmentNamesWithDuration)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

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

successFunctionCallback: function

errorFunctionCallback: function

Usage

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

PushEngage.push(function () {
  PushEngage.addSegmentWithDuration(segmentNamesWithDuration)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

Remove a Subscriber from Segments

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

Syntax

JavaScript
removeSegment(segmentName)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

segmentName: string | string[]

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
var segmentName = 'web-stories';

PushEngage.push(function () {
  PushEngage.removeSegment(segmentName)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

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

PushEngage.push(function () {
  PushEngage.removeSegment(segmentNames)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "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.

Syntax

JavaScript
setProfileId(profileId)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

profileId: string

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
var profileId = '[email protected]';

PushEngage.push(function () {
  PushEngage.setProfileId(profileId)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "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.

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
addAttributes(attributes)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

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

successFunctionCallback: function

errorFunctionCallback: function

Usage

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

PushEngage.push(function () {
  PushEngage.addAttributes(attributes)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

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
setAttributes(attributes)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

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

successFunctionCallback: function

errorFunctionCallback: function

Usage

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

PushEngage.push(function () {
  PushEngage.setAttributes(attributes)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

Get Attributes for Subscriber

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

Syntax

JavaScript
getAttributes().then(successFunctionCallback).catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.getAttributes()
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "attribute_name": "<Attribute Value>"
  ....
  ....
}

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
removeAttributes(attributeNames)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

attributeNames: string[] (optional)

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
var attributeNames = ['name'];

PushEngage.push(function () {
  PushEngage.removeAttributes(attributeNames)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

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.

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
showSubscriptionManagementWidget()
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.showSubscriptionManagementWidget()
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

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

Syntax

JavaScript
removeSubscriptionManagementWidget()
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

successFunctionCallback: function

errorFunctionCallback: function

Usage

JavaScript
PushEngage.push(function () {
  PushEngage.removeSubscriptionManagementWidget()
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response 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
identify(subscriberFields)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

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

successFunctionCallback: function

errorFunctionCallback: function

Usage

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

PushEngage.push(function () {
  PushEngage.identify(subscriberFields)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

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
logout(subscriberFieldNames)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

Parameters

subscriberFieldNames: string[] (optional)

successFunctionCallback: function

errorFunctionCallback: function

Usage

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

PushEngage.push(function () {
  PushEngage.logout(subscriberFieldNames)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

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. If the subscriber is not subscribed, the promise will be rejected.

Server-side alternative

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

Syntax

JavaScript
trackEvent(customEvent)
  .then(successFunctionCallback)
  .catch(errorFunctionCallback);

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.

successFunctionCallback: function — called with the response on success.

errorFunctionCallback: function — called with an error object containing message and details.

Usage

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

PushEngage.push(function () {
  PushEngage.trackEvent(customEvent)
    .then(function (response) {
      console.log(response);
    })
    .catch(function (error) {
      console.log(error.message, error.details);
    });
});

Example of Success Response
{
  "message": "<Response Message>"
}

Errors

Error	Cause
`Event name is required.`	`event_name` is missing or empty.
`Event data property must be an object.`	`data` is present but not a plain object.
`Invalid event data key(s): ...`	A key in `data` does not match the required pattern (must start with a letter or digit, contain only letters, digits, hyphens, or underscores, max 255 characters).
`Event data values must be strings, numbers, booleans, or Date objects.`	A value in `data` is not a string, number, boolean, or Date.
`"data" size can not be more than 4KB.`	The serialized `data` object exceeds 4KB.

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

Initialization Options​

Config Options​

Syntax​

Parameters​

Usage​

Type of Subscription Management Widget​

Display Native Permission Prompt / Single Step Opt-in​

Syntax​

Parameters​

Usage​

Response Object​

Triggering the Popup Modal​

Syntax​

Parameters​

Usage​

Response Object​

Retrieve Subscriber ID​

Syntax​

Parameters​

Usage​

Retrieve Subscriber Details​

Syntax​

Parameters​

Usage​

Response Object​

Check Push Notification Support in Browser​

Syntax​

Parameters​

Usage​

Unsubscribe Subscriber​

Syntax​

Parameters​

Usage​

Get User Permission​

Syntax​

Parameters​

Usage​

Automated/Personalized Notifications​

Enabled Automated Notifications for Subscriber​

Syntax​

Parameters​

Usage​

Disabled Automated Notifications for Subscriber​

Syntax​

Parameters​

Usage​

Segments​

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 Duration​

Syntax​

Parameters​

Usage​

Remove a Subscriber from Segments​

Syntax​

Parameters​

Usage​

Profile ID to Subscriber​

Syntax​

Parameters​

Usage​

Attributes​

Add Attributes to Subscriber​

Syntax​

Parameters​

Usage​

Set Attributes for Subscriber​

Syntax​

Parameters​

Usage​

Get Attributes for Subscriber​

Syntax​

Parameters​

Initialization Options

Config Options

Syntax

Parameters

Usage

Type of Subscription Management Widget

Display Native Permission Prompt / Single Step Opt-in

Syntax

Parameters

Usage

Response Object

Triggering the Popup Modal

Syntax

Parameters

Usage

Response Object

Retrieve Subscriber ID

Syntax

Parameters

Usage

Retrieve Subscriber Details

Syntax

Parameters

Usage

Response Object

Check Push Notification Support in Browser

Syntax

Parameters

Usage

Unsubscribe Subscriber

Syntax

Parameters

Usage

Get User Permission

Syntax

Parameters

Usage

Automated/Personalized Notifications

Enabled Automated Notifications for Subscriber

Syntax

Parameters

Usage

Disabled Automated Notifications for Subscriber

Syntax

Parameters

Usage

Segments

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 Duration

Syntax

Parameters

Usage

Remove a Subscriber from Segments

Syntax

Parameters

Usage

Profile ID to Subscriber

Syntax

Parameters

Usage

Attributes

Add Attributes to Subscriber

Syntax

Parameters

Usage

Set Attributes for Subscriber

Syntax

Parameters

Usage

Get Attributes for Subscriber

Syntax

Parameters

Usage