ReactJS & NextJS Setup

​

Overview

​

Requirements

• Configured OneSignal app and platform. See Web Push Setup to get started.

​

Installation

yarn add react-onesignal

​

Initialization

"use client";

import { useEffect } from 'react';
import OneSignal from 'react-onesignal';

export default function Page() {
  useEffect(() => {
    // Ensure this code runs only on the client side
    if (typeof window !== 'undefined') {
      OneSignal.init({
        appId: 'YOUR_APP_ID',
        // You can add other initialization options here
        notifyButton: {
          enable: true,
        }
      });
    }
  }, []);

  return (
    <div>
      <h1>Hello, world!</h1>
      {/* Rest of your page content */}
    </div>
  );
}

​

Customizing init options

​

Service Worker Settings

​

Hosting the worker

• Public root (default): /OneSignalSDKWorker.js
• Custom folder (recommended): e.g., /onesignal/OneSignalSDKWorker.js as set in the previous step.

​

Verify service worker hosting

https://your-site.com/OneSignalSDKWorker.js

https://your-site.com/onesignal/OneSignalSDKWorker.js

​

Important notes

• Avoid Duplicate Initialization in Development
  • When testing in a development environment, you might see the OneSignal SDK initialize twice, which can cause console errors.
  • This happens due to <React.StrictMode> causing effects to run twice in development. To resolve it, remove <React.StrictMode> from your root component during development.

​

Testing the OneSignal SDK integration

​

Check web push subscriptions

1

Launch your site on a test device.

• Use Chrome, Firefox, Edge, or Safari while testing.
• Do not use Incognito or private browsing mode. Users cannot subscribe to push notifications in these modes.
• The prompts should appear based on your permission prompts configuration.
• Click Allow on the native prompt to subscribe to push notifications.

2

Check your OneSignal dashboard

• Go to Audience > Subscriptions.
• You should see a new entry with the status Subscribed.

You have successfully created a web push subscription. Web push subscriptions are created when users first subscribe to push notifications on your site.

​

Set up test subscriptions

1

Add to Test Subscriptions.

In the dashboard, next to the subscription, click the Options (three dots) button and select Add to Test Subscriptions.

2

Name your subscription.

Name the subscription so you can easily identify your device later in the Test Subscriptions tab.

3

Create a test users segment.

Go to Audience > Segments > New Segment.

4

Name the segment.

Name the segment Test Users (the name is important because it will be used later).

5

Add the Test Users filter and click Create Segment.

You have successfully created a segment of test users. You can now test sending messages to this individual device and groups of test users.

​

Send test push via API

1

Get your App API Key and App ID.

In your OneSignal dashboard, go to Settings > Keys & IDs.

2

Update the provided code.

Replace YOUR_APP_API_KEY and YOUR_APP_ID in the code below with your actual keys. This code uses the Test Users segment created earlier.

Copy

Ask AI

curl -X POST --url 'https://api.onesignal.com/notifications' \
  --header 'content-type: application/json; charset=utf-8' \
  --header 'authorization: Key YOUR_APP_API_KEY' \
  --data '{
    "app_id": "YOUR_APP_ID",
    "target_channel": "push",
    "name": "Testing basic setup",
    "headings": {
      "en": "👋"
    },
    "contents": {
      "en": "Hello world!"
    },
    "included_segments": [
      "Test Users"
    ],
    "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  }'

3

Run the code.

Run the code in your terminal.

4

Check images and confirmed delivery.

If all setup steps were completed successfully, the test subscriptions should receive a notification.

Only Chrome supports images. Images will appear small in the collapsed notification view. Expand the notification to see the full image.

5

Check for confirmed delivery.

In your dashboard, go to Delivery > Sent Messages, then click the message to view stats. You should see the confirmed stat, meaning the device received the push.

Safari does not support Confirmed Delivery.

Push notification message reports

View delivery, click, and conversion stats for your push notifications.

• The API request and response (copy-paste into a .txt file)
• Your Subscription ID
• Your website URL with the OneSignal code

​

User identification

​

Assign External ID

​

Add data tags

​

Add email and/or SMS subscriptions

• Use the addEmail method to create email subscriptions.
• Use the addSms method to create SMS subscriptions.

​

Privacy & user consent

• setConsentRequired(true): Prevents data collection until consent is given.
• setConsentGiven(true): Enables data collection once consent is granted.

​

Listen to push, user, and in-app events

​

Push notification events

• Click event listener: Detect when a notification is tapped.
• Foreground lifecycle listener: Control how notifications behave in foreground.

​

User state changes

• User state change event listener: Detect when the External ID is set.
• Permission observer: Track the user’s specific interaction with the native push permission prompt.
• Push subscription change observer: Track when the push subscription status changes.

​

Advanced setup & capabilities

​

Web SDK setup & reference