Table of contents



Official Content

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.

Notification Provider - GeneXus Module

Domains

NotificationBadgeType (2)

Possible behaviors of Appearance.Badge field of Notification SDT.

        Value Description
  None Leaves the badge count unaffected on the application icon.
  SetTo Sets the badge count on the application icon to the number specified on "Badge" field.
  Increase  Adds the "Badge" field number to the badge count on the application icon (a negative number will decrease it). 

FilterRelationType

Possibles relational operators between keys and values.

        Value Description
  Exists It is true when there exists a key defined.
  NotExists   It is true when a defined key does not exist.
  Equal It is true when the key and value are equals.
  NotEqual It is true when the key and value are not equals.
  Greater It is true when the key is greater than value.
  Less It is true when the key is less than value.


FilterOperation

Possible binary logical operations.

        Value Description
  OR At least one condition must be satisfied.
  AND Both conditions must be satisfied.


TargetType

Target alternatives for sending notifications

        Value         Description
  Everybody    Sends a notification to the default "All" segment of OneSignal. This means that every registered device will receive the notification.
  Devices Sends a notification individually to each device using the OneSignal-specific API called "CreateNotification". 
  Groups Sends a notification to the devices that have the specified TAG. This means that only registered devices that belong to a certain group receive the notification. The notification is filtered by OneSignal Tags, and the "CreateNotification Based on Filters" API is used.
  Targets Sends a notification to devices that have the given TAG and meet certain filters. It is also resolved using OneSignal Tags, but in this case, filters can be applied to send the notification only to certain devices of a given TAG.

 

Note: Keep in mind that the OneSignal API does not allow sending notifications to Segments created via the OneSignal Console and that the OneSignal Free Plan has a limit of 2 TAGS .


PushNotificationPriority

The priority of the notification.

        Value Description
  Normal   Do not wake up the device if it is in doze mode.
  High Wake up the device if it is in doze mode.

 

Structured data types

Configuration

Field Domain Description
ApplicationId Character(100) [OPTIONAL] Smart device main object name
Properties (1) <collection>  
  Item ConfigurationProperty Set a contextual property of  Notifications Provider property dinamically.
Debug    
  Debug Boolean Enables a debug mode for inspecting messages through a proxy server.
Default: False
  Proxy Substructure  
    Host Character(20) Server name or IP for the proxy.
    Port Numeric(6.0) Server port number.
Advanced Substructure  
  BackCompatibility  Boolean Enables compatibility mode for Android/iOS older versions.
Default: False

ConfigurationProperty(1)

Field Domain Description
PropertyName  Character(100)  The property name. 
For example,
OneSignal - App ID property must be "APP_ID"
OneSignal - REST API Key property must be "REST_API_KEY"
PropertyValue <collection> The property value associated with that property name.

Delivery

Field Domain Description
Priority PushNotificationPriority  (Android-only)
Indicates the priority of the notification. 
Default: High
Expiration Numeric(18.0) Time in seconds that the notification provider tries to send the message.
Default: 0 (no expiration)

Event

Field Domain Description
Name Character(100) Name of the event defined in the smart device main object which receives the notification.
Parameter <Collection> [OPTIONAL] Set of parameter sent with the notification.
  Name  Character(100)  Name of a variable in the smart device main object that will be used as a parameter of the notification.
  Value Character(100) Value for the parameter sent to the event on the client-side.

LocalizedText

Field Domain Description
DefaultText Character(100) Text used when there is any localized item.
Text <Collection> [OPTIONAL] Set of text by languages (localized).
  Language  Character(100)  Language name for which the text is written. (Supported Languages Names: Spanish, English, Portuguese, Chinese, Japanese, Arabic)
  Text     Character(100) Text written in the language defined above.

Notification

Field Domain Description
Id Character(20) [OPTIONAL] Assigns an identification to the sent notification and allows to rewrite it if it necessary by sending it again with the same Id.
Title LocalizedText The title content of the notification.
Text LocalizedText The text content (below the title) of the notification.
Appearance Substructure [OPTIONAL] UI customization.
  Badge Character(4)  (iOS-only)
A numeric character to set a badge in the application icon
  BadgeType (2) NotificationBadgeType  Behavior of "Badge" field. It can be "None", "Set to" or "Increase" (in this case, negative values will decreaste badge number).
  Icon    
    Large Url (Android-only)
Url for an image resource that will be used. 
    Small Character(100)  (Android-only)
Name of an Image object embedded in the KB used for a small icon in the notification.
Some restrictions apply, see Notification Icon section on Images in Panels
The Android Asset Studio tool by romannuric may be useful.
  Sound Substructure  
    Sound  Boolean Enables the sound when the notification arrives at the end-user.
Default: True
    CustomSound  Character(100) Name of a project embedded custom sound.
This option is for advanced users, if it's empty, the app will use the default platform sound.
  Channel Character(100) The Android Oreo Notification Category to send the notification under.  
  Picture Character(100) (Android-only)
