Sending

Sending Push Notifications to Android and iOS devices.

The Appery.io Push Notifications feature allows sending push messages to users who have installed your app.

Quickstart

If you are new to sending Push Notifications, you may want to see our step-by-step tutorials:

📘

Note

Also, you can read more on Cordova push plug-ins here.

Enabling Push Notifications

Go to the Configuration page to learn how to enable and configure Push Notifications.

Sending Options

There are many options available to configure when it comes to sending push notifications. Initially, only the basic options are displayed; in order to view more, click the Advanced settings dropdown (to locate it, scroll the Send push notification tab down):

Expiration date

Time stamp in UTC TZ, when the provider should stop re-sending a notification to an offline device.
Please, be aware that Apple provider will not be trying to re-send a message if this parameter is not set.

Targeting (filtering) Devices

There are two options in terms of filtering: device filtering using a query builder and device filtering using a query string. The most convenient way to filter devices is to use the query builder: it supports all data types available in the database.

However, if the builder does not have sufficient flexibility for your queries, use the second option. It accepts all possible queries and can be used with any other collection.
When using the device filtering using a query builder, they are predefined sets of operations for each data type.

To send a notification using Channels , choose from the fields list. The includes option can specify the array of channels where the push notification must be sent.

The not includes operator ensures that push notifications are sent to all of the channels except those specified.

It is also possible to use the elemMatch operator to match more than one component within an array element. In this case, the array structure must be a little more complex.
To send the push notification to a certain device, use the deviceID field and the equals operator:

📘

Note

See how to retrieve the deviceID below.

The not equal operation ensures push notifications are sent to all of the devices except the one(s) specified.

You can also define the timeZone for your pushes; this is useful in combination with other filters.

Click the Add filter to add more specific filters.
After the filter parameters are set, the query string and the number of recipients are updated.
At the bottom of the page, you can find the number of recipients filtered by the query.

Custom Sound

Adding custom sounds in Ionic 4/5 projects:

  1. In the Source tab, upload your custom sound, for example, the mac.wav file to the resources folder:
  1. Enable the Android device type and then select the parameter Custom sound (provide the file name) on the Send Push Notification tab:
  1. Scroll down, expand the Advanced settings section, and click the Add button for the Custom data parameter; provide android_channel_id with a channel name, for example testchannel1:
  1. Go to the app page and declare the Push initialize event with the following code (note the correct android_channel_id name (here, testchannel1) and the file name without its extension: mac):
( < any > window).PushNotification.createChannel(
() => {
console.log('success');
},
() => {
console.log('error');
}, {
// here you can declare any channel name;
id: 'testchannel1',
// here - "sound" - a name of your "wav" file without ".wav";
sound: "mac",
description: 'My first test channel'
}
);
  1. Unfold the scripts folder of the Source tab, and add the link to your custom file to the config.xml file within the <platform name="android"> section:
<resource-file src="resources/mac.wav" target="app/src/main/res/raw/mac.wav"/>

👍

Adding both custom sound and custom icon (image) to project

If you need to add to your project both custom sound and custom icon (image), make sure that in the config.xml file the information about the custom sound file is added before the information about custom icon (image).

Adding custom sounds for the latest Cordova versions 5.1 (JQM) and 2.1 (Ionic1)

For the iOS platform:

  • the sound files are to be uploaded to the resources/ folder;
  • to be included to the build, they have to be declared as resource-file in config.xml:
    <resource-file src="resources/bird.wav" /> within the section <platform name="ios">
  • when sending the push message declare the custom sound file on the Push Settings tab this way: bird.wav

For the Android platform:

  • the sound files are to be uploaded to the resources/android/res folder;
  • to be included in the build, they have to be declared as resource-file in config.xml:
    <resource-file src="resources/android/res/sound.wav" target="app/src/main/res/raw/sound.wav" /> within the section <platform name="android">
  • in the app, the Push initialize event should be declared with the Channel as the following code:
PushNotification.createChannel(
        function(){
            alert('channel success');
        },
        function(){
            alert('channel error');
        },
        {
            // here you can declare any channel name;
            id: 'testchannel1',
            // here - "sound" - a name of your "wav" file without ".wav";
            sound: "sound", 
            description: 'My first test channel'
        }
);
document.addEventListener("pushinit", function() {
    PushNotification.createChannel(
        () => {
            console.log('success');
        },
        () => {
            console.log('error');
        }, {
            // here you can declare any channel name;
            id: 'testchannel1',
            // here - "sound" - a name of your "wav" file without ".wav";
            sound: "sound1",
            description: 'My first test channel'
        }
    );
});
  • when sending the push message on the Push sending tab add android_channel_id with a channel name:
Push send "Advanced settings"Push send "Advanced settings"

Push send "Advanced settings"

