Skip to main content

JS Client SDK (Front-End)

The client-side SDK is mainly used for displaying In-App Notifications and allowing users to see and change their Notification Preferences.

Supported environments:

  • Vanilla JavaScript
  • React
  • Vue
  • Angular
  • Next
  • Remix
  • Most JS Frameworks, including those with server-side rendering, are supported. If you don't see your framework here, just ping us on support and we will add it to the docs!

Setup & Initialization

1. Install
npm install notificationapi-js-client-sdk
# yarn add notificationapi-js-client-sdk
# pnpm add notificationapi-js-client-sdk
2. Import
import NotificationAPI from 'notificationapi-js-client-sdk';
import 'notificationapi-js-client-sdk/dist/styles.css';
3. Initialize
const notificationapi = new NotificationAPI({
clientId: 'YOUR_CLIENT_ID',
userId: 'UNIQUE_USER_ID'
});

Parameters

ParameterTypeDescription
clientId*stringYour NotificationAPI account clientId. You can get it from here.
userId*stringThe unique ID of the user in your system.
userIdHashstringOnly used for Secure Mode.
websocketstringOnly if you want to specify your region, for example, if your account is in Canada region you must pass 'wss://ws.ca.notificationapi.com'.
languagestringThe language used for the pre-built UI widgets. Supported: en-US, es-ES, fr-FR, it-IT, pt-BR

Framework Specific Gotcha's

To prevent unncessary rerenders and reinitialization of the SDK, use the memo function:

import NotificationAPI from 'notificationapi-js-client-sdk';
import 'notificationapi-js-client-sdk/dist/styles.css';
import { PopupPosition } from 'notificationapi-js-client-sdk/lib/interfaces';
import { memo, useEffect } from 'react';

const NotificationAPIContainer = memo((props) => {
useEffect(() => {
const notificationapi = new NotificationAPI({
clientId: 'CLIENT_ID',
userId: props.userId
});
notificationapi.showInApp({
root: 'CONTAINER_DIV_ID',
popupPosition: PopupPosition.BottomLeft
});
}, [props.userId]);

return <div id="CONTAINER_DIV_ID"></div>;
});
export default NotificationAPIContainer;

Service Worker Setup

Only required for Web Push notifications:

Download notificationapi-service-worker.js and place it in the "public" folder of your web application.

getUserPreferences

Returns the user's notification preferences.

notificationapi.getUserPreferences().then((prefs) => {
console.log(prefs);
});

Response Example

[
{
"notificationId": "new_order",
"title": "New Order",
"settings": [
{
"channel": "SMS",
"state": false,
"channelName": "SMS"
},
{
"channel": "EMAIL",
"state": true,
"channelName": "Email"
}
]
}
]

identify

Stores the end-user information for a given user.

By using this function, you can omit the contact information when using send(). NotificationAPI will automatically lookup the user's stored email or phone number and use it for sending the notification. Recommended to call identify() every time the user signs, or upon signup and changing of the user contact info.

notificationapi.identify({
id: 'testId',
email: 'spongebob@squarepants.com'
});

patchUserPreference

Allows you update the user's notification preferences.

notificationapi.patchUserPreference('order_tracking', 'EMAIL', false);

Parameters

ParameterTypeDescription
notificationId*stringThe ID of the notification in NotificationAPI.
channel*stringThe channel for which you wish to change the setting. Accepted values:
EMAIL, INAPP_WEB, SMS, CALL, PUSH, WEB_PUSH
state*booleanThe preference of the user. If set to false, the user will no longer receive the specified notification on the specified channel, until the state is set to true again through the API or the preferences popup.
subNotificationIdstringOnly when using subNotificationIds

showInApp

This function renders the in-app notifications widget on your front-end.

Complete guide: In-App Notifications Widget

notificationapi.showInApp({
root: 'CONTAINER_DIV_ID'
});

Parameters

ParameterTypeDescription
root*stringThe ID of the HTML element that will contain the in-app widget. Ideally an empty div.
inlinebooleanDefault: false. By default, the showInApp() function will display a 🔔 button. The in-app notifications are displayed in a popup when the button is clicked. With inline set to true, the in-app notifications are displayed in the root element without the popup.
markAsReadModestring (JS), MarkAsReadModes enum (TS)Default: AUTOMATIC. In AUTOMATIC mode, in-app notifications are set to read when they are displayed to the user and the unread notification count is reset to 0. Switching to the MANUAL mode will not set notifications to read on display. Instead, the user can set notifications to read using an overall "Mark All As Read" button, or by using the individual "Mark as read" on each notification. The MANUAL_AND_CLICK mode works similar to MANUAL mode, but also sets notifications to read when user clicks the notification. Valid string options: AUTOMATIC, MANUAL, MANUAL_AND_CLICK
popupPositionstring (JS), PopupPosition enum (TS)Default: rightBottom. The position of the notifications popup relative to the button.
paginatedbooleanDefault: false. By default, the in-app notifications are displayed in endless scrolling mode. Setting this field to true will show in-app notifications in paginated mode with controls to change pages.
pageSizenumberDefault: 5. The number of in-app notifications per page. Only valid for paginated mode.

showUserPreferences

This function renders the user preferences widget on your front-end.

Complete guide: User Preferences Widget

notificationapi.showUserPreferences();

Parameters

ParameterTypeDescription
parentstringWhen undefined (default behavior), the user preferences will show as a modal. Given this parameter, the user preferences will render in inline mode inside an existing HTML element on your page. You can pass the ID of the parent element to this parameter. Ideally, use an empty div for the parent.

Parameters

ParameterTypeDescription
id*stringThe unique ID of the user in your system.
emailstringThe email of the user.
phonestringThe phone number of the user. Expected format: +15554443333.

Frequently Asked Questions (FAQs)

Why Can I Not Send Notifications from a Front-end SDK?

NotificationAPI back-end SDKs require your clientId and clientSecret keys that are unique to your account. If anyone else obtained your keys then they would be able to edit or delete your notifications, and be able to send requests to NotificationAPI from your account. This is a security risk to you and your clients.

To better protect you, the NotificationAPI front-end SDKs do not allow sending notifications: they only allow receiving notifications. If you require sending notifications from your front-end, it is recommended to use a NotificationAPI back-end SDK on your back-end and expose an API for your front-end.