Using Javascript Core
Javascript Core package wraps the REST API calls into easy to use functions for any Javascript app. With this package, you can build Notification Inbox, Subscribe users to web push, build preference manager etc.
Javascript core library doesn't provide any UI components. If you're looking for UI-Kit for Javascript, you should use our React component or Browser Javascript UI Kit.
Quick Setup
Before we start, make sure you have Engagespot API Key from your dashboard. Now, let's install the core package, and initialize.
npm i @engagespot/core --save
#or
yarn add @engagespot/core
Initializing the SDK
import Engagespot from '@engagespot/core';
const engagespot = new Engagespot('YOUR_ENGAGESPOT_API_KEY', {
userId: 'youruser@example.com',
});
Fetching notifications
const notificationList = engagespot.getNotificationList();
await notificationList.fetch();
notificationList.data.forEach(notification => {
console.log(notification.title, notification.message);
});
To fetch notification list, you should use the getNotificationList()
method, which returns the NotificationList
object. Note that, the NotificationList
object will be empty, and you need to call the fetch()
method to pull the latest notification data from server.
We've seen this in the example above. After calling fetch()
which returns Promise<this>
, you can access the notifications from data[]
Let's learn more about NotificationList
class below.
Engagespot Class
This class is used to create a new Engagespot instance.
Constructor
The constructor accepts the following arguments.
Property | Type | Description |
---|---|---|
apiKey | string | Engagespot API Key |
options | Object | Options Object. (Properties explained below) |
options.userId | string | Any unique identifier to identify your app user |
options.userSignature | string | Required if your app has HMAC Authentication turned on. |
options.serviceWorkerRegistration | ServiceWorkerRegistration | Use this if your app has an existing Service Worker Registration |
Web Push Notification
Core Javascript API also includes methods to enable web push notifications via the default_webpush
provider. If you have enabled default_webpush
provider in your Engagespot, you can make use of the following methods to work with the web push functionality.
The following methods are available in the Engagespot
class.
httpsWebPushSubscribe()
This function triggers the web push subscription prompt and attaches the subscription with Engagespot. After this, the user can receive web push notifications.
Make sure you have enabled web push for your app in Engagespot dashboard, and the service worker setup is completed. Otherwise, this error will be shown - ES1005 - A service worker must be registered before push can be subscribed
Preference Manager
Using Core Javascript API, you can build a custom notification preference manager for your users. To learn more about how to build a notification preference manager, read this guide.
Event Listeners
Engagespot Core emits several events which you can susbcribe to do custom actions.
onNotificationReceive
import Engagespot from '@engagespot/core';
const engagespot = new Engagespot('YOUR_ENGAGESPOT_API_KEY', {
userId: 'youruser@example.com',
});
engagespot.onNotificationReceive(notification => {
//You'll get the notification object.
});
onNotificationClick
onNotificationClick() is deprecated. Use onNotificationRead
instead.
onNotificationRead
import Engagespot from '@engagespot/core';
const engagespot = new Engagespot('YOUR_ENGAGESPOT_API_KEY', {
userId: 'youruser@example.com',
});
engagespot.onNotificationRead(notification => {
//You'll get the notification object.
});
onNotificationDelete
import Engagespot from '@engagespot/core';
const engagespot = new Engagespot('YOUR_ENGAGESPOT_API_KEY', {
userId: 'youruser@example.com',
});
engagespot.onNotificationDelete(notification => {
//You'll get the notification object.
});
onNotificationSee
import Engagespot from '@engagespot/core';
const engagespot = new Engagespot('YOUR_ENGAGESPOT_API_KEY', {
userId: 'youruser@example.com',
});
engagespot.onNotificationSee(notification => {
//You'll get the notification object.
});
NotificationList Class
Notification list is a collection of Notifications. It implements the NotificationItem
interface.
export interface NotificationList {
unreadCount: number;
totalCount: number;
data: NotificationItem[];
fetch: (page: number, itemsPerPage: number) => Promise<this>;
markAllAsSeen: () => Promise<this>;
}
Properties
The NotificationList
interface has the following properties.
unreadCount
Number of unseen notifications in the list.
totalCount
Total number of notifications in the list
Methods
fetch
Fetches the notifications from the server and add them to the data[]
property.
NotificationItem Interface
NotificationItem
interface represents a single notification entity. It has several properties and methods to do actions on that particular notification.
interface NotificationItem {
id: string;
title: string;
message?: string | null;
icon?: string | null;
url?: string | null;
seenAt?: string | null;
clickedAt?: string | null;
createdAt?: string | null;
data?: T | null;
fetch?: () => Promise<this> // This will mark the notification as seen.
markAsClicked?: () => Promise<this> //@deprecated. Use markAsRead() instead.
markAsRead?: () => Promise<this>
markAsUnSeen?: () => Promise<this>
markAsUnRead? () => Promise<this>
delete? () => Promise<this>
}
Properties
The NotificationItem
interface has the following properties.
id
Id of the notification
title
Title of the notification
message
Body of notification. This can be null.
icon
URL of the notification icon. This can be null.
seenAt
Timestamp of seen event of this notification. This can be null.
clickedAt
Timestamp of click event of this notification. This can be null.
createdAt
Timestamp of created event of this notification.
data
The data object passed to the send notifications API.
Methods
The NotificationItem
interface has the following methods.
fetch()
Calls GET /notifications/:notificationId
API and sets the properties of this class.
markAsClicked()
markAsClicked() method is deprecated. Use markAsRead()
instead
markAsRead()
Calls POST /notifications/:notificationId/click
API and marks this notification as read.
markAsUnSeen()
Calls DELETE /notifications/:notificationId/views
API and marks this notification as unseen.
markAsUnRead()
Calls DELETE /notifications/:notificationId/reads
API and marks this notification as unread.
delete()
Calls DELETE /notifications/:notificationId
API and deletes this notification.