Adding custom sounds for Cordova versions older than 5.1 (JQM)

In the Sound file section, you can set your own sound file to play when a push arrives, if the value is not specified or is invalid, the default sound settings will be applied.

  1. To use a custom sound, you’ll need to first open the app and make sure that you have the Push sound enabled in the global Settings under the Push Notifications tab.
  2. Next, you will need to upload the sound to the source/CORDOVA/platforms/ios/platform_www/soundfilename.wav (for iOS) or
    source/CORDOVA/platforms/android/res/raw/soundfilename.wav (for Android):

📘

Note!

There is no default raw folder in source/CORDOVA/platforms/android/res/`, so you will need to create it first.

  1. Now, go to the Push Notifications console and select Custom for the Sound file and enter the uploaded sound file name into the field provided.
  2. For iOS, you need to specify the path: www/soundfilename.wav.

🚧

Note!

Google updated the rules for Push custom sound for Android 8.0+ devices.
Sound configuration per Notification has been deprecated since Android 8.0 (API 26). The custom sound can be now set per Channel only.
More information can be found here.

Check Silent to disable the sound playback. Click here to read more about custom alerts.

📘

Note!

The silent mode works for iOS 8 and higher only.

Scheduling Push Notifications

You can also defer sending a push notification. To do this, check the Schedule a push box under the Message text area.

There are two ways to schedule push notifications:

  • A push will be sent on the date and time defined according to the time zone of the device.
  • A push will be sent to all devices in different time zones accordingly, all at the same time.

To schedule a push, follow these steps:

  1. Check the Schedule a push box.
  2. Select how you want the push to be sent. If you are sending the notification based on the device time zone, check the first option.
  3. This allows you to set a time when a push should be sent; UTC date is truncated to minutes.
    If a push should be sent to all devices at once, check the second option.
  4. Define the date and time when a push should be sent. Select the time zone for the second option and the time will be calculated automatically on the server.
  5. Click Schedule to apply.

Scheduled and history

All push notifications appear in the list in the Scheduled and History view.

Here, you can see the date and time information for pushes (depending on the time zone of the device), their badges, and statuses. The Status field may have one of the following values:

  • Wait – the specified time has not arrived, no push has been sent.
  • Process – some devices have received the push, but not all.
  • Sent – a push has been sent to all devices.
  • Error – a push hasn’t been sent (with the information on the error).
    Immediate push notifications (sent without scheduling) also appear in the list with the status sent.
    You can delete any record on the list.
    Click Filter scheduled to filter list items by status (sent, wait, error, process) and/or by date.

Changing Scheduled Notifications

Scheduled notifications with the status wait can be changed. To do that, click edit.
The Edit push dialog opens. There, you can change all the editable settings of a scheduled notification.

Dry Run

Check the box to run a quick test of your push notification setup. For Android devices, testing for errors is provided by GCM (Google Cloud Messaging) as a native support option. For iOS devices, it is run to check certificates for any errors.
No messages will be sent to a device.

Custom Data

User data that will be sent to a device. Click Add and enter parameters and values you would like to send with your push.

📘

Note

There are no restrictions on the custom data to be sent in a push notification, but there is the 4kB restriction for the entire push notification set by Google and Apple. To check the approximate amount of data being sent with your push, go to the Push message data section below.

Click Delete to remove excess data.

Collapse Key

Android only.

In situations where there is a newer message that renders an older, a related message is irrelevant to the client app, or GCM (Google Cloud Messaging) replaces the older message e.g. Send-to-Sync, or outdated notifications, set the Collapse key parameter to true, and if a user’s device is offline, only the last push notification with the same collapse key will be displayed.

Restricted Package Name

Android only.

This parameter specifies a string containing the package name of the app. When it is set, messages are only sent to the registration IDs that match the package name, and the registration token must match in order to receive the message.

An application with any package ID can receive your messages as long as it knows your GCM Sender ID and as long as you use its GCM registration Id as a message recipient ID.

Icon

Android only.

The default push notification icon is your app icon but any custom icon can be set to be displayed in the push.

🚧

Note

Be informed that different icon's behavior may be observed on different devices depending on the Android mobile operating system in use.

Also, be aware that the app icon is a small two-dimensional representation of your app's identity and it appears in monochrome in the status bar. If your app sends a wide variety of notifications, you may replace this icon with a symbol that reflects the content type.
More details about Android notifications can be found here.

Setting custom icons in Ionic 5 and Ionic 4 projects with libraries version 1.1

To set a custom push notification image:

  1. In the Source tab, upload your custom image, for example, icon_name.png into the resources folder:
  1. Set it as a push image under Push Notifications tab > Advanced setting > Icon at the bottom of the Send push notification tab.

📘

You will need to unfold the Advanced settings folder first:

📘

Note that the icon file name must contain only lower-case letters and digits [a-z 0-9 _ ].

  1. Open scripts/config.xml.
  2. Under the line <platform name="android">, insert <resource-file src="resources/icon_name.png" target="app/src/main/drawable/icon_name.png"/> (When editing, you receive a warning about editing a file in the Source tab):

👍

Adding both custom sound and custom icon (image) to project

If you need to add to your project both custom sound and custom icon (image), make sure that in the config.xml file the information about the custom sound file is added before the information about custom icon (image).

🚧

Important note!

Be informed that configuring the config.xml file is the final step and is not to be followed by any other configuration modifications! If this condition is not observed, sending push notifications with custom images will fail!

Setting custom icons in Ionic 4 projects with libraries version 1.0

  1. In the Source tab, upload your custom image, for example, icon_name.png into the CORDOVA/resources/android/ folder and set it as a push image under Advanced settings > Icon at the bottom of the Send push notification tab. Note that the icon file name must contain only lower-case letters and digits [a-z 0-9 _ ].
  2. Open CORDOVA/scripts/config.xml.
  3. Under the line <platform name="android">, insert <resource-file src="resources/android/icon_name.png" target="app/src/main/res/drawable/icon_name.png"/> (When editing, you receive a warning about editing a file in the Source tab):

📘

Important note!

An icon file name must contain only lower-case letters and digits [a-z 0-9 _ ].

Setting custom icons in JQM projects with libraries version 5.1

  1. Upload your custom image, for example, icon_name.png icon into the corresponding folder in the Source tab: CORDOVA/resources/android/ and set it as a push image.
  2. An icon file name must contain only lower-case letters and digits [a-z 0-9 _ ].
  3. Open CORDOVA/config.xml.
  4. Under the line <platform name="android">, insert <resource-file src="resources/android/icon_name.png" target="app/src/main/res/drawable/icon_name.png"/> (When editing, you receive a warning about editing a file in the Source tab):
  1. Open Push Notifications tab > Advanced setting > Icon and insert in the field icon_name.

📘

Note

Read more about icon sizes and supporting multiple screens here.

🚧

There are some use cases to be aware of:

  1. For Android 6.0 or above, a white square sign appears in the status – this is a material design requirement from Google. To avoid this, the icon needs to use transparent pixels.
  2. Choose to display Icons or Images in the apps using Android 5.0 or lower – they cannot be used in combination.

Setting custom icons in JQM projects with libraries version 5.0

  1. Upload your custom image, for example, icon_name.png icon into the corresponding Source/CORDOVA/platforms/android/res/drawable/ folder to set it as a push image. If there is no drawable folder, simply create one.
  2. An icon file name must contain only lower-case letters and digits [a-z 0-9_ ].
  3. In the Source tab, open the WEB_RESOURCES > app > startScreen.js file. (When editing, you receive a warning about editing a file in the Source tab).
  4. Find the PushNotification.init function and add the icon property with the 'icon' value.

Icon Color

Android only.

The background color of a push notification Icon is supported on devices with Android 5.0 and higher. Click on the square in the corresponding field to get to the color palette.

📘

Note

Color is set in #rrggbb format.

Image

Android only.

An image can be shown as a large icon for Android notifications (appearing in the upper right corner).

Adding custom images

A custom image can be set to be displayed in the push.

To set a custom push notification image, follow the steps similar to what need to be taken for adding custom icons.
You can check this section for instructions on how to add custom icons for different project types (and different libraries).

🚧

Important note!

The only difference is that the image_name will need to be inserted for the Push Notifications tab > Advanced setting > Image field (instead of Icon):

📘

Note that the image file name must contain only lower-case letters and digits [a-z 0-9 _ ].

Launch Image

iOS only.

The image is launched on a device when a user taps an action button or moves the action slider.

Priority

Selecting the message priority when sending pushes: Default, Normal, or High.

  • Normal (interpreted as 5 for iOS and normal for Android) will attempt to deliver the notification at a time which conserves device battery power.
  • High (interpreted as 10 for iOS and high for Android) will attempt to deliver the notification immediately (or immediately after it was scheduled).
    Setting this parameter to Default (or null in the REST request) will stipulate the default server behavior according to the service policy (for iOS – 10, for Android – normal).

📘

Note

More information on setting the message priority for Android OS can be found here.
Go here to learn more about Apple Push Notification service (APNs).

Content-available

iOS only.

Tick the check box to enable the message content, then set the value to 1 to awaken the app.

Action buttons

Android only.

To specify titles for your push action buttons and icons, click Add, then enter the corresponding names.

The list of objects to represent buttons that will be shown below the notification.

  • title – the specified button title;
  • icon – the image to be displayed on the left side of the text. You can read here or here about how to upload custom images;
  • callback – the global function of the app. Push object will be sent as an argument.

Push Message Data

In this section, you can see the approximate amount of data being sent with your push. Appery.io doesn’t set any limits for sending pushes, however, there is the 4kB restriction set by Google and Apple. So, monitoring push message data is needed to make sure that you do not exceed the allowed amount.

Push Notifications Settings

In the Settings view, you can:

  • Find and reset the Push API Key;
  • Switch the database to link your project to another database;
  • Turn the push notification sound on or off;
  • Specify to show or not show the alert;
  • Specify the Badge (iOS only);
  • Specify Android OS and iOS settings, including the iOS push certificate uploading.

Push Notifications Statistics

On the push notifications Statistics tab, you can see your sending statistics.

Working With Channels

In the predefined Devices collection, there is a Channels column. It has an Array type and can contain any amount of values.

Channels – useful concept that can help classify devices.

For example, there is an application with two versions – freeand paid. Using the code of your app you can easily set needed values in the Channels column via the update REST service.

You can specify the first channel for free and the second channel for a fee, enabling sending different push notifications for each application type. You can also add one generic channel for both application types to send information to both.
The Channels column for devices running the free version:

  • [1, 3] //1 - means free and 3 means common

The Channels column for devices running the paid version:

  • [2, 3] //2 - means paid app and 3 means common

In this way, sending push notifications to the first ([1]) channel will guarantee that this notification will be delivered to the free version of the app only. Sending push notifications to the second ([2]) channel guarantees that only devices with the paid version of the application will receive the message. And sending push notifications to the third channel ([3]) means that both types of the app will receive the notification.

Obtaining DeviceID and Token

The deviceID variable makes it possible to send push notifications directly to specific devices.

AngularJS

Obtaining deviceID and token in AngularJS projects has been automated by using the following code:

pushSettings = Apperyio.config('PushNotification');
pushSettings.deviceId
pushSettings.token

jQuery Mobile

Once the push notifications are enabled in App settings (with Use push notification checked), the application is automatically registered in the Devices collection of the database.
When the application is first launched from the device after the Device ready event, the deviceID can be retrieved by the pushNotificationDeviceID local storage variable.
Use a Device ready event and delay of 1ms to retrieve the deviceID variable:

setTimeout(function() {
    alert(localStorage.getItem('pushNotificationDeviceID'));
}, 1);

📘

Note

The device.uuid parameter or other deviceID variables that can be retrieved by 3rd party applications are not the variables that Appery.io push notifications need to work properly. Use only pushNotificationDeviceID.

To use this variable in mapping, define the local storage variable with the same name.
When first launched from the device, a new record with the deviceID of the phone that the application was launched from is added to the Devices collection.

To get the token parameter, use the pushNotificationToken local storage variable the same way you used deviceID:

setTimeout(function() {
    alert(localStorage.getItem('pushNotificationToken'));
}, 1);

To target a specific ID, use deviceID instead of a token because a token is issued by Apple/Google services and can be changed.

Push Notification Events

  • Push initialize – fires when the app initializes a connection with the server;
  • Push notification – fires when the device receives a notification. You can access message data in the handler of this event.
    For example, the code below will display the push notification message: alert(data.message);
  • Push registration fail – fires when a device registration fails;
  • Push registration success – fires when a device registration is successful.

For more details on push notification events in Ionic 4/5 projects read here.

Read here on how to add and use events in jQuery Mobile.

📘

Reading Data from Push Notification Messages

This blog post shows how to read data from a Push Notifications message.

Push Notification Send Errors

Sometimes sending push notifications can fail. It happens for multiple reasons. Errors are returned by Firebase Cloud Messaging, Google Cloud Messaging, or Apple Push Notification providers and shown in the Scheduled and history view:

Some push notification errors summary:

Error

Description

Provider

Invalid device token

Device token wasn't registered in FCM or was invalidated.

Firebase Cloud Messaging

Can't authenticate to Google. Please check Firebase Admin SDK JSON File

User has specified invalid Firebase Admin SDK JSON File.

Firebase Cloud Messaging

Device token has a length of [9] and not the required 64 bytes

User has specified invalid device token (token has incorrect length).

Apple Push Notification

Sending push notification fail: argument cannot be null

One of required parameters for sending push is missing (token, payload, api key).

Invalid registration

User has not specified device token, or it is invalid.

Google Cloud Messaging

📘

Note

FCM (Firebase Cloud Messaging) error codes can be found here.
APNs (Apple Push Notification Service) error codes can be found here (Table 5-1).
GCM (Google Cloud Messaging) error codes can be found here.

See also Push Notification REST API.

More Help Resources

More help resources are linked to the blog, our YouTube channel and other websites.