English version

---

Version	Anpassungen
1.0 (2020-09-07)	Initiale Version
2.0 (2021-03-08)	Komplett überarbeitete und ergänzte Version
2.1 (2021-03-16)	Einige Methoden als public deklariert, damit sie von KeepAlive aufgerufen werden können. Dies hat keine Auswirkungen auf die Funktionsweise.
2.2 (2021-03-20)	Die ID des Intents wurde nicht korrekt an das OnClick-Ereignis weiter geleitet.
2.3 (2021-04-05)	Die Anzeige der Notification-Eigenschaft NumberID stimmte nicht mit der internen Vorbelegung überein. Hinweis: Die Beispiele sind nicht betroffen und enthalten noch die Version 2.2 der Extension.
2.4 (2021-04-16)	Eigenschaft Colorized hatte im Designer den falschen Datentyp. Bei Benutzung von KeepAlive wurden bei der Intent-Art Event das Ereignis UrsNotification.OnClick nicht ausgelöst. Hinweis: Die Beispiele sind nicht betroffen und enthalten noch die Version 2.2 der Extension.
2.5 (2021-04-17)	Unter bestimmten Bedingungen wurde das Ereignis UrsNotification.Onclick nur einmal ausgelöst.
2.6 (2021-05-12)	Das Starten einer AI2-App (Intent-Typ Screen) hat bei Kodular nicht funktioniert, wenn der Package Name geändert wurde.
2.7 (2021-05-15)	Das Starten einer AI2-App (Intent-Typ Screen) hat bei Kodular nicht funktioniert, wenn der Package Name geändert wurde. GetActiveNotifications hinzugefügt
2.8 (2021-06-13)	Eigenschaft FlagNewTask wurde beim Intent nicht korrekt ausgewertet, wird für Android 10 aber benötigt. Voreinstellung für Eigenschaft FlagNewTask ist nun true.
2.9.1 (2022-10-13)	Angepasst für SDK31 (Android 12): Alle PendingIntent erhalten das Flag FLAG_IMMUTABLE. android.permission.SCHEDULE_EXACT_ALARM requested. Globale Exception wird gefangen und ins Log ausgegeben.
2.10 (2023-11-23)	Angepasst für SDK33 (Android 13): Um Notifications auszugeben, ist die Permission POST_NOTIFICATIONS notwendig Methode AreNotificationsEnabled hinzugefügt Methode OpenNotificationSettings hinzugefügt Methode AreNotificationsPaused hinzugefügt

---

---

 

Download

Das ZIP-Archiv UrsAI2Notifier zum Download. Das Archiv enthält den Quellcode, das kompilierte Binary zum Upload in den App Inventor und einine Beispiel-Anwendungen.

Über Benachrichtigungen

Eine Übersicht zu den Benachrichtigungen findet man in der Android Dokumentation: Übersicht zu Benachrichtigungen.

Benachrichtigungen werden in einem separatem Fenster (Notification Panel), unabhängig von der App angezeigt. Sie können erzeugt und gelöscht werden. Es gibt keine besonderen Funktionen zu deren Abänderungen. Benachrichtigungen besitzen eine eindeutige ID (NumberID). Wird eine zweite Benachrichtigung mit der gleichen ID erstellt, bevor die vorhergehende gelöscht wurde, wird bestehende aktualisiert.

Android besitzt keine Methode, um aktive Benachrichtigungen zu ermitteln. Programme müssen bei Bedarf selbst nachhalten, welche Benachrichtigungen sie erzeugt haben.

Benachrichtigungen, die mit dieser Extension erzeugt werden können, haben den folgenden Aufbau (es müssen nicht immer alle Elemente angezeigt werden):

Sämtliche Text-Elemente können mit HTML-Tags formatiert werden. Welche HTML-Tags benutzt werden können, variiert je nach Implementierung des Android-Systems. Hinweise gibt es bei Mark Murphy's Technical Stuff oder Daniel Lew's Coding Thoughts.

Über Benachrichtigungskanäle

Mit dem API-Level 26 (Version Oreo 8.0) hat Android das Konzept der Benachrichtigungskanäle eingeführt (NotificationChannel, bei manchen Geräten auch Benachrichtigungskategorien genannt). Sämtliche Benachrichtigungen müssen ab API Level 26 einem solchen Kanal zugeordnet werden. Bis einschließlich API Level 25 sind alle den Benachrichtigungskanal betreffende Angaben und Funktionen wirkungslos.

