Required For Setup
- A OneSignal Account if you do not already have one
- Your OneSignal App ID, available in Keys & IDs
- iOS - An iOS device (iPhone, iPad, iPod Touch) to test on. The Xcode simulator doesn't support push notifications so you must test on a real device.
- iOS - You MUST have a Mac with a new version of Xcode
Update SDK
If you already have an app with the Ionic SDK, you can run this to ensure your SDK is on the latest version:
ionic plugin update onesignal-cordova-plugin
If you have not set up an app yet, follow the instructions below.
Setup SDK
Generate Credentials
Before setting up the Ionic SDK, you must generate the appropriate credentials for the platform(s) you are releasing on:
iOS - Generate an iOS Push Certificate
Android - Generate a Google Server API Key
Amazon - Generate an Amazon API Key
Windows Phone 8.1 - Generate a Windows Phone Package SID and Secret
OneSignal supports Ionic 1 through 3.
iOS Requirements
iOS Platform 4.3.0 or newer
CocoaPods - Install with the following from the terminal.
sudo gem install cocoapods
pod repo update1. Import OneSignal Plugin
Requires Cordova 6.4.0 or newer
Please follow step 1A or 1B based how you build your app.
You should also remove other Push SDKs that you are not using, otherwise you may see duplicate notifications.
1A. Import from the Terminal
Run the following from your project directory.
ionic plugin add onesignal-cordova-plugin --save// Ionic Lab does not have a UI to add 3rd party plugins.
// Please run the following from your project directory from a terminal:
ionic plugin add onesignal-cordova-plugin2. Add required code
2.1A If you are using an Ionic Tab project please follow Ionic's OneSignal setup page.
2.1B If you are using the basic Ionic starter project add the following to your <project-dir>/www/js/app.js. (or app.ts if you are using typescript)
// Add the following to your existing ready fuction.
.run(function($ionicPlatform) {
$ionicPlatform.ready(function() {
// Enable to debug issues.
// window.plugins.OneSignal.setLogLevel({logLevel: 4, visualLevel: 4});
var notificationOpenedCallback = function(jsonData) {
console.log('notificationOpenedCallback: ' + JSON.stringify(jsonData));
};
window.plugins.OneSignal
.startInit("YOUR_APPID")
.handleNotificationOpened(notificationOpenedCallback)
.endInit();
// Call syncHashedEmail anywhere in your app if you have the user's email.
// This improves the effectiveness of OneSignal's "best-time" notification scheduling feature.
// window.plugins.OneSignal.syncHashedEmail(userEmail);
})// Add the following to your existing ready fuction.
initializeApp() {
this.platform.ready().then(() => {
// Enable to debug issues.
// window["plugins"].OneSignal.setLogLevel({logLevel: 4, visualLevel: 4});
var notificationOpenedCallback = function(jsonData) {
console.log('notificationOpenedCallback: ' + JSON.stringify(jsonData));
};
window["plugins"].OneSignal
.startInit("YOUR_APPID", "YOUR_GOOGLE_PROJECT_NUMBER_IF_ANDROID")
.handleNotificationOpened(notificationOpenedCallback)
.endInit();
});
});
}2.2 Update initialization parameters
Replace YOUR_APPID with your OneSignal AppId, available in Keys & IDs
3. Android
3.1 Open the Android SDK Manager.
3.2 Make sure to install and update the following under Extras:
- Android Support Repository
- Google Repository
3.3 Follow the Custom Notification Icons instructions below to create a small notification icon required for Android 5.0+ devices.
4. Amazon ADM
Place your api_key.txt file into your <project-dir>/platforms/android/assets/ folder.
To create an api_key.txt for your app follow our Generate an Amazon API Key
5. iOS - Part 1 (Required)
5.0 Open <project-root>/platform/ios/YourAppName.xcworkspace
5.1 Select the root project and Under Capabilities Enable "Push Notifications".
5.2 Next Enable "Background Modes" and check "Remote notifications".
5. iOS - Part 2 (Recommend)
5.3 To support Action Buttons and Media Attachments on iOS 10 please follow the Notification Service Extension guide (Only steps 1.1 to 1.5). Make sure to use Objective-C on this step then come back to this page and continue following the steps below.
5.4 Select the new OneSignalNotificationServiceExtension Target, select "Build Settings" then search for Code Signing Entitlements.
5.5 Delete both Debug and Release entries so they are blank.
5.6 Select Build Phases and expanded the"Link Binary With Libraries" section.
5.7 Press the + and add SystemConfiguration.framework and UIKit.framework.
5.8 Drag and drop Pods/Pods/OneSignal/Frameworks/OneSignal.framework from the view on the left to this section as well.
6. Windows Phone 8.1 (WP8.1)
Only Ionic 1 supports Windows Phone 8.1 projects
Your app does not have to be published however, you must have it created on the Windows Dev Center. Follow our Windows Phone Project SID & Secret setup if you have not done this yet.
6.1 Run ionic build windows and open the .sln in <project-root>/platforms/windows/
6.2 Under the Windows Phone 8.1 project double click on Package.appxmanifest then select the "Application" tab and scroll down to the "Notifications:" section. Change "Toast capable:" to Yes.
6.3 Right click on your VS project and select Store>Associate App with the Store...
6.4 Click Next and sign into your Microsoft account.
6.5 Select your app and press Next.
6.6. Lastly press Associate.
Troubleshooting
If you run into any errors see Troubleshooting Cordova Variants, our our general Troubleshooting section.
You're Done!
Next up: Send your first push notification via the OneSignal Dashboard
What's Next
| Features Setup |
| Ionic SDK |