The client side javascript library for interacting with SuprSend
npm install @suprsend/web-sdkThis 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.
- Checkout detailed documentation for this library.
- Refer type definitions for this library here.
``bashusing npm
npm install @suprsend/web-sdk@latest
Integration
$3
Create suprSendClient instance and use same instance to access all the methods of SuprSend library.
typescript
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 |
$3
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).
typescript
const authResponse = await suprSendClient.identify(
distinctId: any,
userToken?: string, // only needed in production environments for security
{ refreshUserToken: (oldUserToken: string, tokenPayload: Dictionary) => Promise }
);
`| 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
This will remove user data from SuprSend instance similar to logout action.
typescript
await suprSendClient.reset();
`User Methods
Use these methods to manipulate user properties and notification channel data of user
typescript
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
typescript
const response = await suprSendClient.track(event: string, properties?: Dictionary)
`Webpush Setup
$3
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
, you can pass name of it in swFileName.`typescript
new SuprSend(publicApiKey: string, {vapidKey?: string, swFileName?: string})
`$3
Service worker file is the background worker script which handles push notifications.
Create
file such that it should be publicly accessible from https://. Then include below lines of code and replace publicApiKey with key you find in API Keys page in SuprSend Dashboard.`javascript
importScripts(
'https://cdn.jsdelivr.net/npm/@suprsend/web-sdk@3.0.3/public/serviceworker.min.js'
);initSuprSend(publicApiKey);
`$3
Call
in your code, which will perform following tasks:- Ask for notification permission.
- Register push service and generate webpush token.
- Send webpush token to SuprSend.
`typescript
const response = await suprSendClient.webpush.registerPush();
`Preferences
typescript
// get full user preferences data
const preferencesResp = await suprSendClient.user.preferences.getPreferences(args?: {tenantId?: string, tags?: string | Dictionary, locale?: string });// update category level preference
const updatedPreferencesResp = await suprSendClient.user.preferences.updateCategoryPreference(category: string, preference: 'opt_in'|'opt_out');
// update category level channel preference
const updatedPreferencesResp = await suprSendClient.user.preferences.updateChannelPreferenceInCategory(channel: string, preference: 'opt_in'|'opt_out', category: 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.
typescript
// 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
$3
typescript
const feedClient: Feed = suprSendClient.feed.initialize(options?: IFeedOptions);interface IFeedOptions {
tenantId?: string;
pageSize?: number;
stores?: IStore[] | null;
host?: { socketHost?: string; apiHost?: string };
}
`$3
#### 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.
typescript
const feedData: IFeedData = feedClient.data;
`#### Initialize socket for realtime update
typescript
feedClient.initializeSocketConnection();
`#### Fetching notification data
This method will get first page of notifications from SuprSend server and set data in notification store.
typescript
feedClient.fetch();
`#### Fetch more notifications
This method will get next page of notifications from SuprSend server and set data in notification store.
typescript
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.
typescript
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
typescript
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
method during logout will also remove all feedClient instances attached SuprSend client instance.`typescript
feedClient.remove();
`#### Other methods
typescript
// 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
typescript
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
}
}
``