Engagespot JavaScript Core Library

The Engagespot JavaScript Core Library provides a powerful and easy-to-use interface to interact with the Engagespot Notification API in any JavaScript application. With this library, you can:

- Build a Notification Inbox
- Subscribe users to Web Push Notifications
- Manage User Preferences
- Receive Real-Time Notifications
- Handle Device Metadata
- Utilize Platform Detection
- Implement robust Error Handling

> Note: This library does not provide any UI components. If you're looking for a UI kit for JavaScript, please use our React component or the Browser JavaScript UI Kit.

Table of Contents

- Features
- Installation
- Getting Started
- Usage Examples
- Initializing the Engagespot Instance
- Fetching Notifications
- Handling Real-Time Notifications
- Web Push Notifications
- Managing User Preferences
- Events
- API Reference
- Instance Options
- Notification Service
- Preferences Service
- Web Push Service
- Real-Time Service
- Events Module
- Contributing
- License

Features

- Notification Management: Fetch, read, delete, and manage notifications.
- Real-Time Updates: Receive notifications in real-time using WebSockets.
- Web Push Notifications: Subscribe users to Web Push notifications seamlessly.
- User Preferences: Manage and update user notification preferences.
- Device Metadata: Automatically handle device identification and metadata.
- Platform Detection: Utility functions to detect the user's platform and browser.
- Error Handling: Robust error handling with custom error codes and messages.
- Event Handling: Subscribe to various events like notification received, read, deleted, etc.

Installation

Install the package using npm or yarn:

``bash


Using npm

npm install @engagespot/core

Using yarn

yarn add @engagespot/core
`

Getting Started

Before you start, make sure you have your Engagespot API Key from your Engagespot Dashboard.

Usage Examples

$3

`javascript
import { createInstance } from '@engagespot/core';

const engagespot = createInstance({
apiKey: 'YOUR_ENGAGESPOT_API_KEY',
userId: 'unique_user_identifier',
userSignature: 'optional_user_signature', // If using HMAC authentication
debug: true, // Optional: Enable debug mode
});
`

Parameters:

- apiKey (string): Your Engagespot API Key.
- userId (string): A unique identifier for the user.
- userSignature (string, optional): Required if you have HMAC authentication enabled.
- debug (boolean, optional): Enable debug mode for logging.

$3

`javascript
async function fetchNotifications() {
try {
const response = await engagespot.notification.getByPage({
pageNo: 1,
limit: 10,
});

if (response.error) {
console.error('Error fetching notifications:', response.error);
} else {
const notifications = response.data;
notifications.forEach(notification => {
console.log('Title:', notification.title);
console.log('Message:', notification.message);
});
}
} catch (error) {
console.error('An error occurred:', error);
}
}

fetchNotifications();
`

$3

`javascript
// Subscribe to notification receive events
engagespot.events.notificationReceive.subscribe(({ notification }) => {
console.log('New notification received:', notification);
});

// Start the real-time service
engagespot.realTime.connect();
`

$3

`javascript
async function subscribeToWebPush() {
try {
await engagespot.webPush.subscribe();
console.log('Subscribed to web push notifications');
} catch (error) {
console.error('Failed to subscribe to web push notifications:', error);
}
}

subscribeToWebPush();
`

> Note: Ensure that your application is served over HTTPS and that you have a valid service worker registered.

$3

`javascript
async function updateUserPreferences() {
try {
const preferences = {
// Your preferences object
};

await engagespot.preferences.setPreferences(preferences);
console.log('User preferences updated successfully');
} catch (error) {
console.error('Failed to update preferences:', error);
}
}

updateUserPreferences();
`

$3

Engagespot provides several events you can subscribe to for handling notifications:

- notificationReceive: Fired when a new notification is received.
- notificationDelete: Fired when a notification is deleted.
- notificationRead: Fired when a notification is marked as read.
- notificationSeen: Fired when notifications are marked as seen.
- notificationReadAll: Fired when all notifications are marked as read.
- notificationDeleteAll: Fired when all notifications are deleted.
- notificationStateChange: Fired when a notification's state changes.

Example:

`javascript
// Subscribe to the notificationReceive event
const handleNotificationReceive = ({ notification }) => {
console.log('New notification:', notification);
};

