Deutsche Version

---

Version	Modification
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 KeepAlive 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.
2.4 (2021-04-16)	The Colorized property had the wrong data type in the designer. When using the KeepAlive extension, the UrsNotification.OnClick event was not triggered for the intent type Event. 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. GetActiveNotifications added.
2.8 (2021-06-13)	Property FlagNewTask at LauncherIntent was ignored but is needed since Android 10. Default for property FlagNewTask is true.
2.9.1 (2022-10-13)	Adapted for SDK31 (Android 12): All PendingIntents get the FLAG_IMMUTABLE flag. android.permission.SCHEDULE_EXACT_ALARM angefordert. Global exception is caught and written to the log.
2.10 (2023-11-23)	Adapted for SDK33 (Android 13): The POST_NOTIFICATIONS permission is required to output notifications Method AreNotificationsEnabled added Method OpenNotificationSettings added Method AreNotificationsPaused added

---

---

 

Download

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.

About Notifications

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.

About notification channels

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.

About Intents

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.

About alarms

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 the alarm.

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.

Usage

The App Inventor Extension UrsAi2Notification enables the creation of Android notifications. The extension contains three components:

• UrsAI2NotificationChannel (Reference) is a wrapper for the NotificationChannel. With this component, the properties of a notification channel can be set and Notifications can be created. They can be displayed immediately, delayed or at a specific time.
  
  
• UrsNotification (Reference) is used to define the properties of a notification. For example, the UrsAI2NotificationChannel.CreateNotification method uses an instance of this component to create a notification.
  
  
• UrsIntent (Reference)specifies which action should be executed when the notification is tapped. An instance of this component can be comitted to the UrsAI2NotificationChannel.CreateNotification method. The Intent defined by the component is executed when the notification is tapped.

UrsAI2NotificationChannel component

Android versions older than API Level 26 do not have notification channels. Notifications are created without channels. Functions that relate to channels have no effect.

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.

UrsAI2NotificationChannel (Reference) provides the following functions for simply generating notifications:

• CreateSimpleNotification creates a simple notification without any further function. The notification is canceled when tapped.
• CreateActionNotification creates a simple notification associated with an Intent. The underlying intent is executed when the notification is tapped.
• CreateAiNotification creates a simple notification specially designed for calling AI2 apps via a notification.

The download contains the sample project SimpleNotificationTest that shows the application of these three functions.

• CreateNotification creates a complex notification. The properties of the notification are specified by the passed UrsNotification object. An UrsIntent object, which is also passed, is used to specify which action should be triggered when the notification is tapped. Alternatively, the same notification can becreated by UrsNotification.Create.

The download contains the sample project ExtendedNotificationTest that shows the application of this function.

• CreateProgressNotification creates a notification that shows the progress of a running process (e.g. a download). The update of the progress could be done using the functions of the UrsNotification component: SetProgress, SetProgressEx, RemoveProgressBar, RemoveProgressBarEx.

The download contains the sample project ProgressBarTest that shows the application of this function.

• CreateAlarm and CreateAlarmEx are suitable for creating a "reminder function". It works like CreateNotification, but the notification is generated with a delay. It is generated by the Android Alarmmanager even if the app is already closed.
• CreateAlarmAt generates the notification at a specific point in time.

The download contains the sample project Notification Alarm Test that shows the use of this function. A second example is Remember URS.

You have to be able to cancel notifications:

• Cancel cancels a specific notification that has already been displayed. The notification can be canceled by UrsNorification.Cancel.
• CancelAll clears all notifications that have already been displayed.
• CancelAlarm cancels the pending intent for a delayed or dated notification that has not yet been displayed

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

• GetActiveNotifications returns a list with the IDs of the active notifications.
• OpenHomeScreen puts the app to the background and opens the home screen. It simulates pressing the home button.
• OpenNotificationPanel opens the window that displays the notifications (Notification Panel) ¹⁾.
• CloseSystemDialogs closes the Notification Panel.
• SortSimpleList sorts a list with texts, e.g. a list with alarm times.
• AppIsAlreadyRunning checks whether another instance of the app is already active. Depending on the situation, tapping a notification opens a second instance of the app. This function checks this. It does not work in the Companion.
• MoveOtherAppToFront brings another already running instance of the app to the foreground. This function does not work in the Companion.
• AreNotificationsEnabled and AreNotificationsPaused provide information on the status of the notification system.
• OpenNotificationSettings opens the dialog window for setting the notification options.

¹⁾ 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.

UrsNotification component

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

AddActionButton and RemoveActionButtons are used to add and remove action buttons. Up to three action buttons are supported.

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 called¹⁾. 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.

¹⁾ 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.

AreNotificationsEnabled and AreNotificationsPaused provide information on the status of the notification system.

UrsIntent component

An UrsIntent (Reference) object that is passed to the Create... functions is used to specify which action is to be triggered when the notification is tapped.

This component is a collection of properties. It has neither functions nor events.

The ActionType specifies which action is triggered with the Intent:

• None: Nothing happens when the notification or the action button is tapped.
• Screen: When the notification is tapped, the designated screen of the app opens.
• Launcher: Tapping the notification will open any app. See also the ActivityStarter documentation at App Inventor.
• Event: The event UrsNotification.OnClick is triggered.
• GoBack: The notification panel closes and the system returns to the last app you ran.

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.

---

Error codes

Code	Error text	Meaning	Trigger
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.	UrsAI2NotificationChannel.CreateAiNotification
17005	Invalid value at UrsNotificationObject.	Wrong type at parameter UrsNotificationObject.	UrsAI2NotificationChannel: CreateNotification, CreateAlarm, CreateAlarmEx, CreateAlarmAt, CreateProgressNotification UrsNotification.SetOnDestroyAction
17006	Invalid value at UrsIntentObject	Wrong type at parameter UrsIntentObject.	UrsAI2NotificationChannel: CreateActionNotification, CreateNotification, CreateAlarm, CreateAlarmEx, UrsAI2NotificationChannel.CreateAlarmAt, CreateProgressNotification UrsNotification: AddActionButton, Create, SetOnDestroyAction
17007	Invalid Delay value	Delayis less than 1.	UrsAI2NotificationChannel: CreateAlarm, CreateAlarmEx
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

---

Examples:

	Simple Notification Test This example shows how the UrsNotificationChannel.Create... methods work
	Extended Notification Test The extended options such as symbols, images and action buttons are shown.
	Progress Bar Test The topic is display of progress notifications.
	Notification Alarm Test Notifications are delayed or triggered at specific times.
	Remember URS A handy application that reminds the user to start the app regularly.