How to integrate OneSignal push notifications into an Ionic 3 application
In this post, we will explain how to implement One Signal push notifications in an Ionic 3 mobile application.
In general, we will:
- Use the Supermodular2 starter app.
- Set up Firebase and OneSignal accounts
- Implement push notifications in the application.
Note: The complete source code of this tutorial is available in the ionic-onesignal Github repository.
Prerequisites
To follow along with this tutorial, you will need:
- Supermodular2: This is a free starter template that allows you to start a new Ionic 3 project quickly offering some basic features commonly used in recent mobile applications. We are going to use it in order to build a basic Ionic 3 app with an extremely modular architecture and best software development practices applied. In the next section, we will go through all the steps needed for downloading and running the app.
- Firebase account: Will be needed to generate a Google Server API Key.
- One Signal account: Will be needed to use the necessary SDK and an online dashboard to send push notifications.
Step 1: Preparing your local environment
NodeJS
First, make sure that NodeJS is installed on your computer. If NodeJS is not installed, please install the latest LTS version (8.9.4) of NodeJS.
Git
Git should be installed in your computer. Follow the instructions for your platform to install it:
Sass
This application uses SASS, a CSS preprocessor. Follow the instructions for your platform to install it:
Cordova and Ionic
This is an Ionic Cordova based application, so Ionic and Cordova CLIs, should be installed on your computer for this application to run. In order to install Ionic and Cordova CLIs, run the command:
$ npm install -g cordova ionic
Step 2: Clone GitHub repository
Open your terminal and use the following command to clone the Supermodular2 project:
$ git clone https://github.com/appseed-io/supermodular2.git
Step 3: Install project’s libraries
Using your terminal window, navigate to the supermodular2
folder. Install the NodeJS dependencies required by the project:
$ npm install
Step 4: Run / Build the application
In your terminal, navigate to the supermodular2
folder and run the application in the browser by typing the following command:
$ ionic serve
A browser window will open as shown in the picture below.
Step 5: Install Android and/or iOS Tools and SDKs
In order to test this application, you should install Android and iOS tools and SDKs on your machine. Since Ionic is based on Cordova, Cordova provides a very useful guide for installing the requirements for Android platform and iOS platform (Mac OS users only).
Step 6: Add platforms
In your terminal, from your supermodular2
folder, run:
$ ionic cordova platform add android
or
$ ionic cordova platform add ios
Step 7: Emulate the app
After adding your platform, in your terminal, navigate to the supermodular2
folder and run:
$ ionic cordova emulate android
or
$ ionic cordova emulate ios
Step 8: Generate a Google Server API Key
The application we are going to build, uses Firebase in order to generate a Google Server API Key. This key allows OneSignal to use Google’s web push services for your notifications. Visit https://console.firebase.google.com/ and create a new project.
Get your Firebase Cloud Messaging token and Sender ID
Click the Gear icon at the top left and select Project settings.
Select the CLOUD MESSAGING tab.
Make a note of the two values listed:
- You’ll need your Server key, also known as the Google Server API key.
- You’ll need your Sender ID, also known as the Google Project Number, later as well.
Step 9: Configure OneSignal application
We will use OneSignal to send push notifications. Visit OneSignal and create an account if you haven’t already.
Configure OneSignal Android platform settings.
After login to One Signal, click on Add new app.
Type a name for your application in the appeared pop up. Here, we use “AppseedPushNotifications” as an App Name.
Select the platform that you want to configure with OneSignal push notifications and click NEXT. For this tutorial, select Google Android (GCM).
Next, enter your Google Server API Key and Google Project Number and click SAVE. These are the details you got from the Firebase console in the previous step.
Then, select the target SDK for your app. In our case, we are making an Ionic app so select, PhoneGap, Cordova, Ionic, Intel XDK and click NEXT.
As a final step, take a note of the OneSignal App ID, as we will use it in our application later.
Step 10. Implement OneSignal push notifications
Install Cordova plugin
For this application to work, we need to install OneSignal Cordova plugin.From your terminal, navigate in the supermodular2
folder and execute the following command:
$ ionic cordova plugin add onesignal-cordova-plugin
Import Cordova plugin
After installing the plugin, import OneSignal and add it to your app’s NgModule in app.module.ts
under src/app
as shown below.
Add required keys
Next, locate the config.ts
file under the src
folder. Here, we need to copy the App ID provided by OneSignal earlier and paste it to the oneSignalAppId
variable. Also copy the Google Project Number provided by Firebase earlier and paste it to the sender_id variable in the config.ts
file.
Check Cordova availability
The application uses the OneSignal cordova plugin which we referred to earlier. So, the app cannot run in a web browser. That’s why we have to check if the application runs in a real device or an emulator where Cordova is available.
The code below, checks if Cordova is available and returns true or false accordingly. In case Cordova is not available, a message it is also shown prompting the user to use a mobile device.
Under src/
create a folder called common
and a file called is-cordova-available.ts
and paste the following code.
Initialize One Signal plugin at application startup
In this section, we are going to register the device for receiving push notifications once the app loads. In app.component.ts
under src/app
add the highlighted section.
Also, add the highlighted line in the constructor in the same file.
Add the following code in app.component.ts
file under src/app
.
In short, in line 48, we check if the application is executed on a device. The startInit() method, starts the initialization process.
The inFocusDisplaying() method, controls how OneSignal notifications will be shown when one is received while your app is in focus. In this case, it uses Notification as a parameter, which is a native notification displayed while the app is in focus.
The handleNotificationReceived() is a method that runs when a notification is received. It calls the onPushReceived() method which is explained later.
The handleNotificationOpened() is a method that runs when a notification is tapped or when closing an alert notification shown in the app. It calls the onPushOpened() method which is explained later.
The endInit() method must be called to complete the initialization of OneSignal.
Finally, add the following code to handle the received and opened notifications.
Here, we use two methods. onPushReceived() which alerts the user with the notification message once the message is received and onPushOpened() which alerts the user with the notification message once the notification is opened.
OSNotificationPayload contains a payload with the content and settings of the notification the user has received, in this case, only the message of the notification.
Run / Test
Since OneSignal is a Cordova plugin we need to test the application on an emulator or on a real mobile device.
In your terminal, from your project folder type:
$ ionic cordova platform add android
Run project on Android Emulator
Open Android Studio and run the emulator. Make sure that you install the highest Android SDK version that the version of your target cordova-android supports. In this tutorial, we use API 27.
$ ionic cordova emulate android
Run project on Android real device
Connect your android device to your machine. Enable USB debugging and from your terminal run:
$ ionic cordova run android
Send push notifications
After running the application visit OneSignal. Select your application. Here you can see the number of users who have been registered for receiving push notifications.
Go ahead and send a message. To do this, navigate to OneSignal dashboard and click MESSAGES.
Click NEW PUSH.
Type the preferred title and message and click CONFIRM in the bottom of the screen.
Finally, from the appeared pop up click SEND MESSAGE.
Moments later, a push notification will be received in your device.
Push notification received while the app is not in focus.
Push notification opened from the notification drawer.
Push notification received while the app is in focus.
Known issues
Sometimes, it is noticed a URL connection error, after running the app in a slow Android device or an emulator.
A solution to this issue is to increase the timeout value when loading a URL. The code below, is used when loading a page. It specifies the amount of time to wait before throwing a timeout error. This snippet specifies 70 seconds.
Add the following code in supermodular2/config.xml
The complete source code of this tutorial is available in the Github repository. To see how the app should work after all the code we added, download the code of this repository and run the app.
Found this tutorial interesting?
To find many more features to incorporate in any Ionic 3 mobile app, check out Ionic 3 Toolkit.
References
Ionic, Angular2, Source code of this tutorial.
Originally published at AppSeed’s blog.