Practical guide · Updated July 25, 2026

OneSignal push notifications setup for iOS and Android

OneSignal simplifies a cross-platform push system, but it does not replace APNs, Firebase, application identity or permission design. A production integration must connect the correct credentials, identify users safely, open the right app state and remain diagnosable after release.

Reviewed by Aleksei BalchunasProduct founder · web, iOS and Android releases

On this pageUnderstand the delivery path Define what notifications are for Separate development and production Configure Apple Push Notification service Configure Firebase Cloud Messaging for Android Install OneSignal in a Capacitor app Design the permission prompt as a product flow Understand users and subscriptions Design tags, events and segments deliberately Build notification payloads around destinations Handle foreground, background and killed states Send transactional notifications from a trusted backend Privacy, consent and notification preferences Production test matrix Troubleshooting by symptom Release checklist Official OneSignal references

Understand the delivery path

Your product or backendChooses the recipient, event, message content and destination.

OneSignalStores users and subscriptions, creates platform payloads, segments audiences and sends through the platform provider.

APNs and FCMApple Push Notification service delivers to iOS; Firebase Cloud Messaging delivers to supported Android devices.

Your installed appReceives the notification, presents it and routes a tap into the correct authenticated state.

If any identity, credential or routing link is wrong, a campaign can look successful while the user receives nothing or lands on the wrong screen.

Define what notifications are for

Do not begin with “send push.” Define the product event and the user action it should produce.

Transactional: order state, security alert or requested reminder
Communication: message, mention, invitation or assigned task
Lifecycle: onboarding step, abandoned workflow or reactivation
Content: followed topic, saved search or new relevant item
Operational: outage, deadline or action required

For every notification, document the trigger, eligible user, suppression rules, destination, expiry and success metric. Marketing convenience is not a reason to interrupt every user.

Separate development and production

One OneSignal app can support iOS and Android together. Development and production should normally be separate OneSignal apps or rigorously separated environments so test devices and test sends cannot reach real users.

Different OneSignal App IDs for development and production
Development iOS bundle ID and Android application ID are distinct when builds coexist
APNs and Firebase credentials match the corresponding application identity
Environment-specific App IDs come from build configuration, not manual edits
Test users and test segments exist in every environment
Production REST credentials are never available to development clients

Configure Apple Push Notification service

OneSignal still sends iOS notifications through APNs. Configure the iOS platform in OneSignal with a valid APNs signing key or certificate; OneSignal recommends the p8 token path.

Push Notifications capability is enabled for the iOS target
Background Modes includes remote notifications where the integration requires it
The App ID and bundle identifier match the signed application
The APNs key belongs to the correct Apple Developer team
Key ID, Team ID and p8 file are stored securely
A Notification Service Extension and App Group are configured when required for rich media and delivery features
Extension and main-app deployment targets and signing teams are compatible

Do not place the APNs private key in the mobile repository or frontend configuration.

Configure Firebase Cloud Messaging for Android

Android delivery uses FCM. Configure the Android platform in OneSignal with the correct Firebase project credentials and make sure the signed app uses the matching application ID and Firebase configuration.

The Firebase project is owned by the publishing organization
The Android application ID matches the registered Firebase app
The production google-services.json belongs to the production project
FCM service-account credentials are provided only to trusted server services such as OneSignal
Notification icon, color and channel behavior are deliberate
Android runtime notification permission is handled on versions that require it
Battery, background and OEM-specific delivery limits are considered in product expectations

Install OneSignal in a Capacitor app

For an existing web product packaged with Capacitor, use the official Capacitor plugin and synchronize the native projects.

npm install @onesignal/capacitor-plugin
npx cap sync

Initialize OneSignal once during application startup with the environment-specific App ID:

import OneSignal from "@onesignal/capacitor-plugin";

OneSignal.initialize(ONESIGNAL_APP_ID);

The plugin version is compatible with the installed Capacitor version
Both iOS and Android native projects are synchronized after installation
Verbose SDK logging is enabled only for development troubleshooting
Initialization does not accidentally show the permission prompt
The production App ID is injected by the release configuration

Design the permission prompt as a product flow

On iOS, the system permission prompt is a scarce moment. If the user denies it, the app cannot simply display the native prompt again. Ask after the value is understandable.

Show an in-app explanation tied to a concrete benefit.
Let the user accept or postpone.
Request the operating-system permission after acceptance.
Observe the resulting permission and subscription state.
After denial, provide an honest route to system settings when notifications are needed.

Good moments include enabling a reminder, following a conversation, tracking an order or subscribing to a user-selected event. First launch before context is usually a poor moment.

Understand users and subscriptions

OneSignal distinguishes a person from a particular delivery endpoint. A user can have multiple mobile, web, email or SMS subscriptions.