Das Benachrichtigungskonzept ist relativ komplex. Android erlaubt es, Einstellungen sowohl auf der Geräteebene, als auch auf der Kanalebene und bei den Benachrichtigungen selbst vorzunehmen.

Viele Eigenschaften der Benachrichtigungen, z.B. die Wichtigkeit (Importance) oder das Vibrationsmuster, werden auf der Kanal-Ebene festgelegt. Diese Eigenschaften werden von der App bei der Anlage des Kanals festgelegt. Der Benutzer hat mit Hilfe die App Eigenschaften vollen Zugriff auf die meisten der Kanalattribute und kann sie nach belieben modifizieren. Die Modifikationen des Benutzers sollen nicht überschrieben werden. Deshalb können die Kanaleigenschaften nachträglich nicht mehr per Programm geändert werden.  Das geht sogar soweit, dass, wenn eine Kanal gelöscht und anschließend wieder angelegt wird, er mit den zuletzt vorhandenen Einstellungen erzeugt wird. Das "Löschen" ist praktisch nur ein "Verstecken". Lediglich die Eigenschaften Name und Description eines Kanals lassen sich nachträglich ändern. Die Beseitigung von Schreibfehler wäre ansonsten unmöglich.

Man sollte sich also sehr gut überlegen, welche Eigenschaften einem Kanal zugewiesen werden.

Will man andere Eigenschaften ändern, muss ein neuer Kanal (neue Channel-ID) verwendet werden. Den bestehenden Kanal versteckt man sinnvollerweise beim Start der App mit UrsAI2NotificationChannel.HideChannel.

Man sollte sich also sehr gut überlegen, welche Eigenschaften einem Kanal zugewiesen werden.

Über Vorhaben (Intent)

Android benutzt Intent-Objekte, um dem System Aufträge zu erteilen. Ein Intent enthält alle Angaben, die notwendig sind, den Auftrag auszuführen. Der AI2 ActivityStarter z.B. benutzt intern Intents um andere Apps zu starten.

Über Alarme

Alarme sind Aktionen, die zu einer bestimmten Zeit (Alarmzeitpunkt) ausgelöst werden. Sie sind mit einem Intent verknüpft, der angibt, welche Aktion zum Alarmzeitpunkt auszuführen ist.

Ein Alarm kann erzeugt und gelöscht werden. Es gibt keine besonderen Funktionen zu dessen Abänderungen. Ein Alarm besitzen eine eindeutige ID (RequestCode). Wird ein zweiter Alarm mit der gleichen ID erstellt, bevor der vorhergehende ausgelöst wurde, wird der bestehende aktualisiert.

Android besitzt keine Methode, um aktive Alarme zu ermitteln. Programme müssen bei Bedarf selbst nachhalten, welche Alarme sie erzeugt haben.

Verwendung

Die App Inventor Extension UrsAi2Notification ermöglicht es, Android Benachrichtigungen zu erstellen. Die Extension enthält drei verschiedene Komponenten:

• UrsAI2NotificationChannel  (Referenz) bildet einen Wrapper für den NotificationChannel. Mit dieser Komponente können die Eigenschaften eines Benachrichtigungskanals festgelegt und Benachrichtigungen (Notification) erstellt werden. Benachrichtigungen können sofort, verzögert oder zu einem bestimmten Zeitpunkt angezeigt werden.
  
  
• UrsNotification (Referenz) dient zur Festlegung der Eigenschaften einer Benachrichtigung. Z.B. verwendet die Methode UrsAI2NotificationChannel.CreateNotification eine Instanz dieser Komponente zur Anlage einer Benachrichtigung.
  
  
• UrsIntent (Referenz) legt fest, welche Aktion ausgeführt werden soll, wenn die Benachrichtigung angetippt wird. Eine Instanz der Komponente kann der Methode UrsAI2NotificationChannel.CreateNotification übergeben werden. Der durch die Komponente definierte Intent wird dann beim Antippen der Benachrichtigung ausgeführt.

UrsAI2NotificationChannel-Komponente

Android Versionen älter als API Level 26 kennen keine Benachrichtigungskanäle. Benachrichtigungen werden ohne Kanäle angelegt. Funktionen, die sich auf Kanäle beziehen sind wirkungslos.

