onesignal-cordova-plugin
Version:
OneSignal is a high volume Push Notification service for mobile apps. In addition to basic notification delivery, OneSignal also provides tools to localize, target, schedule, and automate notifications that you send.
196 lines (134 loc) • 7.72 kB
Markdown
<p align="center">
<img src="https://media.onesignal.com/cms/Website%20Layout/logo-red.svg"/>
</p>
## Setup
Install clang-format (21.1.3) e.g. `brew install clang-format`.
### OneSignal Cordova Push Notification Plugin
[](https://www.npmjs.com/package/onesignal-cordova-plugin) [](https://www.npmjs.com/package/onesignal-cordova-plugin)
---
#### ⚠️ Migration Advisory for current OneSignal customers
Our new [user-centric APIs and v5.x.x SDKs](https://onesignal.com/blog/unify-your-users-across-channels-and-devices/) 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](https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases/)
- [Google Play Staged Rollouts](https://support.google.com/googleplay/android-developer/answer/6346149?hl=en)
If you run into any challenges or have concerns, please contact our support team at support@onesignal.com
---
[OneSignal](https://onesignal.com/) is a free email, sms, push notification, and in-app message service for mobile apps. This plugin makes it easy to integrate your [Cordova](http://cordova.apache.org/) based (e.g. [Ionic](http://ionicframework.com/), [PhoneGap](https://phonegap.com/), and PhoneGap Build app with OneSignal.
<p align="center"><img src="https://app.onesignal.com/images/android_and_ios_notification_image.gif" width="500" alt="Cordova Notification"></p>
#### Installation and Setup
See the [Documentation](https://documentation.onesignal.com/docs) 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](https://documentation.onesignal.com/docs/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:
```bash
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:
```bash
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.
```bash
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:
```bash
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:
```yaml
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:
```bash
cd platforms/ios
pod deintegrate
rm -rf Pods Podfile.lock
ONESIGNAL_DISABLE_LOCATION=true pod install
```
For Capacitor:
```bash
cd ios/App
pod deintegrate
rm -rf Pods Podfile.lock
ONESIGNAL_DISABLE_LOCATION=true pod install
```
For SPM:
```bash
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](https://github.com/OneSignal/OneSignal-Cordova-SDK/releases) for a complete change log of every released version.
#### Support
Please visit this repository's [Github issue tracker](https://github.com/OneSignal/OneSignal-Cordova-SDK/issues) for feature requests and bug reports related specificly to the SDK.
For account issues and support please contact OneSignal support from the [OneSignal.com](https://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](https://github.com/OneSignal/OneSignal-Cordova-Example)
- [Ionic](https://github.com/OneSignal/OneSignal-Ionic-Example)
#### Supports:
- Cordova, Ionic, Ionic Capacitor, and Phonegap
- Android 4.1 (API Level 16) through 12 (API Level 31), and Amazon FireOS
- iOS 9 - 15