Notification Provider API

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 them.

Notification Provider - GeneXus Module

Domains

FilterRelationType

Possibles relational operators between keys and values.

        Value Description
  Exists It is true when exists a key defined.
  NotExists   It is true when not exists any key defined.
  Equal It is true when key and value are equals.
  NotEqual It is true when key and value are not equals.
  Greater It is true when key is greater than value.
  Less It is true when 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   Every registered device receives the notification.
  Devices A subset of registered devices receives the notification.
  Groups Those registered devices which belong to any declared group receives the notification.
  Targets Those registered devices which satisfied a target condition receives the notification.


PushNotificationPriority

Possible binary logical operations.

        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)
  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
  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 for Smart Devices applications
The Android Asset Studio tool by romannuric may be useful.
  Sound Substructure  
    Sound  Boolean Enables the sound when the notification arrives to 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.
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. See example here.
    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.

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

 

Example

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!".

 

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

 

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
Platforms  Web(.NET, Java)

 

Availability

This API is available as of GeneXus 15 Upgrade 3

(1) Available as of GeneXus 15 Upgrade 9


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