Device Registration

Top  Previous  Next

In order to receive push notifications from Backendless, a device must be registered using the API documented below. Device registration may optionally include a list of messaging channels and/or an expiration date/time when the registration should be canceled.

 

Push notifications can be published using either API or Backendless Console. When a push notification is published, it goes through a messaging channel. Channels provide a way to establish a level of filtering - devices registered with a channel will receive notifications published to the channel. However, there are other way to narrow down push notification delivery. For example, a push notification may be sent to a specific device or a group of devices.

 

If no channels are specified in the device registration call, Backendless registers the device with the default channel. If the device registration call references a non-existing channel, Backendless creates the channel and registers the device with it. Registration expiration is a point in time (expressed as a timestamp) when the device registration must expire. Backendless removes the device registration at the specified time and the device no longer receives published push notifications.

 

In order to receive push notifications on a mobile device, application running on the device must register with Backendless using the API call below:

 

Method Signature

Method:

POST

 

URL:

https://api.backendless.com/<version-name>/messaging/registrations

where:

<version-name>- name of the application's version. Application versions can be managed using Backendless Console. Login to the console, select an application, click Manage, then Versioning. Backendless automatically creates version "v1" for any new application.

Request Headers:

application-id: app-id-value
secret-key: secret-key-value
Content-Type:application/json
application-type: REST

where:

application-id- the ID of your application generated upon its creation. You can find this header in the Manage > App Settings section of the Backendless Console. This header is mandatory. Please refer to the Setup section for information on how to obtain the values for the header.
secret-key - the key of your application generated upon its creation. You can find this header in the Manage > App Settings section of the Backendless Console. This header is mandatory. Please refer to the Setup section for information on how to obtain the values for the header.
Content-Type- the static value, should be set to application/json. This header is mandatory.
application-type- the static value, should be set to REST. This header is mandatory.

 

Request Body:

{
 "deviceToken" : value,
 "deviceId" : value,
 "os" : "IOS" | "ANDROID" | "WP",
 "osVersion": value
 [,"channels": [channelName1, channelName2]],
 [,"expiration": timestamp in GMT0]
}

where:

deviceToken- a token assigned by the push notification service provider (Google Cloud Messaging, Apple Push Notifications, Microsoft Push Notification Service).
deviceId- a unique identification of the device where push notifications will be delivered to.
os- operating system identifier
osVersion- version of the operating system
channels- an array of Backendless messaging channels to subscribe to. Backendless delivers channel's message to the devices if the message is marked as a push notification.
expiration- a timestamp indicating when the device registration should expire.

 

Response Body:

{
 "registrationId" : value
}

Errors:

When the server-side reports an error, it returns a JSON object in the following format:

{
 "message":error-message,
 "code":error-code
}

 

The following errors may occur during the message publishing API call:

Error Code

Description

5004

Invalid expiration date. The expiration date must be after the current time.

8000

Property value exceeds the length limit. Error message should contain additional details about the violating property.

 

Example:
curl
-H application-id:value-from-backendless-console
-H secret-key:value-from-backendless-console
-H application-type: REST
-H Content-Type:application/json
-X POST
-d '{
  "deviceToken":"XXXXXXXXXXXXXXXXXXXXXXXXX",
  "deviceId":"XXXXXXXXXXXXXXXXXXXXXXXXX",
  "os":"ANDROID",
  "osVersion":"4.1"
  }'
-v https://api.backendless.com/v1/messaging/registrations

 


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