HowTo: Use LocalNotifications external object in Native Mobile

Official Content
This documentation is valid for:

The LocalNotifications external object enables your app to alert users of scheduled events or alarms in the background, with no servers required as in Push Notifications in Native Mobile Applications.

This document is a brief guide of how to use Local Notifications in GeneXus for Native Mobile.

Step 1: Checking the objects that will let you add Local Notifications

There are two objects that are used to enable Local Notifications on the GeneXus Core module.

LocalNotificationsexternalobject-Location_201868113144_1_png

LocalNotifications structured data types 
This Structured Data Type (SDT) is used to define the configuration of the Local Notification. It is a collection of Items with DateTime and Text. The DateTime will be used to know when that Local Notification will be triggered, and the text will be the info shown to the user. You can define as many Local Notifications as you want. A single item on the SDT LocalNotifications Item is equivalent to one Local Notification.
image_201868113522_1_png

LocalNotifications external object
This external object has a method called CreateAlerts which expects an instance of a variable based on SDT LocalNotifications as an input parameter. When this action is executed, the app will schedule all the local notifications passed on the SDT LocalNotifications. 
LocalNotifications external object - Structure

Step 2: Programming the Local Notifications

To make them work, just create the following Procedure (e.g: named "SendLocalNotificationsServer").

In this example, this procedure is created to load the SDTLocal Notifications. Bear in mind that this can be done differently, as it is not compulsory to do it with a procedure.

Parm:

parm(out: &MySdtLocalNotifications);

Source:

&MySdtLocalNotificationsItems.DateTime = ymdhmstot(2012,06,07,16,56,00)
&MySdtLocalNotificationsItems.Text = "My Local Test"
&MySdtLocalNotifications.Add(&MySdtLocalNotificationsItems)

Variables:

MySdtLocalNotifications -> SDTLocalNotifications
MySdtLocalNotificationsItems -> SDTLocalNotifications.Item

Next, let's create a Panel object:

Layout:

LocalNotifIphone3

Events:

 Event 'SendNotification'
      Composite
          &MySdtLocalNotifications = SendLocalNotificationsServer()
          LocalNotifications.CreateAlerts(&MySdtLocalNotifications)
      EndComposite
 EndEvent

Step 3: Execution

Run your application.

First, hit the Panel button to start scheduling Local Notifications. After that, the Notifications have been scheduled and they will appear on your device at the time specified.

When the local notification is added:

LocalNotifIphone1

When the local notification is triggered.

LocalNotifIphone2

Sample

A working example of this method can be downloaded from: WorkingWithLocalNotifications.

TroubleShooting

The Create method of the external object returns a numeric value. If the returned value is 0, it means that there was no error in the execution. Otherwise, if the numeric value is different than 0, an execution error occurred.

Availability

This feature has been added to GeneXus in:

  • Apple since GeneXus Evolution 2 Upgrade 1
  • Android since GeneXus Evolution 2 Upgrade 3

Notes

  • Since iOS 8, the local notifications require an authorization from the user. The user will be automatically asked for this authorization the first time you use this API. In case that the developer wants to do it manually, it can be done by using Permissions external object for Apple aplications (e.g. when the app is in the background). 
  • If the DateTime field of the LocalNotification SDT is empty, the notification will be triggered instantly.

Scope

Generators:  Apple Android

See Also

LocalNotifications external object