Der (Android) NotificationChannel wird automatisch direkt nach dem Start der App angelegt. Man muss sich nicht selbst darum kümmern. Im Designer-Fenster können die Eigenschaften des Benachrichtigungskanals festgelegt werden. Da die Eigenschaften des Kanals nach dessen Erstellung nicht mehr geändert werden können, gibt es keine entsprechenden Methoden für die Modifikation zur Laufzeit.

Besondere Achtung ist der Einstellung des Importance-Levels zu schenken. Hiervon hängt es ab, welche generellen (kanal-unabhängigen) Einstellungen die Benachrichtigungen erhalten. Wie oben im Hinweis schon erwähnt, werden diese durch den als erstes angelegten Kanal festgelegt. Der Artikel Set the Importance Level in der Android-Dokumentation gibt die Details dazu.

UrsAI2NotificationChannel  (Referenz) stellt folgende Funktionen zur Erzeugung von einfachen Benachrichtigungen bereit:

• CreateSimpleNotification erstellt eine einfache Benachrichtigung ohne weitere Funktion. Die Benachrichtigung wird gelöscht, wenn sie angetippt wird.
• CreateActionNotification erstellt eine einfache Benachrichtigung die mit einem Intent verbunden ist. Der zu Grunde liegende Intent wird dann beim Antippen der Benachrichtigung ausgeführt.
• CreateAiNotification erstellt eine einfache Benachrichtigung, die speziell für das Aufrufen von AI2-Apps per Benachrichtigung geeignet ist.

Im Download ist das Beispielprojekt SimpleNotificationTest enthalten, dass die Anwendung dieser drei Funktionen zeigt.

• CreateNotification erstellt eine komplexe Benachrichtigung. Die Eigenschaften der Benachrichtigung wird über das übergebene UrsNotification-Objekt festgelegt. Über ein ebenfalls übergebenes UrsIntent-Objekt wird festgelegt, welche Action beim Antippen der Benachrichtigung ausgelöst werden soll. Alternativ kann die gleiche Benachrichtigung über UrsNotification.Create angelegt werden.

Im Download ist das Beispielprojekt ExtendedNotificationTest enthalten, dass die Anwendung dieser Funktion zeigt.

• CreateProgressNotification erstellt eine Benachrichtigung, die den Fertigstellungsgrad eines laufenden Prozesses (z.B. ein Download) anzeigt. Die Aktualisierung der Fortschrittsanzeige erfolgt durch die Funktionen der Komponente UrsNotification: SetProgress, SetProgressEx, RemoveProgressBar, RemoveProgressBarEx.

Im Download ist das Beispielprojekt ProgressBarTest enthalten, dass die Anwendung dieser Funktion zeigt.

• CreateAlarm und CreateAlarmEx sind dazu geeignet eine "Erinnerungsfunktion" zu gestalten. Sie funktioniert wie CreateNotification, die Benachrichtigung wird jedoch verzögert erzeugt. Sie wird vom Android Alarmmanager auch dann erzeugt, wenn die App bereits geschlossen ist.
• CreateAlarmAt erzeugt die Benachrichtigung zu einem bestimmten Zeitpunkt.

Im Download ist das Beispielprojekt Notification Alarm Test enthalten, dass die Anwendung dieser Funktion zeigt. Ein zweites Beispiel ist Remember URS.

Benachrichtigungen muss man auch wieder löschen können:

• Cancel löscht eine bestimmte, bereits angezeigte Benachrichtigung. Die Benachrichtigung kann auch per UrsNorification.Cancel gelöscht werden.
• CancelAll löscht alle bereits angezeigten Benachrichtigungen.
• CancelAlarm löscht den Auftrag für eine noch nicht angezeigte verzögerte oder mit Datum versehene Benachrichtigung.

Die Methode HideChannel versteckt einen bereits angelegten Benachrichtigungskanal.

Es ist unüblich den Namen (ChannelName) und die Beschreibung (Description) zu einem Kanal per Programm oder durch den Benutzer zu ändern. I.d.R. erfolgt dies nur durch ein Update der App. Enthält das Update neue Werte für diese Eigenschaften, werden diese Kanaleigenschaften automatisch beim Start des Programm angepasst.

Nicht implementiert sind Benachrichtigungskanalgruppen und individuelle Benachrichtigungstöne (s.o.).

Weitere Hilfreiche Funktionen sind