Call OneSignal.login(stableUserId) after your application authenticates the user
Use a stable internal user ID rather than an email address that may change
Call logout when the application user logs out or switches accounts
Do not assume reinstalling preserves the same anonymous OneSignal identity
Link iOS and Android subscriptions through the same External ID
Separate user-level tags from subscription-level opt-in state
Test multiple users sharing one physical device

OneSignal recommends assigning an External ID so subscriptions across devices and channels unify under the correct user profile.

Design tags, events and segments deliberately

Segmentation data becomes part of the product’s messaging model. Keep it small, explainable and server-authoritative where eligibility matters.

Use tags for durable messaging attributes, not an uncontrolled copy of the database
Choose a clear owner for language, timezone and preference updates
Do not trust client-written tags for security-sensitive eligibility
Define mutually understandable names such as plan, locale or onboarding_stage
Remove or update tags when the underlying state changes
Create a small test segment before any broad audience
Record the event or rule that made a user eligible

Build notification payloads around destinations

A notification should describe where the app must go, not encode a fragile implementation detail.

Use a stable destination type such as order, conversation or task
Include only the minimum identifier needed to fetch current data
Validate payload fields before navigating
Require authentication and authorization again after the app opens
Handle deleted, expired or inaccessible destinations
Define a safe fallback screen for unknown payload versions
Version payload contracts when behavior changes

Never treat possession of a notification payload as permission to access the referenced resource.

Handle foreground, background and killed states

The same notification can arrive while the user is actively using the app, while it is backgrounded or before any JavaScript state exists.

ForegroundDecide whether to show a banner, update the current screen silently or suppress a redundant interruption.

BackgroundA tap should restore navigation and open the intended destination after the app becomes ready.

Killed / cold startPersist or queue the destination until authentication, state hydration and the navigation container are ready.

Also test a notification tap after logout, token expiration, account switching and application update.

Send transactional notifications from a trusted backend

The OneSignal App ID belongs in the client; REST API credentials do not. Trigger sensitive or individualized notifications from a trusted server.

API keys remain in server-side secret storage
Every send is linked to an authenticated business event
Recipient eligibility is checked server-side
Idempotency prevents duplicate messages during retries
User preferences, quiet hours and suppression rules are applied
Message templates separate trusted data from free-form input
Send results and provider errors are logged without exposing secrets

Dashboard campaigns remain useful for controlled broadcasts, but production systems should not require a person to manually send transactional state changes.

Privacy, consent and notification preferences

Push tokens, device metadata, user identifiers, tags and engagement events are user data. Reflect the actual integration in privacy documentation and deletion workflows.

Privacy policy names the messaging purpose and relevant provider behavior
App Store and Google Play disclosures cover collected notification data
Marketing preferences are separate from essential transactional messages where appropriate
Users can disable categories without disabling every useful notification
Account deletion removes or detaches OneSignal user data as required
Location-triggered or sensitive tags are disabled unless genuinely needed
Logs avoid message contents or identifiers that support does not need

Production test matrix

Test production-signed builds through TestFlight and a Google Play testing track.

Fresh install before permission is requested
Permission accepted, denied and later changed in Settings
Anonymous user, authenticated user and logout
Reinstall followed by login with the same External ID
Two accounts used sequentially on the same device
iOS and Android devices linked to one account
Foreground, background and killed application
Notification received, displayed and tapped
Valid, expired, deleted and unauthorized destinations
Slow startup, offline launch and expired authentication
Rich image, action button and long localized copy where used
Upgrade from the previous public app version

Mark test devices as Test Users and send to a narrow test segment before expanding an audience.

Troubleshooting by symptom

No subscription appearsCheck SDK initialization, App ID, native project sync, device logs and whether the installed build is the expected environment.

Subscription exists but cannot receiveCheck permission, opt-in status, APNs or FCM credentials, token validity and platform configuration.

Dashboard says sent but device receives nothingVerify audience membership, provider delivery errors, app identity, device connectivity and OS delivery restrictions.

Tap opens the app but not the destinationInspect payload parsing, cold-start timing, authentication and navigation readiness.

Duplicate or wrong-account notificationsInspect External ID login/logout behavior, retry idempotency and multiple subscriptions on the device.

Enable verbose SDK logs in a non-production build while reproducing the failure, then capture the Subscription ID, app version, environment and message ID.

Release checklist

Development and production OneSignal App IDs are separate
APNs and Firebase credentials belong to the correct production apps
Capacitor or native SDK initialization runs once
Permission is requested after a meaningful explanation
Authenticated users call login with a stable External ID
Logout and account switching are tested
Every notification has a safe destination and fallback
REST keys exist only on trusted servers
Privacy and store disclosures match the integration
Test Users and a production test segment are ready
TestFlight and Play testing builds pass the full matrix
Support can find the user, Subscription ID and message result
Delivery and notification-open metrics are monitored after launch