Documentation

Ionic Android Setup


To start sending push notifications to your Ionic Android app with Pushy, you'll need to make a few changes to your application.

Get the SDK

Install the latest version of our Cordova SDK by running the following command in the root directory of your project:

ionic cordova plugin add pushy-cordova

Install the sample push BroadcastReceiver plugin by running the following command:

ionic cordova plugin add pushy-cordova-receiver --searchpath plugins/pushy-cordova/receiver/

Note: This command installs the pushy-cordova-receiver plugin from your local filesystem to make it easier to modify its implementation later, if needed.

Modify Index File

Add the following declaration to the top of your src/app/app.component.ts file:

declare var Pushy:any;

Add the following code to your platform.ready() callback function so that the device will listen for push notifications when the deviceready event fires:

// Wait for Cordova to load on the device
document.addEventListener('deviceready', function() { 
    // Start the Pushy service
    Pushy.listen();
});
Android 6.0+ Compatibility

Android 6.0 and newer versions require apps with a targetSdkLevel >= 23 to explicitly request permissions from users via permission dialogs.

Since Pushy persists device tokens in the external storage (to survive app reinstallation), you should add the following code to ask the user to grant your app permission to access the external storage.

Find:
Pushy.listen();
Add Below:
// Request the WRITE_EXTERNAL_STORAGE permission so that the Pushy SDK will be able to persist the device token in the external storage
Pushy.requestStoragePermission();
Register Devices

Devices need to be uniquely identified to receive push notifications.

Every device is assigned a unique token that you can use to push it at any given time. Once the device has been assigned a token, it should be stored in your application's backend database. When you're ready to push the device, your backend server will send its token to our REST API, and we'll deliver the push notification to the corresponding device.


Add the following code to your application to register the device for push notifications:

// Register the device for push notifications
Pushy.register(function (err, deviceToken) {
    // Handle registration errors
    if (err) {
        return alert(err);
    }

    // Print device token to console
    console.log('Pushy device token: ' + deviceToken);

    // Send the token to your backend server via an HTTP GET request
    //await fetch('https://your.api.hostname/register/device?token=' + deviceToken);

    // Succeeded, do something to alert the user
});
Listen for Notifications

Call the Pushy.setNotificationListener((data) => {}) method from your application to listen for push notifications:

// Listen for push notifications
Pushy.setNotificationListener(function (data) {
    // Print notification payload data
    console.log('Received notification: ' + JSON.stringify(data));

    // Display an alert with the "message" payload value
    alert(data.message);
});

This callback is only invoked if incoming notifications are received while your activity is running. Otherwise, the SDK persists the notifications and invokes your notification listener the next time your app is opened.


Feel free to modify this sample code to suit your own needs.

Note: The pushy-cordova-receiver plugin includes a PushReceiver.java sample implementation that automatically emits a system notification even if your app is not running.

Parse Notification Data

Any payload data that you send with your push notifications is made available to your app via the data parameter of your notification listener.

If you were to send a push notification with the following data:

{"id": 1, "success": true, "message": "Hello World"}

Then you'd be able to retrieve each value from within your notification listener callback like so:

var id = data.id; // number
var success = data.success; // bool
var message = data.message; // string

Note: Unlike GCM / FCM, we do not stringify your payload data, except if you supply JSON objects or arrays.

Subscribe to Topics (Optional)

Optionally subscribe the device to one or more topics to target multiple devices with a shared interest when sending notifications.

Depending on your app's notification criteria, you may be able to leverage topics to simply the process of sending the same notification to multiple devices. If your app only sends personalized notifications, skip this step and simply target individual devices by specifying their tokens.


Add the following code to your application to subscribe a registered device to a topic:

// Make sure the device is registered
Pushy.isRegistered(function (isRegistered) {
    if (isRegistered) {
        // Subscribe the device to a topic
        Pushy.subscribe('news', function (err) {
            // Handle errors
            if (err) {
                return alert(err);
            }

            // Subscribe successful
            console.log('Subscribed to topic successfully');
        });
    }
});

Note: Replace news with your own case-sensitive topic name that matches the following regular expression: [a-zA-Z0-9-_.]+.


You can then notify devices subscribed to a certain topic by specifying the topic name (prefixed with /topics/) as the to parameter in the Send Notifications API.

Modify the Push Receiver (Optional)

Optionally modify the default push BroadcastReceiver implementation to handle incoming notifications differently.

The built-in push receiver emits a system notification with your app name and icon, and extracts the message from the {"message": "..."} JSON data payload value. If this behavior is sufficient for your app, you may skip this step.


Modify the PushReceiver.java file in the following path:

plugins/pushy-cordova/receiver/src/android/PushReceiver.java

Note: Do not accidentally modify plugins/pushy-cordova-receiver/src/android/PushReceiver.java or platforms/android/src/me/pushy/sdk/cordova/PushReceiver.java as your modifications will be lost when you reinstall the plugin.


When you are done modifying the PushReceiver.java implementation, reinstall the plugin locally for changes to take effect by running the following commands in your root project directory:

ionic cordova plugin rm pushy-cordova-receiver
ionic cordova plugin add pushy-cordova-receiver --searchpath plugins/pushy-cordova/receiver/
Send Test Notification

Input your device token and select your app to send a test push notification:

Note: You can specify a topic instead of a device token (i.e. /topics/news). Also, if your app is not automatically detected, please manually copy the Secret API Key from the Dashboard and paste it into the form.

Check if your device received the notification. Did it work? If not, contact us, we'll help you out.

Integration Complete


Congratulations on implementing Pushy in your app!

Now, all that's left is to setup your backend. Head on over to the Backend Setup guide to begin persisting device tokens as well as implementing the logic for sending push notifications to your app.