Notification Provider API

This API is part of the GeneXus built-in modules and provides a set of facilities for a GeneXus developer to send push notifications through an external notification provider. It allows registered device management and sending mechanisms for a single device or a group of devices.

Domains

NotificationBadgeType ⁽²⁾

Possible behaviors of the Appearance.Badge field of the Notification Structured Data Type (SDT) object.

FilterRelationType

Possible relational operators between keys and values.

FilterOperation

Possible binary logical operations.

TargetType

Target alternatives for sending notifications.

PushNotificationPriority

The priority of the notification.

Structured data types

Configuration

ConfigurationProperty⁽¹⁾

Delivery

Event

LocalizedText

Notification

Target

Procedures

AddDeviceGroups

Associates a set of groups or categories to which a device belongs.

RemoveDeviceGroups

Disassociates a set of groups or categories from a device.

AddDeviceTargetFilter

Associates a filter name/value with a device.

RemoveDeviceTargetFilter

Disassociates a filter name/value from a device.

SendEvent

Executes an event on a specific device with delivery preferences.

SendEventTargets

Executes an event on a set of target devices with delivery preferences.

SendNotification

Sends a push notification to a specific device with delivery preferences.

SendNotificationTargets

Sends a push notification to a set of target devices with delivery preferences.

SetDeviceTargetMultipleFilters ⁽³⁾

Associates a list of filters (name/value collection) with a device.

This method is only valid for the OneSignal Notifications Provider. 

Sample

Consider that the Native Mobile application's main object is called "MyApp" and that it has the following event defined:

Event 'NotificationAction'
     msg(&msg,status) 
EndEvent

Consideration: If you are generating for iOS and your main object is a Menu object, the event must be associated with an Action located under the Notifications node (not under the Actions node). To do so, you must first explicitly add the Notifications node by right-clicking on the node that displays the Menu name and selecting Add > Notifications. Then, right-click on the Notifications node and select Add > Action to create the action that will be associated with the event.

Finally, from the web backend, you can write a source code as follows:

Variables:

&TheNotification : Notification, GeneXus.Common.Notifications
&TheNotificationDelivery: Delivery, GeneXus.Common.Notifications
&TheNotificationConfiguration : Configuration, GeneXus.Common.Notifications

Source:

&TheNotification.Title.DefaultText = "GeneXus"
&TheNotification.Text.DefaultText  = "Notification Provider API"
&TheNotification.Actions.DefaultAction.Event.Name = "NotificationAction" // Declared in the SD Main object
&TheNotification.Actions.DefaultAction.Event.Parameters.FromJson('[{"Name":"msg","Value":"Hello dear user!"}]')
&TheNotification.Appearance.Icon.Small = !"GX15IconKB"

&TheNotificationDelivery.Expiration = 3000 
&TheNotificationDelivery.Priority   = PushNotificationPriority.Normal

&TheNotificationConfiguration.ApplicationId = !"MyApp"
   
GeneXus.Common.Notifications.SendNotification(
     &TheNotificationConfiguration,
     DeviceToken, // Target device token
     &TheNotification, 
     &TheNotificationDelivery, 
     &OutMessages,
     &IsSuccessful
)

Then, when the above code is executed, the device will receive a notification like this:

Android	iOS

If the end user taps it, the msg command will print the message "Hello dear user!" in the console.

Notifications to devices with certain tags

If you want to send the previous notification to devices that have certain tags already defined, you can use the SendNotificationTargets procedure with the Target parameter. 

Suppose you have added the tag 'User Type' with the value 'Student' throughout the AddDeviceTargetFilter procedure, for those devices that correspond to student users.

Now, to send a notification to those devices, use this code:

&TargetFilter = new()
&TargetFilter.Name = !'User Type'
&TargetFilter.Value = !'Student'
&Target.TargetType = TargetType.Targets
&Target.Targets.Add(&TargetFilter)
SendNotificationTargets(&NotificationConfiguration, &Target, &Notification, &NotificationDelivery, &Messages, &Success)

Notes

• The iOS platform always uses the image set in Apple Application Icon property as the notification icon, unlike Android that uses those set in the Android Notification Icon property and can use a different image for the notification message by the Appearance.Icon field on the Notification SDT.
• In iOS, if the developer wants to download content when the app is in background mode (e.g. a video attached to the notification), it is necessary to include the 'remote-notification' value to the Background Modes property.
• As of GeneXus 15 Upgrade 10, when the developer uses any of the Send methods with OneSignal provider, the Messages parameter will return one item with the response payload in a JSON string in its "description" field. This JSON includes the notification Id and the quantity recipients.
  For example,
  {"id":"5263x49t-ss31-436r-942k-638h111d9g2a","recipients":1}

Troubleshooting

• If the developer removes a device from the provider's console (for example, OneSignal), the device remains associated with the identifier provided by the provider. In this case, uninstall the application from the device and reinstall it in order to generate a new identifier in the provider platform.
• GeneXus 15 Upgrade 4 fixes an issue when using more than two filter targets in the Target SDT.
  For more information, refer to SAC#41070.
• Since Android 13 (API 33) it is recommended to set the Device Registration Mode property to Manual and use the exo Permissions to request the notifications permission. Ref.: SAC #52694.

Push Provider was not specified. Please set a Push Provider

When sending a notification, the following error occurs:

Unknown error processing: Push Provider was not specified. Please set a Push Provider

Make sure the webapp folder includes the CloudServices.config file (specifically \WEB-INF\CloudServices.config) with a valid notification configuration. If you are running the process in batch mode, the input file should be located in the current working directory. For Java, the input file should be located where "System.getProperty("user.dir")" points to, as this property can be set to specify the directory where the input file is located.

FAQ

• When I build my project that uses OneSignal, GeneXus gives me the following error:

  ld: framework not found Pods_OneSignalNotificationServiceExtension
  clang: error: linker command failed with exit code 1 (use -v to see invocation)
  

  Cause: As of GeneXus 15 Upgrade 6, the generated iOS project is based on extension libraries.
  Solution: Open the *.xcworkspace file (instead of *.xcodeproj) on the Mac computer.

Scope

Objects: Procedure object, Web Panel object, Work With for Web pattern
Generators: .NET, Java

Availability

This API is available as of GeneXus 15 Upgrade 3.

⁽¹⁾ Available as of GeneXus 15 Upgrade 9.
⁽²⁾ Available as of GeneXus 15 Upgrade 11.
⁽³⁾ Available as of GeneXus 16 upgrade 10.