@notiflyio/react

Notifly React SDK for building custom inbox notification experiences.

Notifly provides @notiflyio/react, a React library that helps to add a fully functioning Inbox to your web application in minutes. Let's do a quick recap on how you can easily use it in your application. Full documentation: https://notifly.io.

Installation

• Install @notiflyio/react npm package in your react app

npm install @notiflyio/react

Connect to your subscribers

To connect the Inbox component with your Notifly environment and real subscribers, set the applicationIdentifier and subscriber

import { Inbox } from '@notiflyio/react';

function App() {
  return (
    <Inbox
      subscriber='SUBSCRIBER_ID'
      applicationIdentifier='APPLICATION_IDENTIFIER'
    />
  );
}

Use your own backend and socket URL

Point the Inbox at your Notifly deployment's API and socket services (for the hosted platform: https://api.notifly.io and its websocket service).

import { Inbox } from '@notiflyio/react';

function App() {
  return (
    <Inbox
      backendUrl='YOUR_BACKEND_URL'
      socketUrl='YOUR_SOCKET_URL'
      subscriber='SUBSCRIBER_ID'
      applicationIdentifier='APPLICATION_IDENTIFIER'
    />
  );
}

Controlled Inbox

You can use the open prop to manage the Inbox popover open state.

import { Inbox } from '@notiflyio/react';

function App() {
  const [open, setOpen] = useState(false);

  return (
    <div>
      <Inbox
        subscriber='SUBSCRIBER_ID'
        applicationIdentifier='APPLICATION_IDENTIFIER'
        open={open}
      />
      <button onClick={() => setOpen(true)}>Open Inbox</button>
      <button onClick={() => setOpen(false)}>Close Inbox</button>
    </div>
  );
}

Localization

You can pass the localization prop to the Inbox component to change the language of the Inbox.

import { Inbox } from '@notiflyio/react';

function App() {
  return (
    <Inbox
      subscriber='SUBSCRIBER_ID'
      applicationIdentifier='APPLICATION_IDENTIFIER'
      localization={{
        'inbox.status.archived': 'Archived',
        'inbox.status.unread': 'Unread',
        'inbox.status.options.archived': 'Archived',
        'inbox.status.options.unread': 'Unread',
        'inbox.status.options.unreadRead': 'Unread/Read',
        'inbox.status.unreadRead': 'Unread/Read',
        'inbox.title': 'Inbox',
        'notifications.emptyNotice': 'No notifications',
        locale: 'en-US',
      }}
    />
  );
}

HMAC Encryption

When you add the Inbox component to your application, you need to provide a subscriber prop with the value of your customer's subscriberId, along with an application identifier that serves as a public key for API communication.

A malicious actor can access the user feed by accessing the API and passing another subscriberId using the public application identifier.

HMAC encryption will make sure that a subscriberId is encrypted using the secret API key, and those will prevent malicious actors from impersonating users.

Enabling HMAC Encryption

In order to enable Hash-Based Message Authentication Codes, you need to visit the Notifly dashboard In-App settings page and enable HMAC encryption for your environment.

Subscriber HMAC

• Generate an HMAC encrypted subscriberId on your backend:

import { createHmac } from 'crypto';

const subscriberHash = createHmac('sha256', process.env.NOTIFLY_SECRET_KEY).update(subscriberId).digest('hex');

• Pass the created HMAC to your client side application:

<Inbox
  subscriber={'SUBSCRIBER_ID_PLAIN_VALUE'}
  subscriberHash={'SUBSCRIBER_ID_HASH_VALUE'}
  applicationIdentifier={'APPLICATION_IDENTIFIER'}
/>

Note: If HMAC encryption is active in In-App provider settings and subscriberHash along with subscriberId is not provided, then Inbox will not load

Context HMAC (Optional)

If you're using the context prop to pass additional data (e.g., tenant information, environment, etc.), you should also generate a contextHash to prevent context tampering:

• Generate an HMAC for the context on your backend:

import { createHmac } from 'crypto';
import { canonicalize } from '@tufjs/canonical-json';

const context = { tenant: 'acme', app: 'dashboard' };
const contextHash = createHmac('sha256', process.env.NOTIFLY_SECRET_KEY)
  .update(canonicalize(context))
  .digest('hex');

• Pass both the context and contextHash to the component:

<Inbox
  subscriber={'SUBSCRIBER_ID_PLAIN_VALUE'}
  subscriberHash={'SUBSCRIBER_ID_HASH_VALUE'}
  context={{ tenant: 'acme', app: 'dashboard' }}
  contextHash={'CONTEXT_HASH_VALUE'}
  applicationIdentifier={'APPLICATION_IDENTIFIER'}
/>

Note: When HMAC encryption is enabled and context is provided, the contextHash is required. The hash is order-independent, so {a:1, b:2} produces the same hash as {b:2, a:1}.