Setup

Install clang-format (21.1.3) e.g. brew install clang-format.

OneSignal Cordova Push Notification Plugin

⚠️ Migration Advisory for current OneSignal customers

Our new user-centric APIs and v5.x.x SDKs offer an improved user and data management experience. However, they may not be at 1:1 feature parity with our previous versions yet.

If you are migrating an existing app, we suggest using iOS and Android’s Phased Rollout capabilities to ensure that there are no unexpected issues or edge cases. Here is the documentation for each:

• iOS Phased Rollout
• Google Play Staged Rollouts

If you run into any challenges or have concerns, please contact our support team at [email protected]

OneSignal is a free email, sms, push notification, and in-app message service for mobile apps. This plugin makes it easy to integrate your Cordova based (e.g. Ionic, PhoneGap, and PhoneGap Build app with OneSignal.

Installation and Setup

See the Documentation for installation and setup instructions:

• Cordova: https://documentation.onesignal.com/docs/cordova-sdk-setup
• Ionic: https://documentation.onesignal.com/docs/ionic-sdk-setup

API

See OneSignal's Client SDK Reference page for a list of all available methods.

iOS Native Dependencies

Cordova iOS apps using cordova-ios 8 or newer can resolve this plugin with Swift Package Manager. Older Cordova iOS apps continue to use CocoaPods through OneSignalCordovaDependencies.

Capacitor apps using Swift Package Manager must use Capacitor 8.4.0 or newer so Capacitor can read this plugin's root Package.swift. The demo app in examples/demo validates that path.

Manual iOS Dependency Tests

Use these checks from a clean checkout when changing iOS dependency resolution.

Swift Package Manager:

vp install
vp run build

TMP_DIR=$(mktemp -d)
vpx cordova create "$TMP_DIR/spm-app" com.onesignal.spmtest SPMTest
cd "$TMP_DIR/spm-app"
vpx cordova platform add ios@8
vpx cordova plugin add /path/to/OneSignal-Cordova-SDK
vpx cordova prepare ios

# The OneSignal pod should be skipped when SPM is active.
! grep -R "OneSignalCordovaDependencies" platforms/ios/Podfile

APP_NAME=$(basename platforms/ios/*.xcodeproj .xcodeproj)
xcodebuild -resolvePackageDependencies -project "platforms/ios/${APP_NAME}.xcodeproj"
xcodebuild -workspace "platforms/ios/${APP_NAME}.xcworkspace" \
  -scheme "$APP_NAME" \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath build \
  -quiet build \
  CODE_SIGNING_ALLOWED=NO \
  COMPILER_INDEX_STORE_ENABLE=NO

Replace /path/to/OneSignal-Cordova-SDK with the path to this repository. A passing test resolves OneSignal-XCFramework through SPM and builds without adding OneSignalCordovaDependencies to the Podfile.

CocoaPods:

vp install
vp run build

cd examples/demo-pods
vp run clean:ios
vp run setup:ios

grep "OneSignalCordovaDependencies" ios/App/Podfile
xcodebuild -workspace ios/App/App.xcworkspace \
  -scheme App \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath ios/App/build \
  -quiet build \
  CODE_SIGNING_ALLOWED=NO \
  COMPILER_INDEX_STORE_ENABLE=NO

Use vp run setup:ios:local in examples/demo-pods when manually validating local podspec changes before release.

Disabling OneSignal Location

If your app does not use OneSignal.Location, you can exclude the native OneSignal location module from Android, iOS CocoaPods, and iOS Swift Package Manager builds.

Set ONESIGNAL_DISABLE_LOCATION=true in the environment before installing the plugin or syncing native platforms, because this flag is read when native dependencies are resolved. The value is case-insensitive, and 1 is also accepted. For iOS Swift Package Manager, also set the flag for the actual Xcode build process so Package.swift is evaluated with location disabled.

ONESIGNAL_DISABLE_LOCATION=true cordova plugin add onesignal-cordova-plugin
ONESIGNAL_DISABLE_LOCATION=true cordova platform add ios
ONESIGNAL_DISABLE_LOCATION=true cordova platform add android

Capacitor apps do not need to edit ios/App/Podfile or CapApp-SPM/Package.swift; run Capacitor sync in an environment where the flag is set:

ONESIGNAL_DISABLE_LOCATION=true npx cap sync ios
ONESIGNAL_DISABLE_LOCATION=true npx cap sync android
ONESIGNAL_DISABLE_LOCATION=true npx cap run ios --no-sync

In CI, set the flag once at the job or step level so CocoaPods and Gradle inherit it:

env:
  ONESIGNAL_DISABLE_LOCATION: true

With the location module disabled, calls to OneSignal.Location are ignored and OneSignal.Location.isShared() resolves false.

If you change this setting in an existing project, clear the relevant native dependency state and re-resolve in a shell where the variable is exported.

For Cordova:

cd platforms/ios
pod deintegrate
rm -rf Pods Podfile.lock
ONESIGNAL_DISABLE_LOCATION=true pod install

For Capacitor:

cd ios/App
pod deintegrate
rm -rf Pods Podfile.lock
ONESIGNAL_DISABLE_LOCATION=true pod install

For SPM:

rm -rf ios/App/App.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
ONESIGNAL_DISABLE_LOCATION=true xcodebuild \
  -resolvePackageDependencies \
  -project ios/App/App.xcodeproj \
  -derivedDataPath ios/App/build
ONESIGNAL_DISABLE_LOCATION=true xcodebuild \
  -project ios/App/App.xcodeproj \
  -scheme App \
  -derivedDataPath ios/App/build

When using Xcode or Android Studio, launch the IDE from a terminal that has ONESIGNAL_DISABLE_LOCATION exported. An IDE launched from the Dock/Finder does not inherit variables set only in your shell profile.

Change Log

See this repository's release tags for a complete change log of every released version.

Support

Please visit this repository's Github issue tracker for feature requests and bug reports related specificly to the SDK. For account issues and support please contact OneSignal support from the OneSignal.com dashboard.

Demo Projects

To make things easier, we have published an Ionic Capacitor React demo app in the /example folder of this repository.

Legacy (Player Model) demo projects:

• Cordova
• Ionic

Supports:

• Cordova, Ionic, Ionic Capacitor, and Phonegap
• Android 4.1 (API Level 16) through 12 (API Level 31), and Amazon FireOS
• iOS 9 - 15