@engagespot/core NPM

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.

Features
Installation
Getting Started
Usage Examples
API Reference
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:

# 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

Initializing the Engagespot Instance

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.

Fetching Notifications

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();

Handling Real-Time Notifications

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

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

Web Push Notifications

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.

Managing User Preferences

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();

Events

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:

// 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

Instance Options

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.

Notification Service

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

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

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

Preferences Service

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

// 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',
});

Web Push Service

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

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

Real-Time Service

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

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

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

Events Module

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

Available Events

notificationReceive
notificationDelete
notificationRead
notificationSeen
notificationReadAll
notificationDeleteAll
notificationStateChange
webPushPermissionChange

Example

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