End of Support for @suprsend/web-inbox. Migrate to @suprsend/web-components

We have upgraded authentication of inbox from HMAC to JWT as it is more secure. Please migrate to newer SDK if you are on old one.

There are 2 ways in which you can implement inbox functionality:

  • Drop-in components: Pre-built UI with many customizable options which require minimal effort to build.
  • Headless implementation: For more advanced usecases where you want to build UI/UX from scratch.

This guide help you integrate drop-in components in your non-react frameworks (angular, vuejs, vanillajs etc). If you want to build your own UI (headless) instead of using drop-in components please refer docs.

Integration

Integrate using script tag

This integration is used in Vanillajs, Django, Laravel, ruby etc where npm is not used.

<!-- for dropin inbox with bell -->
<div id="suprsend-inbox"></div>

<!-- for feed without bell as a fullscreen notification etc -->
<div id="suprsend-notification-feed"></div>

<script>
  window.suprsendConfig = {
    distinctId: "YOUR_DISTINCT_ID",
    publicApiKey: "YOUR_PUBLIC_API_KEY",
    userAuthenticationHandler: ({ response }) => {
      console.log("User Authentication Response", response);
    },
  };

  let scriptElem = document.createElement("script");
  scriptElem.async = 1;
  scriptElem.src = "https://web-components.suprsend.com/v0.0.1/bundle.umd.js";
  scriptElem.onload = () => {
    console.log("SuprSend SDK loaded", window.suprsend);
  };
  document.body.appendChild(scriptElem);
</script>

Integrate as npm Package

This integration is used in framework based applications like angular, vuejs etc.

npm install @suprsend/web-components@latest
import { initSuprSend, clearSuprSend } from "@suprsend/web-components";

// for dropin inbox with bell
<div id="suprsend-inbox"></div>

// for feed without bell as a fullscreen notification etc
<div id="suprsend-notification-feed"></div>

const suprsendConfig = {
  distinctId: "YOUR_DISTINCT_ID",
  publicApiKey: "YOUR_PUBLIC_API_KEY",
  userAuthenticationHandler: ({ response }) => {
    console.log("User Authentication Response", response);
  },
};

initSuprSend(suprsendConfig) // for creating instance and rendering component
console.log("Instance created but user authentication pending", window.suprsend)

Removing Instance

Components will be removed automatically if you navigate away from the page (on unmounting). If you want to remove them manually, you can use below methods.

window.suprsend.clearSuprSend(); // clears instance and remove all components
window.suprsend.clearSuprSendInbox(); // unmount only inbox component
window.suprsend.clearSuprSendFeed(); // unmount only feed component

Update config options

window.suprsend.updateInboxConfig(config: IInbox);
window.suprsend.updateFeedConfig(config: IFeed);
window.suprsend.updateToastConfig(config: IToastNotificationProps);

Refreshing expired JWT user token

If your JWT token has TTL (expires) you can call your backend api to get refreshed token and update existing token with new one.

window.suprsend.refreshUserToken(token); // pass new jwt usertoken string

Accessing other instance methods

SDK internally calls new SuprSend() when you call initSuprSend() then you can access instance using window.suprsend.client. This instance has methods like preferences, webpush, event and user updates.

// example methods
window.suprsend.client.isIdentified();
window.suprsend.client.user.addEmail(email: string);
window.suprsend.client.track(event: string, properties?: Dictionary)
window.suprsend.client.webpush.registerPush();
window.suprsend.client.user.preferences.getPreferences(args?: {tenantId?: string});

Config Options

To customise SuprSend components you can pass config object.

interface ConfigProps {
  publicApiKey: string;
  distinctId ? : unknown;
  userToken ? : string;
  host ? : string;
  initOnLoad ? : boolean; // pass false if you dont want to initialise instance just after loading script
  refreshUserToken ? : (oldUserToken: string, tokenPayload: Dictionary) => Promise < string > ;
  vapidKey ? : string;
  swFileName ? : string;
  userAuthenticationHandler ? : ({
    response: ApiResponse
  }) => void;
  inbox ? : IInbox; // inbox config options
  feed ? : IFeed; // feed config options
  toast ? : IToastNotificationProps; // toast config options
}
ParameterDescription
publicApiKeypublic api key is mandatory field without which error will be thrown by SuprSendProvider. You can get this from SuprSend Dashboard.
distinctIdUnique identifier to identify a user across platform. If a value is passed SDK will create user and authenticate user. If null value is passed authenticated user’s instance data will be cleared in your application, kind of logout.
userTokenMandatory when enhanced security mode is on. This is ES256 JWT token generated in your server-side. Refer docs to create userToken.
refreshUserTokenThis function is called by SDK internally to get new userToken before existing token is expired. The returned JWT token string is used as the new userToken.
userAuthenticationHandlerThis callback will be called after authenticating user internally when you pass distinctId field to give you back the response of user creation api call.
hostCustomise the host url.
vapidKeyThis key is needed only if you are implementing WebPush notifications. You can get it in SuprSend Dashboard —> Vendors —> WebPush
swFileNameThis key is needed only if you are implementing WebPush notifications and want to customise default serviceworker.js file name with your own service worker file name.

For further component specific customisations please refer to the docs.