HowTo: Using iOS Badge operations

Official Content
This documentation is valid for:

For iOS users, badges are a very common UI feature that they are used to seeing in almost every native application which has any of the Push Notifications or Local Notifications feature. 

What is a badge?

badgeios1

As you can see, this screen has five applications with this badge feature on and many more which are not activated. The badge feature shows a number above the app icon in white and red. It is typically used by the iOS native framework to show:

a. The number of unread emails you have on your inboxes.

b. New text messages in your SMS/iMessage application.

c. New upgrades available in the Apple App Store.

d. New iOS upgrades available.

And many more. So, this feature is really useful and important if an application has push or local notifications and expects the user to react because it has recognized that some action from him is pending on the application.

This document is a simple tutorial to add this feature and some more related to an iOS Smart Device Application generated with GeneXus.

Step 1: Resources to get things Done

A few methods are provided in the Interop external object to enable and use this feature.

iOS Badges Interop Methods GeneXus15

SetBadgeNumber (Number) Sets the number to show over the aplication icon on the Home Screen of the iOS device. If the Number passed as a parameter is 0, the red badge icon should disapear.
iOSSetBadgeTextToTab (Text,TabIndex) Sets a text over the tab in the index passed as a parameter. This control is used for the tabs of a Dashboard, it is not valid for the tabs of a TabControl which is enabled by drag and drop from the toolbar. The index starts at 1 from left to right.
iOSSetSelectedTabIndex (TabIndex) Sets the tab in the TabIndex position as active. The indexes start at 1 from left to right.

 

Step 2: Coding Example

The example uses a Menu for Smart Devices object with 4-5 items and sets the Control to Tabs on the Dashboard properties.

Create the following Panel for Smart Devices object:

Layout:

badgelayout

Events:

Event 'iosSetBadgetext'
    Interop.IOSSetBadgeTextToTabIndex('test',2)
Endevent
Event 'iosSetTabIndex'
    Interop.IOSSetSelectedTabIndex(3)
Endevent
Event 'RemoveBadge'
    Interop.IOSSetBadgeTextToTabIndex("",2)
Endevent
Event 'iosSetBadgeNum'
    Interop.SetBadgeNumber(&varnum)
Endevent
Event 'iosSetBadge0'
    Interop.SetBadgeNumber(0)
Endevent

Add that Panel to the Dashboard and hit F5.

Step 3: Execution

SetBadgeNumber()
Result:

badgeio2

badgeios3

iosSetBadgeText()
Result:

badgeios4

Step 4: Complement the Local and Push Notifications

One of the most common uses of this feature is combined with Local and Push notifications. When a Notification is sent to the user, the badge number is automatically set to +1. So, when the user performs the action expected of the notification the app should subtract one to the current badge number.

The subtraction is not automatically done yet, because the action performed after the notification has to be tracked by the application logic.

If this isn't done, the badge number over the app icon will never change and look like some notifications are pending.

 

Notes

  • In order to use SetBadgeNumber method in iOS, the developer must include the remote notification background mode capability on the generated XCode project.
    • As of GeneXus 15 Upgrade 5, this feature can be added automatically by using Background Modes property with value "remote-notification".
    • For lower upgrades, you must call to RequestRemotenotificationsPermission method of Permissions external object before calling SetBadgeNumber (see the example below).
      Event 'MyEventForSettingBadgeNumber'
                Composite
                        Permissions.RequestRemoteNotificationsPermission()
                        Interop.SetBadgeNumber(&Numeric)
                EndComposite
      EndEvent
    • When the knowledge base uses LocalNotifications external object funcionalities, as of GeneXus 15 Upgrade 3 the permission will be generated automatically





Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.