OneSignal push notifications

Create a OneSignal account, then add an app and configure the platforms you support (Web, Apple iOS, Google Android). Copy the App ID from Settings → Keys & IDs — the hook takes the same App ID on every platform.

Install the package and the optional OneSignal Web SDK:

pnpm add @zoharyandrianome/crosshooks react-onesignal

Copy examples/docs/.env.example to .env.local and add your App ID:

NEXT_PUBLIC_ONESIGNAL_APP_ID=

Add the OneSignal service worker at public/OneSignalSDKWorker.js so OneSignal can create a background push subscription:

importScripts('https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js');

import { usePushNotifications } from '@zoharyandrianome/crosshooks';
import { oneSignalProvider } from '@zoharyandrianome/crosshooks/onesignal';

const oneSignalPush = oneSignalProvider({
  appId: process.env.NEXT_PUBLIC_ONESIGNAL_APP_ID!,
  // initOptions is forwarded to OneSignal.init, e.g. { safari_web_id, allowLocalhostAsSecureOrigin: true }
});

function NotificationsButton() {
  const notifications = usePushNotifications({ provider: oneSignalPush });
  return <button onClick={() => notifications.subscribe()}>Enable notifications</button>;
}

Keep the provider object outside the component so it stays stable.

Install the package and the optional native OneSignal SDK:

pnpm add @zoharyandrianome/crosshooks react-native-onesignal

The provider calls OneSignal.initialize() with your App ID and manages permission and opt-in, so the hook needs no OneSignal environment variables on native — pass the same { appId } config on every platform.

OneSignal delivers to Android through Firebase Cloud Messaging. In the OneSignal dashboard, open Settings → Push & In-App → Google Android (FCM) and upload your Firebase service account JSON (FCM v1) so OneSignal can send on your behalf.

Follow the React Native OneSignal Android setup to add the required Gradle configuration, then rebuild the native application.

Apple requires every app that receives push notifications to be set up once at the native level. You need a Mac with Xcode installed. Do each action in the tool named below.

1. In the Apple Developer portal: under Keys, create an APNs authentication key and download the .p8 file.
2. In the OneSignal dashboard: upload that .p8 key under Settings → Push & In-App → Apple iOS (APNs). This is what lets OneSignal hand your messages to Apple's servers.
3. In Xcode: open Signing & Capabilities, click + Capability, and add Push Notifications. Then add Background Modes and tick Remote notifications.
4. In Xcode: add a Notification Service Extension and the OneSignal App Group, as described by the React Native OneSignal iOS setup, so rich notifications and confirmed delivery work.
5. In a terminal: install the native pods and rebuild the app.

cd ios && pod install

Rebuild from Xcode (or your usual React Native run command) after pod install. Push notifications only arrive on a real device — the iOS Simulator cannot receive them.

import { usePushNotifications } from '@zoharyandrianome/crosshooks';
import { oneSignalProvider } from '@zoharyandrianome/crosshooks/onesignal';

const oneSignalPush = oneSignalProvider({ appId: 'your-onesignal-app-id' });

function NotificationsButton() {
  const notifications = usePushNotifications({ provider: oneSignalPush });
  return <Button title="Enable notifications" onPress={notifications.subscribe} />;
}

subscribe() requests permission, opts the device in, and returns the OneSignal subscription ID. Send that ID to your backend and associate it with the signed-in user, or call OneSignal.login() with your own external ID to target the user directly.

The hook registers the device; it does not embed OneSignal server credentials or send privileged messages from the client. Send from a trusted backend with the OneSignal REST API, targeting the stored subscription ID or external ID.

Never expose your OneSignal REST API key, APNs keys, or FCM service-account credentials through client environment variables. Only the OneSignal App ID is public.