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:

 

The process of device registration consists of two steps:

1.Registering for push notifications with Apple Push Notification Service (APNS) and receiving a device token.
2.Registering the device token with Backendless.

 

To initiate the sequence and perform step (1), invoke the following method:

[backendless.messaging registerForRemoteNotifications];
backendless.sharedInstance().messaging.registerForRemoteNotifications()

The method above registers device with APNS for all available notification types (alert, badge and sound). If your app requires a subset of notification types,  step (1) must be performed as shown below:

let settings = UIUserNotificationSettings(forTypes: [.Alert, .Badge, .Sound], categories: nil)
UIApplication.sharedApplication().registerUserNotificationSettings(settings)
UIApplication.sharedApplication().registerForRemoteNotifications()
backendless.sharedInstance().messaging.registerForRemoteNotifications()

 

To receive the device token from APNS, application must declare the following method in main application delegate:

- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {
  // register device with Backendless here
}
func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {
  // register device with Backendless here
}

The body of the method shown above must perform step (2), which means calling an API which registers the device token (and thus the device itself) with Backendless.

The following APIs for token/device registration are available:

Synchronous Methods:

// Register device token with Backendless. Associate registration
// with the 'default' channel and no expiration.
// If server returns a fault, it is thrown as an exception
-(NSString *)registerDeviceToken:(NSData *)deviceToken;

// Register device token with Backendless. Associate registration
// with the specified channels and request the registration to 
// expire on the specified expiration date.
// If server returns a fault, it is thrown as an exception
-(NSString *)registerDevice:(NSArray<NSString*> *)channels 
                             expiration:(NSDate *)expiration 
                             token:(NSData *)deviceToken;

// Register device token with Backendless. Associate registration
// with the 'default' channel and no expiration.
// If server returns a fault, it is delivered through the "fault" argument.
-(NSString *)registerDeviceToken:(NSData *)deviceToken 
                                  error:(Fault **)fault;
                                  
// Register device token with Backendless. Associate registration
// with the specified channels and request the registration to 
// expire on the specified expiration date.
// If server returns a fault, it is delivered through the "fault" argument.
-(NSString *)registerDevice:(NSArray<NSString*> *)channels 
                             expiration:(NSDate *)expiration 
                             token:(NSData *)deviceToken 
                             error:(Fault **)fault;
// Register device token with Backendless. Associate registration
// with the 'default' channel and no expiration.
// If server returns a fault, it is thrown as an exception
func registerDeviceToken(_ deviceToken: NSData!) -> String

// Register device token with Backendless. Associate registration
// with the specified channels and request the registration to 
// expire on the specified expiration date.
// If server returns a fault, it is thrown as an exception
func registerDevice(_ channels: [String]!, 
                    expiration expiration: NSDate!, 
                    token deviceToken: NSData!) -> String

// Register device token with Backendless. Associate registration
// with the 'default' channel and no expiration.
// If server returns a fault, it is delivered through the "fault" argument.
func registerDeviceToken(_ deviceToken: NSData!, 
                         error fault: AutoreleasingUnsafeMutablePointer<Fault?>) -> String
                                  
// Register device token with Backendless. Associate registration
// with the specified channels and request the registration to 
// expire on the specified expiration date.
// If server returns a fault, it is delivered through the "fault" argument.
func registerDevice(_ channels: [String]!, 
                    expiration expiration: NSDate!, 
                    token deviceToken: NSData!, 
                    error fault: AutoreleasingUnsafeMutablePointer<Fault?>) -> String

Asynchronous Methods:

// Register device token with Backendless. Associate registration
// with the 'default' channel and no expiration.
// Method's return value or any fault returned by the server are 
// delivered through the "responder" object;
-(void)registerDeviceToken:(NSData *)deviceToken responder:(id <IResponder>)responder;

// Register device token with Backendless. Associate registration
// with the specified channels and request the registration to 
// expire on the specified expiration date.
// Method's return value or any fault returned by the server are 
// delivered through the "responder" object;
-(void)registerDevice:(NSArray<NSString*> *)channels 
                       expiration:(NSDate *)expiration 
                       token:(NSData *)deviceToken 
                       responder:(id <IResponder>)responder;

// Register device token with Backendless. Associate registration
// with the 'default' channel and no expiration.
// Method's return value or any fault returned by the server are 
// delivered through block-based callbacks
-(void)registerDeviceToken:(NSData *)deviceToken 
                            response:(void(^)(NSString *))responseBlock 
                            error:(void(^)(Fault *))errorBlock;
                                  
// Register device token with Backendless. Associate registration
// with the specified channels and request the registration to 
// expire on the specified expiration date.
// Method's return value or any fault returned by the server are 
// delivered through block-based callbacks
-(void)registerDevice:(NSArray<NSString*> *)channels 
                       expiration:(NSDate *)expiration 
                       token:(NSData *)deviceToken 
                       response:(void(^)(NSString *))responseBlock 
                       error:(void(^)(Fault *))errorBlock;
// Register device token with Backendless. Associate registration
// with the 'default' channel and no expiration.
// Method's return value or any fault returned by the server are 
// delivered through the "responder" object;
func registerDeviceToken(_ deviceToken: NSData!, responder responder: IResponder!) -> Void

// Register device token with Backendless. Associate registration
// with the specified channels and request the registration to 
// expire on the specified expiration date.
// Method's return value or any fault returned by the server are 
// delivered through the "responder" object;
func registerDevice(_ channels: [String]!, 
                    expiration expiration: NSDate!, 
                    token deviceToken: NSData!, 
                    responder responder: IResponder!) -> Void

// Register device token with Backendless. Associate registration
// with the 'default' channel and no expiration.
// Method's return value or any fault returned by the server are 
// delivered through block-based callbacks
func registerDeviceToken(_ deviceToken: NSData!, 
                         response responseBlock: ((BackendlessCollection!) -> Void)!, 
                         error errorBlock: ((Fault!) -> Void)!) -> Void
                                  
// Register device token with Backendless. Associate registration
// with the specified channels and request the registration to 
// expire on the specified expiration date.
// Method's return value or any fault returned by the server are 
// delivered through block-based callbacks
func registerDevice(_ channels: [String]!, 
                    expiration expiration: NSDate!, 
                    token deviceToken: NSData!, 
                    response responseBlock: ((BackendlessCollection!) -> Void)!, 
                    error errorBlock: ((Fault!) -> Void)!) -> Void

where:

deviceToken- device token obtained from Apple Push Notification Service;
expiration- a timestamp when the device registration should expire;
channels- channel (or a collection of channels) to receive messages from. For the method without the argument, the "Default" channel is used;
responder- for asynchronous API calls - a Responder instance to receive the result or fault objects.

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

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:
The following methods demonstrate registering a device for push notifications. Methods must be added to the main application delegate class:

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [backendless initApp:APP_ID secret:SECRET_KEY version:VERSION_NUM];   
    [backendless.messaging registerForRemoteNotifications];
    return YES;
}

- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {
    [backendless.messaging registerDeviceToken:deviceToken];
}
    
- (void)application:(UIApplication *)app didFailToRegisterForRemoteNotificationsWithError:(NSError *)err {
   // handle error
}
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        
  backendless.sahredInstance().initApp(APP_ID, secret:SECRET_KEY, version:VERSION_NUM)
  backendless.sahredInstance().messaging.registerForRemoteNotifications()
  return true
}

func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {
  backendless.sahredInstance().messaging.registerDeviceToken(deviceToken)
}
    
func application(application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: NSError) {
  // handle error
}

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