Device Registration API¶

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.

Important

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:

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

Step1: Registering with APNS¶

To initiate the sequence and register for push notifications with APNS add the following code:

Objective-CSwift

// Use this code for iOS 9 or earlier
// AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes: (UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound) categories:nil];
    [[UIApplication sharedApplication] registerUserNotificationSettings:settings];
    dispatch_async(dispatch_get_main_queue(), ^{
        [[UIApplication sharedApplication] registerForRemoteNotifications];
    });
    return YES;
}

// Use this code for iOS 10 or higher
// AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
    center.delegate = self;
    [center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert + UNAuthorizationOptionBadge + UNAuthorizationOptionSound) completionHandler:^(BOOL granted, NSError * _Nullable error) {
        dispatch_async(dispatch_get_main_queue(), ^{
            [[UIApplication sharedApplication] registerForRemoteNotifications];
        });
    }];
    return YES;
}

To receive the device token from APNS and then register the device with Backendless, application must declare the following method in main application delegate:

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

// Use this code for iOS 9 or earlier
// AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let settings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
    UIApplication.shared.registerUserNotificationSettings(settings)
    DispatchQueue.main.async {
        UIApplication.shared.registerForRemoteNotifications()
    }
    return true
}

// Use this code for iOS 10 or higher
// AppDelegate.swift                                              

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    let center = UNUserNotificationCenter.current()
    center.delegate = self
    center.requestAuthorization(options: [.alert, .badge, .sound]) { (granted, error) in
    DispatchQueue.main.async {
        UIApplication.shared.registerForRemoteNotifications()
        }
    }
    return true
}

To receive the device token from APNS and then register the device with Backendless, application must declare the following method in main application delegate:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    // register device with Backendless here
}

Step 2: Registering with Backendless¶

The following APIs for token/device registration are available:

Objective-CSwift

// Associate registration with the 'default' channel and no expiration
- (void)registerDeviceWithDeviceToken:(NSData * _Nonnull)deviceToken responseHandler:^(NSString * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

// Associate registration with the channels and no expiration   
- (void)registerDeviceWithDeviceToken:(NSData * _Nonnull)deviceToken channels:(NSArray<NSString *> * _Nonnull)cannels responseHandler:^(NSString * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

// Associate registration with the 'default' channel and the expiration date
- (void)registerDeviceWithDeviceToken:(NSData * _Nonnull)deviceToken expiration:(NSDate * _Nonnull)expiration responseHandler:^(NSString * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

// Associate registration with the channels and the expiration date
- (void)Backendless.shared.messaging registerDeviceWithDeviceToken:(NSData * _Nonnull)deviceToken channels:(NSArray<NSString *> * _Nonnull)channels expiration:(NSDate * _Nonnull)expiration responseHandler:^(NSString * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

// Associate registration with the 'default' channel and no expiration
func registerDevice(responseHandler: ((String) -> Void)!, errorHandler: ((Fault) -> Void)!)
func registerDevice(deviceToken: Data, responseHandler: ((String) -> Void)!, errorHandler: ((Fault) -> Void)!)    

// Associate registration with the channels and no expiration  
func registerDevice(channels: [String], responseHandler: ((String) -> Void)!, errorHandler: ((Fault) -> Void)!)
func registerDevice(deviceToken: Data, channels: [String], responseHandler: ((String) -> Void)!, errorHandler: ((Fault) -> Void)!) 

// Associate registration with the 'default' channel and the expiration date
func registerDevice(expiration: Date, responseHandler: ((String) -> Void)!, errorHandler: ((Fault) -> Void)!)
func registerDevice(deviceToken: Data, expiration: Date, responseHandler: ((String) -> Void)!, errorHandler: ((Fault) -> Void)!) 

// Associate registration with the channels and the expiration date
func registerDevice(channels: [String], expiration: Date, responseHandler: ((String) -> Void)!, errorHandler: ((Fault) -> Void)!)
func registerDevice(deviceToken: Data, channels: [String], expiration: Date, responseHandler: ((String) -> Void)!, errorHandler: ((Fault) -> Void)!)

where:

Argument	Description
`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. If a value is not provided, Backendless registers the device with the `default` channel;

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:

Objective-CSwift

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [Backendless.shared.messaging registerDeviceWithDeviceToken:deviceToken responseHandler:^(NSString *registrationId) {
        NSLog(@"Device has been registered in Backendles");
    } errorHandler:^(Fault *fault) {
        NSLog(@"Error: %@", fault.message);
    }];
}

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    NSLog(@"Device registration failed: %@", error.localizedDescription);
}

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Backendless.shared.messaging.registerDevice(deviceToken: deviceToken, responseHandler: { registrationId in
        print("Device has been registered in Backendless")
    }, errorHandler: { fault in
        print("Error: \(fault.message ?? "")")
    })
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    print("Device registration failed: \(error.localizedDescription)")
}

Codeless Reference¶

push_device_registration_api_1

where:

Argument	Description
`channel name`	A list of messaging channels the device registration will be associated with. Messages published to the channels will be delivered to the associated devices. If no values are passed to this parameter, then Backendless registers the device with the `default` channel.
`return result`	Returns an object with the `registrationId` parameter, containing a `Map` between Backendless channel name (key name in the map) and the registration ID of the device for that channel (value assigned to the key). When a device is registered with multiple Backendless messaging channels, this map will contain a mapping for each channel.

The example below registers the device with the "ads" and "discount" channels:

push_device_registration_api_2