• GetActiveNotifications liefert eine Liste mit den IDs der aktiven Benachrichtigungen.
• OpenHomeScreen stellt die App in den Hintergrund und öffnet den Home Screen. Simuliert also das Drücke der Home-Taste.
• OpenNotificationPanel öffnet das Fenster, das die Benachrichtigungen anzeigt (Notification Panel) ¹⁾.
• CloseSystemDialogs schließt das Notification Panel.
• SortSimpleList sortiert eine Liste mit Texten, z.B. eine Liste mit Alarmzeitpunkten.
• AppIsAlreadyRunning prüft, ob bereits eine andere Instanz der App aktiv ist. Das Antippen einer Benachrichtigung öffnet je nach Situation eine zweite Instanz der App. Diese Funktion überprüft dies. Diese Funktion funktioniert nicht im Companion.
• MoveOtherAppToFront bringt eine andere bereits laufende Instanz der App in den Vordergrund. Diese Funktion funktioniert nicht im Companion.
• AreNotificationsEnabled und AreNotificationsPaused liefern Informationen zum Status des Notification-Systems.
• OpenNotificationSettings öffnet das Dialogfenster zur Einstellung der Benachrichtigungsoptionen.

¹⁾ Die Funktion benötigt die Permission EXPAND_STATUS_BAR. Diese Permission ist im Standard-AI2-Companion nicht angefordert und funktioniert dort nicht. In Kapitel AI2-FAQ: Patchen des AI2 Companion - zusätzliche Permissions wird erklärt, wie man den AI2-Companion patchen kann und um die notwendigen Permission zu erhalten.

UrsNotification-Komponente

Die Komponente UrsNotifiaction (Referenz) dient zur Zusammenfassung der verschiedenen Optionen einer Notification. Der Notifiction.Builder wird intern zur Erstellung der Benachrichtigung verwandt. Benachrichtigungen können abgeändert werden. Wird eine zweite Benachrichtigung mit der gleichen ID (Feld NumberID) erstellt, bevor die vorhergehende gelöscht wurde, wird diese aktualisiert.

Die Funktionen Create und Cancel sind i.W. identisch mit denen des Benachrichtigungskanals. Sie erzeugen eine Benachrichtigung mit den Einstellungen der Komponente bzw. löschen die Benachrichtigung mit der in der Komponente definierten ID (NumberID).

Die Funktionen SetProgress, SetProgressEx, RemoveProgressBar, RemoveProgressBarEx modifizieren eine mit der Funktion UrsAI2NotificationChannel.CreateProgressNotification erstellte Fortschrittsbenachrichtigung.

AddActionButton und RemoveActionButtons dienen zum Hinzufügen und Entfernen von Aktionsschaltflächen. Es können bis zu drei Aktionsschaltflächen angezeigt werden.

Anstatt eine andere Activity zu starten, kann man in dem Screen, zu dem das UrsNotification-Objekt gehört, das Ereignis OnClick auslösen. Dazu muss eine UrsIntent mit dem ActionType Event angegeben werden.

Das Auslösen des Ereignisses OnClick funktioniert nicht, wenn der zugehörige Screen geschlossen wurde. Apps, die diese Funktion nutzen, müssen sicher stellen, dass die Benachrichtigung entweder geschlossen (Eigenschaft CancelOnDestroy) oder passend abgeändert wird. Leider erlaubt es der App Inventor nicht, das Activity.onDestroy-Ereignis an die App weiter zu geben. Diese hat also keine Möglichkeit, die Benachrichtigung entsprechend abzuändern. Deshalb wird über die Funktion SetOnDestroyAction eine passende Benachrichtigung registriert, die angezeigt wird, wenn die App geschlossen wird. Zu beachten ist, dass die intern notwendig Objekte zum Zeitpunkt des Aufrufs dieser Funktion erstellt werden¹⁾. Wenn nachträglich Änderungen am übergebenen UrsNotificationObject oder UrsIntentObject vorgenommen werden sollen, muss die Funktion SetOnDestroyAction erneut aufgerufen werden. Ansonsten hätte die Änderung keine Wirkung.

¹⁾ Wenn die App aus der App-Übersicht (Historie) geschlossen wird, steht nur begrenzte Zeit und ein begrenzter Funktionsumfang zur Verfügung (Test mit Version Android Oreo, 8.1). Dieser reicht nicht aus, um die Objekte zum Zeitpunkt des Schließen zu erstellen.

