72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# ProximityNotificationService
|
|
|
|
## Übersicht
|
|
Der `ProximityNotificationService` im Paket `com.example.snapandsolve.service` ist ein **Android Foreground Service**. Er ermöglicht die Hintergrund-Überwachung des Nutzerstandorts, um proaktiv Benachrichtigungen auszulösen, wenn sich der Nutzer in der Nähe (Standard: 100m) eines in ArcGIS registrierten Straßenschadens befindet.
|
|
|
|
---
|
|
|
|
## 1. Architektur & Lebenszyklus
|
|
Der Dienst ist darauf ausgelegt, unabhängig von der Sichtbarkeit der App zu laufen. Als **Foreground Service** ist er mit einer permanenten System-Benachrichtigung verknüpft, um eine vorzeitige Beendigung durch das Android-Betriebssystem zu verhindern.
|
|
|
|
### Steuerung über das Companion Object
|
|
* **`start(context, featureTable)`**: Initialisiert den Dienst mit der notwendigen Datenquelle und startet ihn.
|
|
* **`stop(context)`**: Beendet das Tracking und den Dienst.
|
|
|
|
---
|
|
|
|
## 2. Funktionsweise des Standorts-Trackings
|
|
|
|
### Initialisierung
|
|
Nach dem Start (`onCreate`) wird die `SystemLocationDataSource` von ArcGIS initialisiert. Diese liefert kontinuierlich Standort-Updates innerhalb eines dedizierten `serviceScope` (CoroutineScope).
|
|
|
|
### Geofencing-Logik (`checkProximityToDamages`)
|
|
Bei jedem Standort-Update führt der Dienst eine räumliche Analyse durch:
|
|
|
|
1. **Abfrage**: Alle verfügbaren Features werden aus der `ServiceFeatureTable` abgerufen.
|
|
2. **Projektion**: Da GPS-Koordinaten (`SpatialReference.wgs84()`) oft nicht mit dem Koordinatensystem der Karte übereinstimmen, wird der Standort des Nutzers mittels `GeometryEngine.projectOrNull` transformiert.
|
|
3. **Distanzberechnung**: Die exakte Entfernung wird über `GeometryEngine.distanceGeodeticOrNull` berechnet. Hierbei wird der Kurventyp `Geodesic` verwendet, um die Erdkrümmung korrekt zu berücksichtigen.
|
|
|
|
|
|
|
|
---
|
|
|
|
## 3. Benachrichtigungs-Management
|
|
|
|
### Spam-Prävention
|
|
Um mehrfache Warnungen für denselben Schaden zu vermeiden, nutzt der Dienst ein internes Cache-System:
|
|
* **`notifiedFeatures`**: Ein Set von `OBJECTID`s, für die bereits eine Benachrichtigung gesendet wurde.
|
|
* **Hysterese-Bereinigung**: Eine ID wird erst dann aus dem Cache entfernt, wenn sich der Nutzer mehr als 150 Meter vom entsprechenden Schaden entfernt hat (`cleanupNotifiedFeatures`). Dies verhindert "flackernde" Benachrichtigungen an der Radiengrenze.
|
|
|
|
### Benachrichtigungs-Inhalt
|
|
Der Dienst sucht dynamisch nach verfügbaren Attributen im ArcGIS-Feature, um den Text zu generieren:
|
|
* **Kategorie**: Prüft Felder wie `Kategorie`, `kategorie`, `Category` oder `category`.
|
|
* **Beschreibung**: Sucht nach zusätzlichen Details in `Beschreibung` oder `Description`.
|
|
|
|
---
|
|
|
|
## 4. Konfiguration & Konstanten
|
|
|
|
| Konstante | Wert | Beschreibung |
|
|
| :--- | :--- | :--- |
|
|
| `PROXIMITY_RADIUS_METERS` | 100.0 | Radius, ab dem eine Warnung ausgelöst wird. |
|
|
| `CHANNEL_ID` | `proximity_notifications` | ID des Android-Benachrichtigungskanals. |
|
|
| `START_STICKY` | Konstante | Sorgt für einen automatischen Neustart des Dienstes nach einem System-Kill. |
|
|
|
|
---
|
|
|
|
## 5. Voraussetzungen & Sicherheit
|
|
|
|
### Erforderliche Berechtigungen
|
|
In der `AndroidManifest.xml` müssen folgende Berechtigungen konfiguriert sein:
|
|
* `ACCESS_FINE_LOCATION` (Präziser Standort)
|
|
* `ACCESS_BACKGROUND_LOCATION` (Standort im Hintergrund)
|
|
* `FOREGROUND_SERVICE` (Erlaubnis für Hintergrunddienste)
|
|
|
|
### Datenintegrität
|
|
Der Dienst setzt voraus, dass die `ServiceFeatureTable` beim Start übergeben wird. Ist die Tabelle `null`, stellt der Dienst die Überprüfung ein und loggt einen Fehler, bleibt aber als Foreground Service aktiv, um Systeminstabilitäten zu vermeiden.
|
|
|
|
---
|
|
|
|
## Fehlerbehandlung
|
|
* **Projektionsfehler**: Falls die Koordinatentransformation fehlschlägt, wird das betroffene Feature übersprungen.
|
|
* **Geometrie-Validierung**: Nur Features mit gültigen Punkt-Geometrien werden verarbeitet. |