engagespot.events.notificationReceive.subscribe(handleNotificationReceive);

// Unsubscribe from the event
engagespot.events.notificationReceive.unsubscribe(handleNotificationReceive);
`

API Reference

$3

When creating an instance using createInstance(options), the following options are available:

- apiKey (string): Required. Your Engagespot API Key.
- userId (string): Required. A unique identifier for the user.
- tenantIdentifier (string, optional): A unique identifier for multi-tenant applications.
- userSignature (string, optional): Required if HMAC authentication is enabled.
- userToken (string, optional): User token for secure mode.
- disableWebPush (boolean, optional): Disable web push notifications. Default is false.
- allowNonHttpsWebPush (boolean, optional): Allow web push on non-HTTPS sites (for development). Default is false.
- serviceWorkerRegistration (ServiceWorkerRegistration, optional): Custom service worker registration.
- disableRtm (boolean, optional): Disable real-time messaging. Default is false.
- baseUrl (string, optional): Custom base URL for the Engagespot server.
- debug (boolean, optional): Enable debug mode for logging. Default is false.
- disableAutoStart (boolean, optional): Disable automatic start of services. Default is false.

$3

Accessed via engagespot.notification, provides methods to manage notifications.

Methods

- getById(id): Fetch a notification by ID.
- getByPage(params): Fetch notifications with pagination.
- Params can include pageNo, limit, category, filter, and tenantIdentifier.
- markAsRead(id): Mark a notification as read.
- remove(id): Remove a notification.
- markAllAsSeen(): Mark all notifications as seen.
- markAllAsRead(): Mark all notifications as read.
- removeAll(): Remove all notifications.
- changeState({ id, state }): Change the state of a notification.

Example

`javascript
// Mark a notification as read
await engagespot.notification.markAsRead('notification_id');

// Delete a notification
await engagespot.notification.remove('notification_id');
`

$3

Accessed via engagespot.preferences, provides methods to manage user preferences.

Methods

- getPreferences(): Get user preferences.
- setPreferences(preferences): Set user preferences.
- setProfileAttributes(attributes): Set user profile attributes.
- getCategories(): Get notification categories.
- getSupportedChannels(): Get supported notification channels.

Example

`javascript
// Get user preferences
const preferences = await engagespot.preferences.getPreferences();

// Set user preferences
await engagespot.preferences.setPreferences({
// Preference data
});

// Set profile attributes
await engagespot.preferences.setProfileAttributes({
attribute1: 'value1',
attribute2: 'value2',
});
`

$3

Accessed via engagespot.webPush, provides methods to manage web push notifications.

Methods

- connect(): Connect to the web push service.
- isSupported(): Check if web push is supported.
- getRegistrationState(): Get the registration state of web push.
- clearWebPushSubscription(): Clear the web push subscription.
- subscribe(): Subscribe to web push notifications.

Example

`javascript
if (engagespot.webPush.isSupported()) {
await engagespot.webPush.subscribe();
} else {
console.warn('Web push is not supported in this browser.');
}
`

$3

Accessed via engagespot.realTime, provides methods to manage real-time messaging.

Methods

- connect(): Connect to the real-time messaging service.
- disconnect(): Disconnect from the real-time messaging service.

Example

`javascript
// Connect to real-time service
await engagespot.realTime.connect();

// Disconnect when needed
engagespot.realTime.disconnect();
`

$3

Accessed via engagespot.events, allows you to subscribe and unsubscribe to various events.

Available Events

- notificationReceive
- notificationDelete
- notificationRead
- notificationSeen
- notificationReadAll
- notificationDeleteAll
- notificationStateChange
- webPushPermissionChange

Example

`javascript
// Subscribe to web push permission changes
engagespot.events.webPushPermissionChange.subscribe(({ permission }) => {
console.log('Web push permission changed:', permission);
});
``

Contributing

We welcome contributions to the Engagespot JavaScript Core Library! If you have any ideas, suggestions, or issues, please open an issue or pull request on our GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

For more information about Engagespot and its features, please visit our official website or check out our documentation.

If you have any questions or need assistance, feel free to reach out to our support team at support@engagespot.co.