React OneSignal Integration

Common errors

• ReferenceError: OneSignal is not defined

  cause Attempting to use `OneSignal` without importing it, or in a CommonJS environment without correctly requiring it after v3.3.0.
  fix Ensure `import OneSignal from 'react-onesignal';` is at the top of your file, or use `const OneSignal = require('react-onesignal');` for CJS.

• TypeError: Cannot read properties of undefined (reading 'promptPush')

  cause Calling OneSignal methods (e.g., `Slidedown.promptPush()`) before the `OneSignal.init()` promise has resolved.
  fix Always `await OneSignal.init(...)` or chain `.then()` to the `init` call before attempting to interact with other OneSignal SDK functionalities.

• OneSignal SDK is not initialized.

  cause This error occurs internally within the OneSignal SDK if you try to use its methods (e.g., `setExternalUserId`, `sendTag`) when `OneSignal.init()` has not been successfully called or completed.
  fix Verify that `OneSignal.init()` is called exactly once and its promise resolves successfully before any other OneSignal API calls. Check for any errors during the `init` process.

• Failed to register service worker

  cause The OneSignal service worker file is not found at the specified `path`, `serviceWorkerPath`, or `serviceWorkerUpdaterPath` during initialization, or there are network/CORS issues preventing its loading.
  fix Double-check the paths provided in the `init` options match the location of your OneSignal service worker files. Ensure these files are correctly deployed and accessible from your domain. Use browser developer tools to inspect service worker registration errors.

Warnings

• breaking Version 3.0 introduced significant breaking changes. Existing implementations using v2.x or older will require updates. Consult the official 'Migration Guide' for detailed instructions.
  Fix: Refer to the 'MigrationGuide.md' file in the package's GitHub repository or documentation to adapt your code to the v3 API changes.
• gotcha The `OneSignal.init()` function returns a Promise. It is crucial to await this promise or use its `.then()` method before attempting to call any other OneSignal SDK methods, otherwise, they might not be available or fully configured.
  Fix: Always use `await OneSignal.init(...)` in an `async` context or `OneSignal.init(...).then(() => { ... })` to ensure the SDK is fully loaded and ready before subsequent calls.
• gotcha While the package is named `react-onesignal`, it's explicitly stated to be usable in 'practically any JS front-end codebase'. Developers should be aware it's a wrapper for the OneSignal Web SDK and not a React-specific UI component library.
  Fix: Understand that the package provides an API wrapper, not React components. Integrate it by calling its `init` method and then using the exposed OneSignal SDK methods.
• gotcha Incorrect configuration of `path`, `serviceWorkerPath`, or `serviceWorkerUpdaterPath` options during `init` can lead to service worker registration failures, preventing push notifications from working correctly.
  Fix: Ensure that the service worker paths specified in the `init` options correctly point to the OneSignal service worker files within your deployed application. Verify these paths against your OneSignal setup and deployment structure.
• gotcha The `IDisplayableOSNotification` interface and its `display()` method (added in v3.5.1) are for advanced notification handling. Misusing `preventDefault()` without subsequently calling `display()` (if intended) can result in notifications not being shown to the user.
  Fix: When using notification event listeners and `event.preventDefault()`, ensure you understand the lifecycle. If the notification should eventually be shown, explicitly call `notification.display()` at the appropriate time.

Install

• npm install react-onesignal npm
• yarn add react-onesignal yarn
• pnpm add react-onesignal pnpm

Imports

• OneSignal
  wrong:

  const OneSignal = require('react-onesignal');

  correct:

  import OneSignal from 'react-onesignal';

  The library primarily uses ES Module syntax. While CommonJS is supported since v3.3.0, ESM is the recommended pattern for modern React applications. OneSignal is a default export.
• IDisplayableOSNotification
  wrong:

  import { IDisplayableOSNotification } from 'react-onesignal';

  correct:

  import type { IDisplayableOSNotification } from 'react-onesignal';

  This is a TypeScript type interface, requiring a type-only import for correct static analysis and to avoid bundling issues.
• Slidedown
  wrong:

  import { Slidedown } from 'react-onesignal';

  correct:

  await OneSignal.init({ appId: 'YOUR_APP_ID' });
  OneSignal.Slidedown.promptPush();

  Slidedown is a property of the initialized OneSignal object, not a separate named export. Access it after OneSignal has been successfully initialized.

Quickstart

This example demonstrates how to initialize OneSignal using the `init` function within a React component's `useEffect` hook, ensuring it's called only once. It shows how to await the initialization promise and conditionally render content based on the SDK's readiness.

import React, { useState, useEffect } from 'react';
import OneSignal from 'react-onesignal';

function PushNotificationHandler() {
  const [initialized, setInitialized] = useState(false);

  useEffect(() => {
    const initializeOneSignal = async () => {
      try {
        await OneSignal.init({
          appId: process.env.ONE_SIGNAL_APP_ID ?? 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
          safari_web_id: process.env.ONE_SIGNAL_SAFARI_WEB_ID ?? '',
          notifyButton: {
            enable: true,
          },
          allowLocalhostAsSecureOrigin: true,
        });
        setInitialized(true);
        console.log('OneSignal initialized successfully');
        
        // You can prompt for push notifications here after initialization
        // OneSignal.Slidedown.promptPush();

      } catch (error) {
        console.error('Failed to initialize OneSignal:', error);
      }
    };

    if (!initialized) {
      initializeOneSignal();
    }
  }, [initialized]);

  if (!initialized) {
    return <div>Loading push notifications...</div>;
  }

  return (
    <div>
      <h1>Push Notifications Ready</h1>
      <p>OneSignal SDK is initialized and ready to use.</p>
      <button onClick={() => OneSignal.Slidedown.promptPush()}>Show Push Prompt</button>
    </div>
  );
}

export default PushNotificationHandler;