@suprsend/web-sdk

SuprSend Javascript Web SDK

This library is used to integrate SuprSend features like WebPush, Preferences and InApp feed in to your javascript client environments.

📘 Upgrading major version of SDK

• Please refer migration guide if you are migrating the major version of SDK.

Documentation

• Checkout detailed documentation for this library.
• Refer type definitions for this library here.

Installation

# using npm
npm install @suprsend/web-sdk@latest

# using yarn
yarn add @suprsend/web-sdk@latest

Integration

1. Create Client

Create suprSendClient instance and use same instance to access all the methods of SuprSend library.

import {SuprSend} from '@suprsend/web-sdk';

export const suprSendClient = new SuprSend(publicApiKey: string);

Params	Description
publicApiKey*	This is public Key used to authenticate api calls to SuprSend. Get it in SuprSend dashboard ApiKeys -> Public Keys section

2. Authenticate user

Authenticate user so that all the actions performed after authenticating will be w.r.t that user. This is mandatory step and need to be called before using any other method. This is usually performed after successful login and on reload of page to re-authenticate user (can be changed based on your requirement).

const authResponse = await suprSendClient.identify(
  distinctId: any,
  userToken?: string, // only needed in production environments for security
  { refreshUserToken: (oldUserToken: string, tokenPayload: Dictionary) => Promise<string> }
);

Properties	Description
distinctId*	Unique identifier to identify a user across platform.
userToken	Mandatory when enhanced security mode is on. This is ES256 JWT token generated in your server-side. Refer docs to create userToken.
refreshUserToken	This function is called by SDK internally to get new userToken before existing token is expired. The returned string is used as the new userToken.

3. Reset user

This will remove user data from SuprSend instance similar to logout action.

await suprSendClient.reset();

User Methods

Use these methods to manipulate user properties and notification channel data of user

await suprSendClient.user.addEmail(email: string)
await suprSendClient.user.removeEmail(email: string)

// mobile should be as per E.164 standard
await suprSendClient.user.addSms(mobile: string)
await suprSendClient.user.removeSms(mobile: string)

// mobile should be as per E.164 standard
await suprSendClient.user.addWhatsapp(mobile: string)
await suprSendClient.user.removeWhatsapp(mobile: string)

// set custom user properties
await suprSendClient.user.set(arg1: string | Dictionary, arg2?: unknown)

// set properties only once that cannot be overridden
await suprSendClient.user.setOnce(arg1: string | Dictionary, arg2?: unknown)

// increase or decrease property by given value
await suprSendClient.user.increment(arg1: string | Dictionary, arg2?: number)

// Add items to list if user property is list
await suprSend.user.append(arg1: string | Dictionary, arg2?: unknown)

// Remove items from list if user property is list.
await suprSend.user.remove(arg1: string | Dictionary, arg2?: unknown)

// remove user property. If channel needs to be removed pass $email, $sms, $whatsapp
await suprSend.user.unset(arg: string | string[])

//2-letter language code in "ISO 639-1 Alpha-2" format e.g. en (for English)
await suprSendClient.user.setPreferredLanguage(language: string)

// set timezone property at user level in IANA timezone format
await suprSendClient.user.setTimezone(timezone: string)

Triggering Events

const response = await suprSendClient.track(event: string, properties?: Dictionary)

Webpush Setup

1. Configuration

While creating SuprSend instance you have to pass vapidKey (get it in SuprSend Dashboard --> Vendors --> WebPush).

If you want to customise serviceworker file name instead of serviceworker.js, you can pass name of it in swFileName.

new SuprSend(publicApiKey: string, {vapidKey?: string, swFileName?: string})

2. Add ServiceWorker file

Service worker file is the background worker script which handles push notifications.

Create serviceworker.js file such that it should be publicly accessible from https://<your_domain>/serviceworker.js. Then include below lines of code and replace publicApiKey with key you find in API Keys page in SuprSend Dashboard.

importScripts(
  'https://cdn.jsdelivr.net/npm/@suprsend/web-sdk@3.0.3/public/serviceworker.min.js'
);

initSuprSend(publicApiKey);

