|1.0 (2020-09-07)||Initial version|
|2.0 (2021-03-08)||Completely revised and extended version|
|2.1 (2021-03-16)||Some methods declared public so that
can call them. This has no effect on the functionality.
|2.2 (2021-03-20)||The intent ID was not correctly passed to the OnClick event.|
|2.3 (2021-04-05)||The display of the notification property NumberID did
not match the internal default.
Note: The examples are not affected and still contain version 2.2 of the extension.
Note: The examples are not affected and still contain version 2.2 of the extension.
|2.5 (2021-04-17)||Under certain conditions, the UrsNotification.Onclick event was triggered only once.|
|2.6 (2021-05-12)||Starting an AI2 app (intent type Screen) did not work with Kodular if the package name was changed.|
|2.7 (2021-05-15)||Starting an AI2 app (intent type Screen) did not work
with Kodular if the package name was changed.
The UrsAI2Notifier ZIP archive for download. The archive contains the source code, the compiled binary for uploading to the App Inventor and some sample applications.
An overview of the notifications can be found in the Android documentation: Notifications Overview.
Notifications are displayed in a separate window (notification panel), separate of the app. They can be created and deleted. There are no special functions to modify them. Notifications have a unique ID (NumberID). If a second notification is created with the same ID before the previous one has been deleted, the existing one will be updated.
Android does not have a method for getting active notifications. If necessary, the program itself
must keep track of which notifications it has created.
Notifications that can be generated with this extension have the following structure (it is not necessary to display all elements):
All text elements can be formatted with HTML tags. Which HTML tags can be used varies depending on the implementation of the Android system. There are hints at Mark Murphy's Technical Stuff or Daniel Lew's Coding Thoughts.
With API level 26 (version Oreo 8.0), Android introduced the concept of notification channels (NotificationChannel, also known as notification categories on some devices). All notifications must be assigned a channel.
The notification concept is quite complex. Android allows settings to be made on the device level as well as on the channel level and with the notifications themselves.
Many properties of the notifications, e.g. the importance or the vibration pattern, are set at the channel level. These properties are defined by the app when the channel is created and cannot be changed afterwards. The user has full access to most of the channel attributes and can modify them at will. The modifications made by the user should not be overwritten. Therefore, settings cannot be changed later by the program after creating them. Even if a channel is deleted and then created again, it is created with the last available settings. "Erasing" is practically just hiding. Only the properties Name and Description of a channel can be changed later. Eliminating spelling mistakes would otherwise be impossible.
If you want to change properties, a new channel (new channel ID) must be used. The existing channel could be hidden with UrsAI2NotificationChannel.HideChannel when launching the app.
So you should think carefully about which properties are assigned to a channel.
Android uses Intent objects to send orders to the system. An Intent contains all information that is necessary to execute the designated action. The AI2 ActivityStarter, for example, uses Intents internally to start other apps.
Alarms are actions that are triggered at a specific time (alarm time). They are linked to an
Intent that specifies the action to be executed at the time of
An alarm can be created and deleted. There are no special functions to modify it. An alarm has a unique ID (RequestCode). If a second alarm is created with the same ID before the previous one was triggered, the existing one will be updated.
Android does not have a method for getting active alarms. If necessary, the program itself must keep track of which alarms it has created.
The App Inventor Extension UrsAi2Notification enables the creation of Android notifications. The extension contains three components:
The (Android) NotificationChannel is automatically created immediately after starting the app. You don't have to worry about it yourself. The properties of the notification channel can be set in the designer window of the App Inventor. Since the properties of the channel cannot be changed after it has been created, there are no methods for modification at runtime.
Particular attention must be paid to the setting of the Importance level. It depends on this which general (channel-independent) settings the notifications get. As already mentioned in the note above, these are determined by that channel that was created first. The site Set the Importance Level at the Android documentation gives the details.
The download contains the sample project SimpleNotificationTest that shows the application of these three functions.
The download contains the sample project
shows the application of this function.
The download contains the sample project ProgressBarTest that shows the application of this function.
You have to be able to cancel notifications:
The HideChannel method hides a notification channel.
It is unusual to change the name (ChannelName) and the description (Description) of a channel by program or by the user. Usually this is only done by updating the app. If the update contains new values for these properties, these channel properties are automatically updated when the program is started.
Notification channel groups and individual notification sounds are not implemented (see above).
Other helpful functions are
1) The function requires the EXPAND_STATUS_BAR permission. This permission is not requested in the standard AI2 companion and does not work there. Chapter AI2 FAQ: Patching the AI2 Companion - Additional Permissions explains how to patch the AI2 Companion and how to obtain the necessary permission.
The UrsNotifiaction (Reference) component is used to summarize the various properties of a Notification. The Notifiction.Builder is used internally to create the notification. Notifications can be modified. If a second notification is created with the same ID (NumberID field) before the previous one has been deleted, this will be updated.
The functions Create and Cancel are identical to those of the notification channel. You generate a notification with the settings of the component or delete the notification with the ID (NumberID) defined in the component
The SetProgress, SetProgressEx, RemoveProgressBar and RemoveProgressBarEx functions modify a progress notification created with the UrsAI2NotificationChannel.CreateProgressNotification function
Instead starting of another Activity, the event OnClick can be triggered at the Screen to which the UrsNotification object belongs. To do this, an UrsIntent must be specified with the ActionType Event.
The OnClick event will not be triggered if the associated Screen has been closed. Apps that use this function must ensure that the notification is either closed (CancelOnDestroy property) or modified appropriately. Unfortunately, the App Inventor does not allow the Activity.onDestroy event to be passed to the app. This means that there is no way of changing the notification accordingly. Therefore, a suitable notification which is displayed when the app is closed is registered via the SetOnDestroyAction function. It should be noted that the internally necessary objects are created when this function is called1). If changes are to be made to the passed UrsNotificationObject or UrsIntentObject, the SetOnDestroyAction function must be called again. Otherwise the change would have no effect.
1) If the app is closed from the app overview (history), only a limited time and a limited range of functions are available (test with version Android Oreo, 8.1). This is not suitable to create the objects at the time of closing.
RemoveOnDestroyAction removes the task of displaying a new notification when the Screen is closed.
This component is a collection of properties. It has neither functions nor events.
The intents for the OnClick event can be differentiated using the ID property. If you want to use the OnClick event for a notification with action buttons, a different UrsIntent instance, which at least differs in ID, must be applied to the actual notification and to each action button. The ID of the associated UrsIntent instance is published by the OnClick event.
|17001||Invalid value at UrsChannelObject.||Wrong type at parameter UrsChannelObject.||UrsNotification.Create, UrsNotification.SetOnDestroyAction|
|17002||Invalid Vibration Pattern||Invalid vibration pattern.||UrsAI2NotificationChannel (beim Start der App)|
|17003||Invalid sound file name||The specified audio file does not exist.||UrsAI2NotificationChannel (beim Start der App)|
|17004||Screen not found: <screen name>||The specified
Screen does not exist.
|17005||Invalid value at UrsNotificationObject.||Wrong type at parameter UrsNotificationObject.||UrsAI2NotificationChannel:
CreateNotification, CreateAlarm, CreateAlarmEx, CreateAlarmAt, CreateProgressNotification
|17006||Invalid value at UrsIntentObject||Wrong type at parameter UrsIntentObject.|| UrsAI2NotificationChannel:
CreateActionNotification, CreateNotification, CreateAlarm, CreateAlarmEx, UrsAI2NotificationChannel.CreateAlarmAt, CreateProgressNotification
AddActionButton, Create, SetOnDestroyAction
|17007||Invalid Delay value||Delayis less than 1.||UrsAI2NotificationChannel:
|17008||Invalid Millis value||The specification is smaller than the current time.||UrsAI2NotificationChannel.CreateAlarmAt|
|17009||Notification not created yet||The notification has not been created yet.||UrsNotification:
SetProgress, SetProgressEx, RemoveProgressBar, RemoveProgressBarEx
|17010||Must specify Title||The specification for the Title parameter is missing.||UrsNotification.AddActionButton|
This example shows how the UrsNotificationChannel.Create... methods work
The extended options such as symbols, images and action buttons are shown.
The topic is display of progress notifications.
Notifications are delayed or triggered at specific times.
A handy application that reminds the user to start the app regularly.