iOS Badging and Auto Badging

When you update a device's badge count, use the methods provided by the Urban Airship SDK to ensure the device token's registration is in sync with the client application. 

You can then update the device's badge number easily, via push request calls made from either the Urban Airship Dashboard or the API.

App Implementation

To enable auto badging in the client application add the following call in the didFinishLaunchingWithOptions method of your ApplicationDelegate.

[[UAPush shared] setAutoBadgeEnabled: YES];

 

Below is a code snippet from the Urban Airship iOS library which shows how the default notification handler deals with an included badge number:

// Badge
        NSString *badgeNumber = [apsDict valueForKey:@"badge"];
        if (badgeNumber && ![UAirship push].autobadgeEnabled && [pushDelegate respondsToSelector:@selector(handleBadgeUpdate:)]) {
            [pushDelegate handleBadgeUpdate:[badgeNumber intValue]];
        }

        // Sound
        NSString *soundName = [apsDict valueForKey:@"sound"];
        if (soundName && [pushDelegate respondsToSelector:@selector(playNotificationSound:)]) {
            [pushDelegate playNotificationSound:[apsDict objectForKey:@"sound"]];
        }
    }

 

Note that this will only execute if a badge value is included in the push payload sent to the device. When a badge value is present, it will update the local application badge number to that which was received if autobadge is enabled. Otherwise it expects your own handler to do this along with any additional handling you implement.

You can also manipulate the badge number through the client library by sending a setBadgeNumber message to the UAPush instance.

Below is this method's implementation: 

- (void)setBadgeNumber:(NSInteger)badgeNumber {

    if ([[UIApplication sharedApplication] applicationIconBadgeNumber] == badgeNumber) {
        return;
    }

    UA_LDEBUG(@"Change Badge from %ld to %ld", (long)[[UIApplication sharedApplication] applicationIconBadgeNumber], (long)badgeNumber);

    [[UIApplication sharedApplication] setApplicationIconBadgeNumber:badgeNumber];

    // if the device token has already been set then
    // we are post-registration and will need to make
    // an update call
    if (self.autobadgeEnabled && (self.deviceToken || self.channelID)) {
        UA_LDEBUG(@"Sending autobadge update to UA server.");
        [self updateChannelRegistrationForcefully:YES];
    }
}

 

Resetting Badge Value:

The resetBadge method is available through the UAPush class. This method is a wrapper for the setBadgeNumber method, passing it a value of 0. If you would like the badge number to be cleared when the app is opened, we suggest calling [[UAPush shared] resetBadge] in the following three methods of your ApplicationDelegate:

  1. didFinishLaunchingWithOptions
  2. didReceiveRemoteNotification
  3. applicationDidBecomeActive

You may be wondering why the device registration is not updated as soon as we parse the request payload specifying the new badge value. Auto badging only updates from the client library to ensure that the device's stored badge number does not differ from that which is registered for the device in Urban Airship's database. Pushes do not always reach the device, whether it be deliberate or an issue from APNS. If Urban Airship does not wait for the client to update the badge as a result of receiving the remote notification, the client badge values may become out of sync.

 

Setting badges from the Web Message Composer:

Please see the iOS specific section of the Message Composer guide for details.

Setting badges from the API:

Please review the iOS specific payload section of our Push API documentation for details on making calls to our Push API that change the badge value.

Related Content