Picture to display in the expanded view. Can be a drawable resource name or a URL.
Actions Substructure  
  DefaultAction Substructure Default action that will be executed on Notification Tapping.
    Event Event Settings for the default action that will be executed when the end user taps on the notification.
  CustomUIActions <Collection> Typically when a user receives a notification, there is only a single action available - tapping on the notification. CustomUIActions allow more than one action to be taken on a notification, allowing for greater interactivity within notifications. See example here
    Event Event Configuration for the secondary action.
    Id Character(20) An Id for the custom secondary action.
    Text LocalizedText Text shown with the option.
    Icon Character(100) Name of an Image object in the KB.
Advanced Substructure  
  Attachment <Collection> (iOS-only) [OPTIONAL] Set of rich content (like media, e.g. videos in mp4 format). Must be a public URL resource. 
    Type Character(100) Any identifier for the resource (e.g. myvideo.mp4).
    URL Url The link to the media resource.
  Group Substructure (Android-only) [OPTIONAL]. For stacking Push Notification.
    GroupId Character(100) An identifier for stacking notifications in the same box.
    GroupMessage  LocalizedText Text to be shown when more than one message in the same group arrives to the smart device.
  Template Character(100) Use a template you setup on One Signal dashboard. You can override the template values by sending other parameters with the request.
This option is useful to personalize many aspects of the notification message, like the icon, sound, color, priority, category, etc. directly from the dashboard.
The template is the UUID found in the URL when viewing a template on One Signal dashboard. Example: be4a8044-bbd6-11e4-a581-000c2940e62c

Target

Field Domain Description
TargetType TargetType Indicates which are the target devices determining which of the following collections will be used.
Device <Collection> [OPTIONAL] Applies when TargetType is Devices
  DeviceToken  Character(500)  The DeviceToken of the target device in the set.
Group <Collection> [OPTIONAL] Applies when TargetType is Groups and the collection is understood as a disjunction of groups (joined with ORs)
  Name Character(100) Name of the group previously added with AddDeviceGroup procedure.
Filter <Collection>  
  Name Character(100) Name of a filter key previously added with AddDeviceTargetFilter procedure.
  Value Character(100) Value associated with the filter key.
  Relation FilterRelationType  Relation that associates the Name or Name and Value fields.
Default: Exists.
  Operator FilterOperation Relation of the current item condition with the next one (the last item ignores this field).
Default: AND

 

Procedures

AddDeviceGroups

Associates a set of groups or categories that a device belongs.

     Parameters   Configuration:SDT(Configuration), DeviceToken:Character(500), Groups:Collection(Character(20))
  Returns Messages:SDT(Messages), Success:Boolean


RemoveDeviceGroups

Disassociates a set of groups or categories from a device.

     Parameters   Configuration:SDT(Configuration), DeviceToken:Character(500), Groups:Collection(Character(20))
  Returns Messages:SDT(Messages), Success:Boolean


AddDeviceTargetFilter

Associates a filter name/value to a device.

     Parameters   Configuration:SDT(Configuration), DeviceToken:Character(500), FilterName:Character(20), FilterValue:Character(20)
  Returns Messages:SDT(Messages), Success:Boolean


RemoveDeviceTagetFilter

Disassociates a filter name/value of a device.

     Parameters   Configuration:SDT(Configuration), DeviceToken:Character(500), FilterName:Character(20), FilterValue:Character(20)
  Returns Messages:SDT(Messages), Success:Boolean


SendEvent

Executes an event on a specific device with delivery preferences.

     Parameters   Configuration:SDT(Configuration), DeviceToken:Character(500), NotificationEvent:Event, Delivery:Delivery
  Returns Messages:SDT(Messages), Success:Boolean


SendEventTargets

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

     Parameters   Configuration:SDT(Configuration), Target:Target, Event:Event, Delivery:Delivery
  Returns Messages:SDT(Messages), Success:Boolean


SendNotification

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

     Parameters   Configuration:SDT(Configuration), DeviceToken:Character(500), NotificationMessage:Notification, Delivery:Delivery
  Returns Messages:SDT(Messages), Success:Boolean


SendNotificationTargets

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

     Parameters   Configuration:SDT(Configuration), Target:Target, NotificationMessage:Notification, Delivery:Delivery
  Returns Messages:SDT(Messages), Success:Boolean


SetDeviceTargetMultipleFilters (3)

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

     Parameters Configuration:SDT(Configuration), DeviceToken:Character(500), FilterTags:Properties
  Returns Messages:SDT(Messages), Success:Boolean

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
Note: The 'status' flag on msg function allows the developer to write messages and then inspect them in the application log when Default Log Level property has Debug value.

Warning: The event defined in the main app (e.g. 'NotificationAction') cannot contain any command, function or control that includes UI (such as msg, confirm, etc). Remember that this kind of notifications can arrive with the device locked, with the app running in background mode, or even when the app not running. However, the developer can trigger UI actions if the app is running in foreground mode, but first, the developer must check such state by using the Interop.ApplicationState property.

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
Notification Provider API - Android result Notification Provider API - iOS result

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: .NETJava

Availability

This API is available as of GeneXus 15 Upgrade 3

(1) Available as of GeneXus 15 Upgrade 9
(2) Available as of GeneXus 15 Upgrade 11
(3) Available as of GeneXus 16 upgrade 10

Last update: February 2024 | © GeneXus. All rights reserved. GeneXus Powered by Globant