Notification Provider API

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

Domains

NotificationBadgeType ⁽²⁾

Possible behaviors of Appearance.Badge field of Notification SDT.

FilterRelationType

Possibles 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 that a device belongs.

RemoveDeviceGroups

Disassociates a set of groups or categories from a device.

AddDeviceTargetFilter

Associates a filter name/value to a device.

RemoveDeviceTagetFilter

Disassociates a filter name/value of 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) to a device.

This method is only valid for the OneSignal Notifications Provider. 

Sample

Consider that the smart device application's main object is called "MySDApp" and it has the following event defined:

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

Then, from the web-backend, we 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 = !"MySDApp"
   
GeneXus.Common.Notifications.SendNotification(
     &TheNotificationConfiguration,
     DeviceToken, // Target device token
     &TheNotification, 
     &TheNotificationDelivery, 
     &OutMessages,
     &IsSuccessful
)

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

Android	iOS

and if the end user taps on it, the msg command will be print in the console a message saying "Hello dear user!".

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 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. Such 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 (e.g. OneSignal), the device is still associated with the identifier provided by the provider. In such 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's recommended to set the property Device Refistration Mode 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 valid a 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 One signal, 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