RemoveOnDestroyAction entfernt den Auftrag, eine neue Benachrichtigung beim Schließen des Screens anzuzeigen.

AreNotificationsEnabled und AreNotificationsPaused liefern Informationen zum Status des Notification-Systems.

UrsIntent-Komponente

Über ein UrsIntent-Objekt (Referenz), dass den Create...-Funktionen übergeben wird, wird festgelegt, welche Aktion ausgeführt werden soll, wenn die Benachrichtigung angetippt wird.

Diese Komponente ist eine Sammlung von Eigenschaften. Sie besitzt weder Funktionen noch Ereignisse.

Der Aktionstyp (ActionType) bestimmt, welche Aktion mit dem Intent ausgelöst wird:

• None: Beim Antippen der Benachrichtigung oder der Aktionsschaltfläche geschieht nichts.
• Screen: Beim Antippen der Benachrichtigung wird der bezeichnete Screen der eigenen App geöffnet.
• Launcher: Beim Antippen der Benachrichtigung wird eine beliebige App geöffnet. Siehe hierzu auch die ActivityStarter-Dokumentation des App Inventor.
• Event: Das Ereignis UrsNotification.OnClick wird ausgelöst.
• GoBack: Das Benachrichtigungsfenster (Notification Panel) wird geschlossen und zu letzten ausgeführten App zurück gekehrt.

Über die Eigenschaft ID können die Intents beim OnClick-Ereignis unterschieden werden. Wenn man also bei einer Benachrichtigung mit Aktionsschaltflächen das OnClick-Ereignis nutzen will, muss für die eigentliche Benachrichtigung und für jede Aktionsschaltfläche eine andere UrsIntent-Instanz übergegeben werden, die sich mindestens in der ID unterscheiden. Die ID der zugehörigen UrsIntent-Instanz wird dem OnClick-Ereignis übergeben.

---

Fehler-Codes

Code	Fehlertext	Bedeutung	Auslöser
17001	Invalid value at UrsChannelObject.	Falscher Typ beim Parameter UrsChannelObject.	UrsNotification.Create, UrsNotification.SetOnDestroyAction
17002	Invalid Vibration Pattern	Ungültiges Vibrationsmuster.	UrsAI2NotificationChannel (beim Start der App)
17003	Invalid sound file name	Die angegebene Audiodatei existiert nicht.	UrsAI2NotificationChannel (beim Start der App)
17004	Screen not found: <screen name>	Der angegebene Screen existiert nicht.	UrsAI2NotificationChannel.CreateAiNotification
17005	Invalid value at UrsNotificationObject.	Falscher Typ beim Parameter UrsNotificationObject.	UrsAI2NotificationChannel: CreateNotification, CreateAlarm, CreateAlarmEx, CreateAlarmAt, CreateProgressNotification UrsNotification.SetOnDestroyAction
17006	Invalid value at UrsIntentObject	Falscher Typ beim Parameter UrsIntentObject.	UrsAI2NotificationChannel: CreateActionNotification, CreateNotification, CreateAlarm, CreateAlarmEx, UrsAI2NotificationChannel.CreateAlarmAt, CreateProgressNotification UrsNotification: AddActionButton, Create, SetOnDestroyAction
17007	Invalid Delay value	Delay ist kleiner als 1.	UrsAI2NotificationChannel: CreateAlarm, CreateAlarmEx
17008	Invalid Millis value	Die Angabe ist kleiner als die aktuelle Zeit.	UrsAI2NotificationChannel.CreateAlarmAt
17009	Notification not created yet	Die Benachrichtigung wurde noch nicht erstellt.	UrsNotification: SetProgress, SetProgressEx, RemoveProgressBar, RemoveProgressBarEx
17010	Must specify Title	Die Angabe zum Parameter  Title fehlt.	UrsNotification.AddActionButton

---

Beispiele:

	Simple Notification Test Dieses Bespiel zeigt, wie die UrsNotificationChannel.Create...-Methoden funktionieren.
	Extended Notification Test Es werden die erweiterten Möglichkeiten, wie Symbole, Bilder und Aktionsschaltflächen gezeigt.
	Progress Bar Test Das Thema ist Anzeige von Fortschrittsbenachrichtigungen.
	Notification Alarm Test Benachrichtigungen werden verzögert oder zu bestimmten Zeitpunkten ausgelöst.
	Remember URS Eine praktische Anwendung, die den Benutzer daran erinnert, die App regelmäßig zu starten.