If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

See the Push notification REST API here.

Introduction

The Appery.io push notifications feature allows you to send push messages to users who have installed your app, it also allows you to  customise the push notifications, and the of option sending any data to devices that are available to Appery.io users.

There is a difference when it comes to creating applications with push notification services in jQuery Mobile and AngularJS projects.

In jQuery Mobile projects, all push notification services are created automatically, while in AngularJS, importing Apperyio Push plug-in with the further invoking its PushRegisterDevice service is needed to register a device in Apple/Google push services, and add it to the Appery.io database.

To send push notifications, the app must be installed on the device (PhoneGap app).

Quickstart

If you are new to sending push notifications you may want to see the step-by-step tutorials:

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

Enabling push notifications

To turn on the send push notification feature you go to the Push Notifications tab and  check the Enable push notifications  box:1st

Once you’ve turned on the push notifications, you’ll be able to choose a database that you want to link the app with. Linking a database is necessary because all the devices are stored in the Devices collection in the appropriate database. If the database is already linked with another app, it will not be listed in the database list. You can find the app name in the database Settings in which the current database it is linked. You can unlink the database and apps, but all of the data in the Devices collection will be cleared.

Once the database is linked, you can go to the Send push notification tab to configure sending options.

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 Advanced settings at the bottom of the Send push notification tab.

Expiration date

Time stamp in UTC TZ, when the provider (Apple, Google, etc.) should stop re-sending a notification to an offline device.

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, as with any other collection.

When using the device filtering using a query builder, they are predefined sets of operations for each data type:
Filtering

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:
Channels

The not includes operator ensures that push notifications will be 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:
DeviceID

See how to retrieve the deviceID below.

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

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

Click Add filter to add more specific filters:
TimeZone

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, which is filtered by the query.

Custom sound

In the Sound file section you can set your own sound file to play when the push arrives. Set an empty string for no sound if this does not get specified the default sound is selected. To use a custom sound you’ll need to first open up the app and make sure that you have the Push sound enabled in the global Settings in the Push Notifications tab. Then you will need to upload the sound to the source/iOS/appname/www/soundFileName.wav  tab (for iOS) or source/ANDROID/appname/res/raw/soundFileName.wav (for Android):

Android

iOS

There is no default raw folder in source/ANDROID/appname/res/, so you’ll need to create it first.

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:

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

Silent mode works only on iOS 8 and higher.

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:

  • The push will be sent on the date and time defined according to the time zone of the device.
  • The Push will be sent to all devices in different time zones accordingly, and 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’re 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 truncated to minutes.
    If the push should be sent to all devices at once, check the second option.
  4. Define the date and time when the 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 the push (depending on the time zone of the device), its badge, and the status. 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 – the push has been sent to all devices.
  • Error – the 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 in the list.

Click the Filter scheduled to filter list items by status (sent, wait, error, process) and/or by date:
filter

Changing scheduled notifications

Scheduled notifications with the status wait can be changed. To do that, click edit:
editable

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 send to device. Click Add and enter parameters and values you would like to send with your push:CustomData

There are no restrictions for the custom data to be sent in a push notification, but there are some limitations for push notifications size on the part of Google (4kB) and Apple (2kB). 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

For 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 and delay while Idle (see below) parameters 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 this 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, you can set any custom icon to be displayed in the push.

To set a custom push notification image, do the following:

  1. Upload your custom image, for example, icon_name.png icon into the corresponding ANDROID/project_name/res/drawable/ folder to set it as a push image. If there is no drawable folder, just create one.
  2. An icon file name must contain only lower-case letters and digits [a-z 0-9 _ .]

    Read more about icon size and supporting multiple screens here.

  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:code
  5. The new icon is added.

The Icon size is reduced if you also add an Image to your push notification: Icons

There are some use cases to be aware of:

  1. For Android 6.0, 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.

Icon colour

Android only.

The background colour 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 colour palette.

Color is set in #rrggbb format.

Image

Android only.

This image can be shown as a large icon for Android notifications (appearing in the upper right corner). There are several ways to use images:

  1. With an Icon, prior to uploading an image file is mandatory. The path for upload is: ANDROID/project_name/res/drawable/icon_name.png. Next, you should enter the uploaded image file name in the field provided:
  2. Another way is to upload an image to the assets folder, for example, with the Media manager. In this case, the upload path will look like this:
    WEBRES
  3. As an alternative, you can upload it in the Source tab: www/img/my_picture.png or www/{folder_where_you _uploaded_picture}/my_picture.png.
  4. Also, payload.image can have a link to the external resource folder, e.g.: http://exadel.com/assets/ApperyIO/appery.io_logo_221x46.png.

Adding an Image reduces the Icon size in your push notification: Icons

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).

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.

Delay while idle

Android only.

With the collapseKey parameter set and the Delay while idle box checked, only the last push notification from every collapse key will be delivered.

Action buttons

Android only.

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

The list of objects that 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 send 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 are restrictions on by Google (4kB) and Apple (2kB). 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

At 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

Channels – useful concept that can help classify devices.

For example, there is a application with two versions – free and 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 you to send different push notifications for each type of application. You can also add one generic channel for both application types to send information necessary to both.

The Channels column for devices running the free version:

The Channels column for devices running the paid version:

In this way, sending push notifications to the first ([1]) channel will guarantee that this notification will be delivered only to the free version of the app. Sending push notifications to the second ([2]) channel guarantees that only devices with the paid version of 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:

jQuery Mobile

Once the push notifications are enabled in App settings(Use push notification is 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:

From the Appery.io builder:DeviceReady

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 the pushNotificationDeviceID.

To use this variable in mapping, define the local storage variable with the same name:pushNotificationDeviceID

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 the deviceID:

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

AngularJS

  • push-notification – fires when the device receives a notification.
  • pushinit – fires when the app initializes connection with server.

You can handle these event as following:

For more, on push notification events in AngularJS projects read here.

jQuery Mobile

  • Push initialize – fires when the app initializes connection with server.
  • Push notification – fires when the device receives a notification. You can access message data in handler of this event. For example, code below will display the push notification message:

    If you’re using jQuery Mobile libraries version earlier than 3.0, use the following syntax:
    alert(data.aps.alert);

  • Push registration fail – fires when device registration fails.
  • Push registration success – fires when device registration is successful.

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 can happen for multiple reasons. Errors are returned by Google Cloud Messaging or Apple Push Notification services and shown in the Scheduled and history view:

Push notification errors summary:

Error Description Service
Invalid registration User has not specified device token, or it is invalid. Google Cloud Messaging service.
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 Service.
Sending push notification fail: argument cannot be null. One of required parameters for sending push is missing (token, payload, api key).

GCM (Google Cloud Messaging) error codes can be found here.

APNs (Apple Push Notification Service) error codes can be found here (Table 5-1).

See also Push Notification REST API.

More help resources

More help resources are links to the blog, our YouTube channel and other web sites.