Publish Push Notifications

Top  Previous  Next

Backendless supports push notification delivery to iOS, Android and Windows Phone devices. A device must be registered (see the Device Registration API) in order to receive a push notification. A push notification can be published via API or using the Backendless Console. The content of a push notification consists of a message body and the specialized message headers.

 

Publish a Push Notification from Console

To publish a push notification from Backendless console, navigate to the Messaging screen and click the Devices tab. Make sure there are registered devices, otherwise a push notification has nowhere to go.

Select the check boxes for the device(s) you would like to send a notification to.
Make sure to enter the message headers. The format of the headers must be: "header1-name":"header1-value", "header2-name":"header2-value". For example:

"android-ticker-text":"ticker text", "android-content-title":"content title", "android-content-text":"content text"

To send a push notification to specific devices, select the devices from the list and click the Selected devices checkbox.
To send a push notification to devices with a particular operating system, select the corresponding checkboxes.
Click the Publish button.
backendless-publishing-push-notification-console.zoom50

 

Publish Push Notification with API

Message publishing API supports the following scenarios:

 

Basic push notification - In the simplest form a push notification is sent to a channel and this to all the devices registered with the channel. The notification message must contain appropriate headers which control the appearance of the notification on the devices. Example.
 
Push notification delivered to devices grouped by the OS - With this type of message delivery push notifications can be sent to all devices of a specific operating system (or a group of).  This includes delivery to Android, iOS or Windows Phone devices or a any combination of. Example.
 
Push notification delivered to specific devices - This delivery type allows push notification delivery to individual devices. Example.
 
Delayed publishing - For all scenarios described above a push notification request can be configured to be executed at a later time (thus "delayed publishing"). Messages published with this delivery option can be canceled at any time using the message cancellation API. Example.

 

Push Notification Headers

The headers described below must be added to the "publish options" object or in case of REST clients, they are plain message headers:

Operating System

Headers

Description

iOS

"ios-alert":value

Sets the text of the alert message. If the header is not present and the published notification targets the iOS devices, Backendless sets the header to the value of the "message" argument. To disable this behavior, set the ios-alert header to null.

"ios-badge":value

Sets the value to update the badge with

"ios-sound":URL string or array of bytes

Sets either a URL for the sound notification to play on the device or an array of bytes for the sound to play.

Android

"android-ticker-text":value

Sets the text of the ticker showing up at the top of a device's screen when the device receives the notification.

"android-content-title":value

Sets the title of the notification as it is visible in the Android Notification Center

"android-content-text":value

Sets the message of the notification which appears under android-content-title in the Android Notification Center.

Windows Phone

"wp-title":value,
"wp-content":value

Sets the title and the content of a toast notification.

"wp-type":"TILE":
"wp-title" : value,
"wp-backgroundImage" : URL string,
"wp-badge" : number value,
"wp-backTitle" : value,
"wp-backImage" : URL string,
"wp-backContent" : value

Sets the properties for a tile notification.

"wp-type":"RAW",
"wp-raw":XMLString

Sets the properties for a raw notification

Method Signatures

Synchronous Methods:

Publishes push notification to the "Default" channel. Headers must be added to the publishOptions argument.

public MessageStatus Backendless.Messaging.publish( Object message, 
                                                    PublishOptions publishOptions ) throws BackendlessException

 

Same as above, but the notification is published into the specified channel. Headers must be added to the publishOptions argument.

public MessageStatus Backendless.Messaging.publish( String channelName, 
                              Object message, 
                              PublishOptions publishOptions ) throws BackendlessException

Publishes push notification to the "Default" channel. Headers must be added to the publishOptions argument. Delivery options can be used to:

1.Designate the message as "push notification only" or both a push notification and a pub/sub message.
2.Singlecast publishing - set a list of devices which should be receiving the notification.
3.Broadcast publishing - identify operating systems of the registered devices which should be receiving the notification.
4.Publish the message at a later time (delayed publishing).
5.Specify that the message should be republished multiple times (repeated publishing).

public MessageStatus Backendless.Messaging.publish( Object message, 
                              PublishOptions publishOptions, 
                              DeliveryOptions deliveryOptions ) throws BackendlessException

Same as above, but published into the specified channel.

public MessageStatus Backendless.Messaging.publish( String channelName, 
                              Object message, 
                              PublishOptions publishOptions, 
                              DeliveryOptions deliveryOptions ) throws BackendlessException

Asynchronous Methods:

Same set of methods as above, but executed asynchronously. The difference in the method signatures is the AsyncCallback<MessageStatus> argument:

public void Backendless.Messaging.publish( Object message, 
                                           PublishOptions publishOptions, 
                                           AsyncCallback<MessageStatus> responder )

public void Backendless.Messaging.publish( String channelName, 
                                           Object message, 
                                           PublishOptions publishOptions, 
                                           AsyncCallback<MessageStatus> responder )