3. Register Push

Call registerPush in your code, which will perform following tasks:

• Ask for notification permission.
• Register push service and generate webpush token.
• Send webpush token to SuprSend.

const response = await suprSendClient.webpush.registerPush();

Preferences

// get full user preferences data
const preferencesResp = await suprSendClient.user.preferences.getPreferences(args?: {tenantId?: string});

// update category level preference
const updatedPreferencesResp = await suprSendClient.user.preferences.updateCategoryPreference(category: string, preference: 'opt_in'|'opt_out', args?: { tenantId?: string });

// update category level channel preference
const updatedPreferencesResp = await suprSendClient.user.preferences.updateChannelPreferenceInCategory(channel: string, preference: 'opt_in'|'opt_out', category: string, args?: { tenantId?: string });

// update overall channel level preference
const updatedPreferencesResp = await suprSendClient.user.preferences.updateOverallChannelPreference(channel: string, preference: 'all'|'required');

All preferences update api's are optimistic updates. Actual api call will happen in background with 1 second debounce. Since its a background task SDK also provides event listener to get updated preference data based on api call status.

// listen for update in preferences data and update your UI accordingly in callback
suprSendClient.emitter.on('preferences_updated', (preferenceDataResp) => void);

// listen for errors and show error state like toast etc
suprSendClient.emitter.on('preferences_error', (errorResp) => void);

InApp Feed

Initialise feed client

const feedClient: Feed = suprSendClient.feed.initialize(options?: IFeedOptions);

interface IFeedOptions {
  tenantId?: string;
  pageSize?: number;
  stores?: IStore[] | null;
  host?: { socketHost?: string; apiHost?: string };
}

Feed Client

Get Feed Data

This returns notification store which contains list of notifications and other meta data like page information etc. You can call this anytime to get updated store data.

const feedData: IFeedData = feedClient.data;

Initialize socket for realtime update

feedClient.initializeSocketConnection();

Fetching notification data

This method will get first page of notifications from SuprSend server and set data in notification store.

feedClient.fetch();

Fetch more notifications

This method will get next page of notifications from SuprSend server and set data in notification store.

feedClient.fetchNextPage();

Listening for updates to store

Whenever there is update in notification store (ex: on new notification or existing notification state updated) this event is fired by library. You can listen to this event and update your local state so that UI of you application is refreshed.

feedClient.emitter.on('feed.store_update', (updatedStoreData: IFeedData) => {
  // update your local state to refresh UI
});

Listening for new notification

In case you want to show toast notification on receiving new notification you can use this listener

feedClient.emitter.on(
  'feed.new_notification',
  (notificationData: IRemoteNotification) => {
    // your logic to trigger toast with new notification data
  }
);

Removing Feed

This will remove feed client data and abort socket connection. Additionally calling suprSendClient.reset method during logout will also remove all feedClient instances attached SuprSend client instance.

feedClient.remove();

Other methods

// If stores are used, this method will change active store
feedClient.changeActiveStore(storeId: string)

// Used to reset badge count which is shown on bell icon. This count is latest notifications that user received from the last he opened inbox popup.
// call this on click of bell icon
feedClient.resetBadgeCount()

// mark notification as seen
await feedClient.markAsSeen(notificationId: string)

// mark notification as read
await feedClient.markAsRead(notificationId: string)

// mark notification as unread
await feedClient.markAsUnread(notificationId: string)

// mark notification as archived
await feedClient.markAsArchived(notificationId: string)

// mark notification as interacted
await feedClient.markAsInteracted(notificationId: string)

// bulk mark all notifications as read
await feedClient.markAllAsRead()

// bulk mark given notification id's as seen
await feedClient.markBulkAsSeen(notificationIds: string[])

Response Structure

Most of the methods in this library return Promise<ApiResponse>

interface ApiResponse {
  status: 'success' | 'error';
  statusCode?: number;
  error?: { type?: string; message?: string };
  body?: any;
}

// success response
{
  status: "success",
  body?: any,
  statusCode?: number
}

// error response
{
  status: "error",
  error: {
    type: string,
    message: string
  }
}