This is a JavaScript module that can be used to easily include OneSignal code in a website or app that uses React for its front-end codebase.

OneSignal is the world's leader for Mobile Push Notifications, Web Push, and In-App Messaging. It is trusted by 800k businesses to send 5 billion Push Notifications per day.

You can find more information on OneSignal here.

You can use yarn or npm.

yarn add react-onesignal

npm install --save react-onesignal

Simply initialize OneSignal with your token:

import OneSignal from 'react-onesignal';

OneSignal.initialize('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', options);

Where options is:

safari_web_id?: string;
subdomainName?: string;
allowLocalhostAsSecureOrigin?: boolean;
requiresUserPrivacyConsent?: boolean;
persistNotification?: boolean;
autoResubscribe?: boolean;
autoRegister?: boolean;
notificationClickHandlerMatch?: string;
notificationClickHandlerAction?: string;
notifyButton?: {
  enable?: boolean;
  size?: 'small' | 'medium' | 'large';
  position?: 'bottom-left' | 'bottom-right';
  showCredit?: boolean;
  prenotify?: boolean;
    theme?: 'default' | 'inverse';
    offset?: {
      bottom?: string;
      right?: string;
      left?: string;
    },
    text?: {
      [key: string]: string;
    };
    colors?: {
      [key: string]: string;
    };
}

And OneSignal object contains:

notificationPermission: string[];
registerForPushNotifications: () => Promise<any>;
getNotificationPermission: () => Promise<string>;
isPushNotificationsEnabled: () => Promise<boolean>;
isPushNotificationsSupported: () => boolean;
setSubscription: (unmute: boolean) => Promise<any>;
setEmail: (email: string) => Promise<string>;
logoutEmail: () => Promise<void>;
getEmailId: () => Promise<string>;
getUserId: () => Promise<string>;
setExternalUserId: (externalUserId: string | number) => Promise<void>;
removeExternalUserId: () => Promise<void>;
getExternalUserId: () => Promise<any>;
initialized: boolean;
sendTag: (key: string, val: string) => Promise<string>;
sendTags: (keyValues: object) => Promise<any>;

Player ID is an important information on OneSignal.

You can use getPlayerId to obtain it.

// Obtains the current playerId from the browser
const playerId = await OneSignal.getPlayerId();

To manage notifications:

• Use notificationPermission to see all possible states.
• Use getNotificationPermission to check current notification permissions.
• Use registerForPushNotifications to ask for notification permissions.

// Check all possible permission states
const permissions = OneSignal.notificationPermission;

// Check current permission state
const currentState = await OneSignal.getNotificationPermission();

// Ask the user for notification permissions, if not granted yet
await OneSignal.registerForPushNotifications();

You can use setEmail, getEmailId and logoutEmail to track user email.

// Set email to track & notify specific users
OneSignal.setEmail('[email protected]');

// Check which email is configured in this browser
const emailId = await OneSignal.getEmailId();

// Remove email tracking
OneSignal.logoutEmail();

You can use setExternalUserId, getExternalUserId and removeExternalUserId to track external user ID.

// Set external user ID
OneSignal.setExternalUserId('your_id');

// Get external user ID
const externalUserId = await OneSignal.getExternalUserId();

// Remove external user ID
OneSignal.removeExternalUserId();

You can also listen for native OneSignal events like subscriptionChange.

To add an event listener to the OneSignal.push() array, pass an array of events to the ReactOneSignal.initialize() function as the third parameter.

Each object in the array should contain:

• listener -- (optional) Default value: 'on'. Some events can be listened for via multiple listeners (e.g. .on(), .once()). Check the docs to see which listeners listen for your event. Example: 'on' | 'once'

• event -- Name of the event being listened for. Example: 'subscriptionChange'

• callback -- Callback function for event. Example: (value) => { console.log(value); }

For documentation on events and event listeners, check out the Web Push SDK docs.

const events = [
  {
    listener: 'once',
    event: 'subscriptionChange',
    callback: (isSubscribed) => {
      if (true === isSubscribed) {
        console.log('The user subscription state is now:', isSubscribed);
      }
    },
  },
  {
    event: 'notificationDisplay',
    callback: (event) => {
      console.warn('OneSignal notification displayed:', event);
    },
  },
  {
    event: 'notificationDismiss',
    callback: (event) => {
      console.warn('OneSignal notification dismissed:', event);
    },
  },
];


ReactOneSignal.initialize(applicationId, options, events);

You can use sendTag and sendTags to set OneSignal tags for segment filtering.

// Send a tag to OneSignal for the current player
OneSignal.sendTag('tag', 'tagValue');

// Send multiple tags to OneSignal for the current player
const keyValues = {
  'tag1': 'value1',
  'tag2': 'value2',
  'tag3': 'value3',
};
OneSignal.sendTags(keyValues);

To avoid error due to OneSignal not initialized, you can use useOneSignalSetup hook, passing a callback to be called when OneSignal is ready

import OneSignal, { useOneSignalSetup } from 'react-onesignal';

type AppProps = {
  user: {
    id: string;
    Email: string;
  };
};

function App(props: AppProps) {
  const { user } = props;

  useOneSignalSetup(() => {
    OneSignal.setEmail(user.Email);
    OneSignal.setExternalUserId(user.id);
  });
}

Pull requests are welcome! If you have any feedback, issue or suggestion, feel free to open a new issue so we can talk about it 💬.

MIT © pedro-lb