public void Backendless.Messaging.publish( Object message, 
                                           PublishOptions publishOptions, 
                                           DeliveryOptions deliveryOptions, 
                                           AsyncCallback<MessageStatus> responder )

public void Backendless.Messaging.publish( String channelName, 
                                           Object message, 
                                           PublishOptions publishOptions, 
                                           DeliveryOptions deliveryOptions, 
                                           AsyncCallback<MessageStatus> responder )

where:

channelName- name of the channel to publish the notification to. If the channel does not exist, Backendless automatically creates it.
message- object to publish. The object can be of any data type - a primitive value, String, Date, a  user-defined complex type, a collection or an array of these types.
publishOptions- an instance of PublishOptions. When provided may contain publisher ID (an arbitrary, application-specific string value identifying the publisher), and/or a collection of headers.
deliveryOptions- an instance of DeliveryOptions. When provided may specify options for push notification delivery such as: deliver to specific devices (or devices grouped by the operating system), delayed delivery or repeated delivery.

 

Return value:

MessageStatus- a data structure which contains ID of the published message. Use the getMessageId() method to get the ID assigned to the message by the backend (the ID is needed to check the message publishing  status or cancel the message).

Errors:

The following errors may occur during the message publishing API call. See the Error Handling section for details on how to retrieve the error code when the server returns an error:

 

Error Code

Description

5003

Invalid repeatExpiresAt date in delivery options.

5007

User does not have the permission to publish messages

5030

Invalid publishAt date in the delivery options.

Examples:

Basic push notification

Targeting a group of devices (grouped by OS)

Targeting specific devices

Delayed publishing

Basic push notification

String applicationID = "YOUR-APP-ID";
String secretKey = "ANDROID-KEY";
String version = "v1";
// this call must be somewhere early on in the application initialization
Backendless.initApp( appContextOrActivity, applicationId, secretKey, version );

PublishOptions publishOptions = new PublishOptions();
publishOptions.putHeader( "android-ticker-text", "You just got a push notification!" );
publishOptions.putHeader( "android-content-title", "This is a notification title" );
publishOptions.putHeader( "android-content-text", "Push Notifications are cool" );
MessageStatus status = Backendless.Messaging.publish( (Object) "Hi Devices!", publishOptions );

Targetting a group of devices

String applicationID = "YOUR-APP-ID";
String secretKey = "ANDROID-KEY";
String version = "v1";
// this call must be somewhere early on in the application initialization
Backendless.initApp( appContextOrActivity, applicationId, secretKey, version );

DeliveryOptions deliveryOptions = new DeliveryOptions();

deliveryOptions.setPushBroadcast( PushBroadcastMask.ANDROID | PushBroadcastMask.IOS );

PublishOptions publishOptions = new PublishOptions();
publishOptions.putHeader( "android-ticker-text", "You just got a push notification!" );
publishOptions.putHeader( "android-content-title", "This is a notification title" );
publishOptions.putHeader( "android-content-text", "Push Notifications are cool" );

MessageStatus status = Backendless.Messaging.publish( "Hi Devices!", publishOptions, deliveryOptions );

Targeting specific devices

String applicationID = "YOUR-APP-ID";
String secretKey = "ANDROID-KEY";
String version = "v1";
// this call must be somewhere early on in the application initialization
Backendless.initApp( appContextOrActivity, applicationId, secretKey, version );

DeliveryOptions deliveryOptions = new DeliveryOptions();
deliveryOptions.addPushSinglecast( receiver-device-id );

PublishOptions publishOptions = new PublishOptions();
publishOptions.putHeader( "android-ticker-text", "You just got a private push notification!" );
publishOptions.putHeader( "android-content-title", "This is a notification title" );
publishOptions.putHeader( "android-content-text", "Push Notifications are cool" );

MessageStatus status = Backendless.Messaging.publish( "this is a private message!", publishOptions, deliveryOptions );

Delayed publishing

String applicationID = "YOUR-APP-ID";
String secretKey = "ANDROID-KEY";
String version = "v1";
// this call must be somewhere early on in the application initialization
Backendless.initApp( appContextOrActivity, applicationId, secretKey, version );


PublishOptions publishOptions = new PublishOptions();
publishOptions.putHeader( "android-ticker-text", "You just got a private push notification!" );
publishOptions.putHeader( "android-content-title", "This is a notification title" );
publishOptions.putHeader( "android-content-text", "Push Notifications are cool" );

DeliveryOptions deliveryOptions = new DeliveryOptions();
Date publishDate = new Date( System.currentTimeMillis() + 20000 ); // add 20 seconds
deliveryOptions.setPublishAt( publishDate );

MessageStatus status = Backendless.Messaging.publish( "This message was scheduled 20 sec ago", publishOptions, deliveryOptions );

 


Please let us know how we can improve the documentation by leaving a comment. All technical questions should be posted to the Backendless Support forum. We do not respond to the technical questions on the documentation pages.: