SafeCheck – dokumentacja techniczna

Spis treści #

1. Opis produktu
2. Stos technologiczny
3. Uruchomienie i budowanie
4. Konfiguracja (dane do podmiany)
5. Struktura projektu
6. Architektura
7. Opis komponentów
8. Sekwencja alarmowa
9. Planowanie alarmów
10. Model danych i przechowywanie
11. Kontrakt komunikacji (Intenty, broadcasty)
12. Powiadomienia
13. Uprawnienia
14. Obsługa numerów telefonów
15. Reklamy (AdMob)
16. Internacjonalizacja
17. Bezpieczeństwo i prywatność
18. Testowanie
19. Wydanie i dystrybucja
20. Znane ograniczenia i dług techniczny
21. Proponowany rozwój (roadmapa)
22. Słownik pojęć

1. Opis produktu #

SafeCheck jest dla osób mieszkających samotnie: seniorów, osób przewlekle chorych, osób pracujących lub podróżujących w pojedynkę. Gdy użytkownik przez dłuższy czas nie daje znaku życia, aplikacja automatycznie powiadamia jego bliskich.

Zasada działania:

1. Użytkownik ustawia długość licznika (domyślnie 48 godzin) i podaje numery telefonów opiekunów.
2. Co jakiś czas naciska duży przycisk „ŻYJĘ!”, który zeruje licznik i rozpoczyna odliczanie od nowa.
3. Gdy licznik dojdzie do zera, telefon włącza głośny alarm, również na zablokowanym ekranie.
4. Jeśli użytkownik nie zareaguje przez około 2,5 minuty, aplikacja wysyła do każdego opiekuna SMS z lokalizacją GPS (linki do Google Maps i Apple Maps).
5. Jeśli użytkownik potwierdzi później, że wszystko w porządku, opiekunowie dostają SMS „fałszywy alarm”.

Cechy wyróżniające:

• Brak konta, rejestracji i serwera. Dane nie opuszczają telefonu, z wyjątkiem SMS-ów wysyłanych do opiekunów.
• SMS-y idą przez sieć komórkową użytkownika, więc nie trzeba internetu ani aplikacji po stronie opiekuna.
• Alarm działa przy zamkniętej aplikacji, w trybie oszczędzania energii i po restarcie telefonu.
• Ostrzeżenia o ustawieniach producentów (Xiaomi, Huawei, Oppo, Vivo), które agresywnie zamykają aplikacje w tle.
• Dystrybucja bez sklepu: plik APK ze strony projektu. Kod jest przygotowany także do ewentualnej publikacji w Google Play przez nabywcę (rozdz. 19.6).

2. Stos technologiczny #

Aplikacja nie korzysta z bibliotek DI (Hilt/Koin), Navigation, Room ani Retrofit. Jest to świadomie prosta architektura „single-activity + Compose”, opisana w rozdziale 6.

3. Uruchomienie i budowanie #

3.1 Wymagania #

• Android Studio Hedgehog (2023.1) lub nowsze. Zalecane jest najnowsze stabilne wydanie.
• JDK 17 (wbudowany w Android Studio).
• Android SDK Platform 35.

3.2 Pierwsze uruchomienie #

1. File → Open i wskaż katalog SafeCheck-kotlin.
2. Poczekaj na Gradle Sync.
3. Wybierz konfigurację app i urządzenie (fizyczne albo emulator z Google Play Services) → Run.

AdMob i FusedLocationProvider wymagają Google Play Services. Na emulatorze wybierz obraz systemu z oznaczeniem Google APIs lub Google Play.

3.3 Linia poleceń #

./gradlew assembleDebug        # APK testowy: app/build/outputs/apk/debug/app-debug.apk
./gradlew installDebug         # instalacja na podłączonym urządzeniu
./gradlew assembleRelease      # APK produkcyjny (wymaga podpisu, patrz rozdz. 19)
./gradlew bundleRelease        # AAB (tylko przy ewentualnej publikacji w Google Play)
./gradlew lint                 # analiza statyczna

3.4 Warianty budowania #

4. Konfiguracja (dane do podmiany) #

Wszystkie dane zależne od właściciela aplikacji są w jednym miejscu: gradle.properties, w sekcji „KONFIGURACJA APLIKACJI”. Plik app/build.gradle.kts odczytuje je funkcją config(). Brak klucza przerywa budowanie czytelnym komunikatem.

Wartości domyślne w repozytorium:

• Reklamy: oficjalne testowe ID Google. Działają od razu, wyświetlają reklamy z napisem „Test Ad” i nie generują przychodu.
• Linki do dokumentów i strona pobierania: strona projektu https://safecheckapk.github.io. Nabywca podmienia je na własną stronę – gotowe dokumenty do opublikowania są w katalogu docs/strona/, patrz rozdział 19.5.

Pozostałe elementy marki:

5. Struktura projektu #

SafeCheck-kotlin/
├── README.md                       – skrócony opis i szybki start
├── CHANGELOG.md                    – historia zmian
├── LICENSE.md                      – licencja (kod poufny, wszelkie prawa zastrzeżone)
├── docs/
│   ├── DOKUMENTACJA_TECHNICZNA.md  – ten dokument
│   └── strona/                     – dokumenty dla użytkowników (do hostowania)
│       ├── docs.html               – przeglądarka plików .md (?file=...)
│       ├── instrukcja.md
│       ├── regulamin.md
│       └── polityka-prywatnosci.md
├── gradle.properties               – KONFIGURACJA APLIKACJI
├── settings.gradle.kts / build.gradle.kts
├── gradle/wrapper/                 – Gradle Wrapper 8.5
└── app/
    ├── build.gradle.kts            – konfiguracja modułu, zależności, BuildConfig
    ├── proguard-rules.pro
    └── src/main/
        ├── AndroidManifest.xml
        ├── java/com/example/safecheck/
        │   ├── MainActivity.kt     – UI (wszystkie ekrany), ustawienia, uprawnienia
        │   ├── AdsConsentManager.kt – zgoda na reklamy (Google UMP, RODO)
        │   ├── AlarmService.kt     – usługa pierwszoplanowa: alarm, dźwięk, GPS, SMS
        │   ├── AlarmScheduler.kt   – planowanie alarmu w AlarmManager
        │   ├── AlarmReceiver.kt    – odbiorca alarmu systemowego
        │   ├── BootReceiver.kt     – przywracanie alarmu po restarcie
        │   └── AlarmActivity.kt    – pełnoekranowy ekran alarmu
        └── res/
            ├── values/ values-pl/ values-de/ values-fr/   – teksty
            ├── drawable/ mipmap-*/                        – grafiki i ikony
            └── xml/                                       – reguły kopii zapasowej

5.1 Organizacja MainActivity.kt #

Plik ma około 2600 linii i jest podzielony na ponumerowane sekcje, oznaczone w kodzie komentarzami // N. NAZWA:

Rekomendacja: przy dalszym rozwoju warto rozbić plik na pakiety ui/screens, ui/dialogs, permissions, data (patrz rozdział 21).

6. Architektura #

6.1 Widok ogólny #

flowchart LR
    subgraph UI["Warstwa UI (Compose)"]
        MA[MainActivity<br/>ekrany + nawigacja]
        AA[AlarmActivity<br/>ekran alarmu]
    end
    subgraph BG["Warstwa tła"]
        AS[AlarmService<br/>foreground service]
        AR[AlarmReceiver]
        BR[BootReceiver]
        SCH[AlarmScheduler]
    end
    subgraph DATA["Dane"]
        SP[(SharedPreferences<br/>safecheck_local_db)]
    end
    subgraph SYS["System / zewnętrzne"]
        AM[AlarmManager]
        SMS[SmsManager → operator]
        GPS[FusedLocationProvider]
        ADS[Google AdMob]
    end

    MA -- LocalPrefs --> SP
    MA -- scheduleAlarm --> SCH
    MA -- Intent I_AM_ALIVE / ALARM_TRIGGER --> AS
    MA -- reklamy --> ADS
    SCH --> AM
    AM -- alarm --> AR
    AR -- START_SEQUENCE --> AS
    AR --> AA
    BR -- po restarcie --> SCH
    BR -- termin minął --> AS
    AS -- odczyt --> SP
    AS -- broadcast UPDATE_ALARM_UI --> AA
    AA -- I_AM_ALIVE --> AS
    AS --> GPS
    AS --> SMS

6.2 Założenia architektoniczne #

• Single Activity + Compose. Wszystkie ekrany konfiguracji i ekran główny działają w MainActivity. Osobną aktywnością jest tylko AlarmActivity, bo musi się pokazywać na ekranie blokady.

• Nawigacja oparta na stanie. Zamiast biblioteki Navigation blok when w MainActivity.onCreate() wybiera ekran na podstawie flag (isLanguageSet, isNameSet, isConfigured, isIntroSeen).

• Stan UI trzymany jest w remember { mutableStateOf(...) } wewnątrz composable. Aplikacja nie ma ViewModeli. Trwałe dane trafiają do LocalPrefs (SharedPreferences).

• Źródło prawdy o terminie to klucz alarm_target (timestamp w ms). Czytają go UI (MainDashboard), AlarmService i BootReceiver.

• Podwójne zabezpieczenie wyzwolenia alarmu:

  1. alarm systemowy w AlarmManager, który działa przy zamkniętej aplikacji,
  2. pętla w MainDashboard, która sprawdza czas co 100 ms, gdy ekran jest widoczny.

  Duplikację startu sekwencji blokuje warunek currentStage == 0 w AlarmService.

6.3 Przepływ ekranów #

flowchart TD
    S[SplashScreen<br/>2 s] --> L{isLanguageSet?}
    L -- nie --> LS[LanguageSelectionScreen] -->|recreate| S
    L -- tak --> N{isNameSet?}
    N -- nie --> NE[NameEntryScreen<br/>imię + zgoda na regulamin]
    N -- tak --> C{isConfigured?<br/>są opiekunowie}
    NE --> C
    C -- nie --> SE[SetupScreen<br/>numery opiekunów]
    C -- tak --> I{isIntroSeen?}
    SE --> I
    I -- nie --> IN[IntroScreen<br/>7 plansz]
    I -- tak --> D[MainDashboard]
    IN --> D
    D -- "Usuń konto" --> CLR[prefs.clear + recreate] --> S

Od momentu wyjścia ze SplashScreen aktywne są też komponenty Check…UI(), które w razie braku uprawnień nakładają okna z prośbą o ich nadanie.

7. Opis komponentów #

7.1 MainActivity (MainActivity.kt, sekcja 4) #

Motyw: MaterialTheme.colorScheme.copy(primary = SafeGreen, background = BgColor).

7.2 LocalPrefs #

Jedyny punkt dostępu do zapisanych danych – korzystają z niego UI, AlarmService i BootReceiver. Dane są w dwóch plikach (patrz rozdział 10):

• safecheck_local_db – ustawienia użytkownika, objęte kopią zapasową Androida,
• safecheck_device_state – termin licznika na tym urządzeniu, wyłączony z kopii zapasowej.

Nazwy plików i kluczy są stałymi w LocalPrefs.Companion. Ustawienia zapisywane są asynchronicznie (apply()), termin licznika synchronicznie (commit()), bo odczytują go też procesy w tle.

Dodatkowo:

• isRestoredWithoutTimer – true, gdy aplikacja jest skonfigurowana (imię + opiekunowie), ale na urządzeniu nie ma terminu, czyli ustawienia przywrócono z kopii zapasowej. MainDashboard uruchamia wtedy licznik od nowa i pokazuje komunikat restored_from_backup,
• migracja w init: termin zapisany przez wersje ≤ 2.5.2 w pliku ustawień jest jednorazowo przenoszony do pliku stanu urządzenia.

7.3 Ekrany konfiguracji #

7.4 MainDashboard (sekcja 6) #

• Stan: targetTime, timeLeftMs, duration, progress (0..1) i isAlarmTriggered.
• Pętla licznika: LaunchedEffect(targetTime, duration).
  • Przy starcie planuje alarm (AlarmScheduler.scheduleAlarm).
  • Co 100 ms przelicza pozostały czas.
  • Synchronizuje się z prefs.alarmTargetTime, bo termin może zmienić AlarmService po akcji z powiadomienia.
  • Po dojściu do zera wysyła ALARM_TRIGGER do AlarmService.
• Przycisk „ŻYJĘ!”:
  • nowy termin = teraz + timerDuration,
  • I_AM_ALIVE do AlarmService,
  • reklama pełnoekranowa.
• Licznik dd:hh:mm:ss: kliknięcie otwiera TimeEditDialog.
• Menu boczne (ModalNavigationDrawer):
  • opiekunowie (okno edycji listy),
  • zaproszenia (najpierw prośba o READ_CONTACTS),
  • zarządzanie kontem,
  • język,
  • o aplikacji,
  • przycisk „Sprawdź uprawnienia” (openSettings),
  • „Usuń konto”: anulowanie alarmów, zatrzymanie usługi, prefs.clear(), recreate().
• Baner AdMob: AndroidView { AdView(...) }, rozmiar AdSize.BANNER.

7.5 Okna dialogowe (sekcja 7) #

7.6 AlarmService (AlarmService.kt) #

Usługa pierwszoplanowa (foregroundServiceType="specialUse|location"), uruchamiana jako START_REDELIVER_INTENT.

7.7 AdsConsentManager #

Obiekt obsługujący zgodę na reklamy przez Google UMP 2.2.0:

W buildach debug region jest wymuszany na EOG (DEBUG_GEOGRAPHY_EEA), więc formularz pojawia się przy każdej czystej instalacji. Fizyczne urządzenia testowe dodaje się w safecheck.umpTestDeviceIds. Wersja release korzysta z rzeczywistej lokalizacji użytkownika.

7.8 AlarmScheduler #

Opis w rozdziale 9.

7.9 AlarmReceiver #

Odbiera alarm z AlarmManager. Uruchamia AlarmService z akcją START_SEQUENCE (startForegroundService na API 26+) oraz AlarmActivity z flagami NEW_TASK | CLEAR_TOP.

7.10 BootReceiver #

Nasłuchuje BOOT_COMPLETED, QUICKBOOT_POWERON i USER_PRESENT, ale reaguje tylko na BOOT_COMPLETED, bo tak sprawdza akcję w kodzie.

• Termin w przyszłości → ponowne zaplanowanie alarmu.
• Termin minął (telefon był wyłączony) → natychmiastowy ALARM_TRIGGER.

7.11 AlarmActivity #

• Pokazuje się nad ekranem blokady i włącza wyświetlacz: setShowWhenLocked, setTurnScreenOn, requestDismissKeyguard na API 27+, flagi okna na starszych.
• Composable AlarmScreen rejestruje odbiornik UPDATE_ALARM_UI (RECEIVER_NOT_EXPORTED) i wyświetla:
  • tytuł i treść etapu,
  • pierścień odliczania 30 s,
  • przycisk „ŻYJĘ!” (260 dp).
• Kolory: czerwone tło podczas alarmu, żółte podczas przerwy.

8. Sekwencja alarmowa #

8.1 Etapy #

Etap 6 zaczyna się 150 s (2,5 min) po wybuchu alarmu. SMS wysyłany jest raz (flaga smsSent) do wszystkich opiekunów.

8.2 Diagram stanów #

stateDiagram-v2
    [*] --> Czuwanie
    Czuwanie --> Etap1: termin minął
    Etap1 --> Etap2: 30 s
    Etap2 --> Etap3: 30 s
    Etap3 --> Etap4: 30 s
    Etap4 --> Etap5: 30 s
    Etap5 --> Etap6_SMS: 30 s
    Etap1 --> Czuwanie: ŻYJĘ!
    Etap2 --> Czuwanie: ŻYJĘ!
    Etap3 --> Czuwanie: ŻYJĘ!
    Etap4 --> Czuwanie: ŻYJĘ!
    Etap5 --> Czuwanie: ŻYJĘ!
    Etap6_SMS --> Czuwanie: ŻYJĘ! (+ SMS „fałszywy alarm”)

8.3 Diagram sekwencji (alarm przy zamkniętej aplikacji) #

sequenceDiagram
    participant AM as AlarmManager
    participant AR as AlarmReceiver
    participant AS as AlarmService
    participant AA as AlarmActivity
    participant U as Użytkownik
    participant O as Opiekun

    AM->>AR: alarm (alarm_target)
    AR->>AS: START_SEQUENCE
    AR->>AA: start (nad ekranem blokady)
    loop etapy 1..5 (co 30 s)
        AS->>AA: UPDATE_ALARM_UI (tytuł, treść, sekundy)
    end
    AS->>AS: getCurrentLocation()
    AS->>O: SMS z lokalizacją
    U->>AA: „ŻYJĘ!”
    AA->>AS: I_AM_ALIVE
    AS->>O: SMS „fałszywy alarm”
    AS->>AM: nowy termin (scheduleAlarm)

8.4 Treść SMS-ów #

Szablony są w AlarmService.kt (trimIndent()), {imię} = user_name:

• z lokalizacją: nagłówek „🚨🚨🚨 SafeCheck ALARM!”, informacja „{imię} NIE POTWIERDZIŁ OBECNOŚCI!”, linki https://www.google.com/maps?q=lat,lng i http://maps.apple.com/?ll=lat,lng.
• brak uprawnienia GPS: dopisek „(BRAK DOSTĘPU DO GPS)”.
• brak pozycji / błąd lokalizacji: „Nie udało się ustalić lokalizacji.” / „Błąd ustalania lokalizacji.”
• fałszywy alarm: „SafeCheck: Fałszywy alarm. {imię} potwierdził obecność. Wszystko w porządku.”

Emoji wymuszają kodowanie UCS-2 (70 znaków na segment). Wiadomość z lokalizacją ma kilka segmentów, a każdy segment operator nalicza jak osobny SMS.

9. Planowanie alarmów #

AlarmScheduler (obiekt Kotlin) zarządza jednym alarmem końca licznika.

Dlaczego setAlarmClock: system traktuje go jak budzik. Odpala go dokładnie także w trybie Doze, a w pasku statusu pokazuje ikonę zbliżającego się alarmu. Na Android 12+ wymaga canScheduleExactAlarms() == true, inaczej planowanie jest pomijane (patrz CheckExactAlarmPermissionUI).

Kiedy alarm jest (prze)planowany:

Poprawka w 2.5.2: w wersji 2.5.1 istniał drugi, równoległy alarm (requestCode 1001, setExactAndAllowWhileIdle). Nie był aktualizowany przy zmianie długości licznika ani anulowany przy usunięciu konta, przez co mógł wywołać fałszywy alarm, a w konsekwencji niepotrzebny SMS do opiekunów. Szczegóły są w CHANGELOG.

10. Model danych i przechowywanie #

10.1 SharedPreferences #

Dane są w dwóch plikach w prywatnym katalogu aplikacji (/data/data/<pakiet>/shared_prefs/). Dostęp wyłącznie przez LocalPrefs.

Plik safecheck_local_db.xml – ustawienia użytkownika (objęty kopią zapasową):

Plik safecheck_device_state.xml – stan licznika na tym urządzeniu (wyłączony z kopii zapasowej):

W wersjach ≤ 2.5.2 alarm_target był zapisany w safecheck_local_db.xml. LocalPrefs przenosi go automatycznie przy pierwszym uruchomieniu wersji 2.5.3 (migracja zweryfikowana na emulatorze).

10.2 Klasy danych #

data class LanguageOption(val code: String, val name: String, val flag: String)
data class IntroStep(val title: String, val description: String, val icon: ImageVector)
data class PhoneContact(val name: String, val phoneNumber: String)
data class Country(val code: String, val name: String, val dialCode: String, val flagEmoji: String)

10.3 Kopia zapasowa #

Aplikacja nie ma własnej funkcji kopii zapasowej ani konta. Korzysta z mechanizmu systemu Android – Auto Backup (kopia na koncie Google) i device-to-device transfer (przenoszenie danych przy konfiguracji nowego telefonu). Włącza to android:allowBackup="true" w manifeście, a zakres określają reguły:

Reguły typu include oznaczają, że kopiowany jest wyłącznie plik ustawień. Nie są kopiowane: termin licznika (safecheck_device_state.xml), ustawienia zgody UMP, pliki WebView ani inne dane.

Co dzieje się po przywróceniu na nowym telefonie:

Dlaczego termin jest wyłączony z kopii: przywrócony stary termin zwykle już minął, więc pierwsze otwarcie aplikacji natychmiast uruchomiłoby alarm, a bez reakcji – SMS do opiekunów (problem istniał do wersji 2.5.2).

Ograniczenia (zależne od systemu, nie od aplikacji):

• kopia wymaga włączonej kopii zapasowej Google; system wykonuje ją zwykle raz na dobę (urządzenie bezczynne, ładowanie, Wi-Fi),
• aplikacja dystrybuowana jako APK nie jest automatycznie instalowana na nowym telefonie podczas jego konfiguracji – użytkownik instaluje ją ręcznie; przywrócenie ustawień przy takiej instalacji zależy od wersji Androida i producenta i nie jest gwarantowane,
• po przywróceniu alarm jest planowany dopiero przy pierwszym otwarciu aplikacji.

Weryfikacja: test T15 (rozdz. 18) – wykonany na emulatorze Pixel 8 przez bmgr z transportem lokalnym.

Aby całkowicie wyłączyć kopię: android:allowBackup="false" w manifeście (wtedy po zmianie telefonu aplikację konfiguruje się od nowa). Należy też zaktualizować politykę prywatności (rozdz. 4.4) i instrukcję (FAQ).

11. Kontrakt komunikacji (Intenty, broadcasty) #

11.1 Akcje AlarmService #

11.2 Broadcast UPDATE_ALARM_UI #

Wysyłany przez AlarmService z setPackage(packageName), odbierany przez AlarmScreen.

11.3 Komponenty w manifeście #

12. Powiadomienia #

Jeden kanał: ALARM_CHANNEL_001 („SafeCheck Alarm”, IMPORTANCE_HIGH, wibracje, bez dźwięku kanału, bo dźwięk gra MediaPlayer, widoczny na ekranie blokady). ID powiadomienia: 1, współdzielone przez wszystkie stany.

Na Android 14+ startForeground jest wywoływane z typem FOREGROUND_SERVICE_TYPE_SPECIAL_USE.

13. Uprawnienia #

Wzorzec Check…UI():

1. Stan hasPermission odczytywany jest przy starcie i odświeżany przy każdym Lifecycle.Event.ON_RESUME (powrót z ustawień).
2. Dla uprawnień runtime okno pokazuje się z opóźnieniem (500 / 800 / 1000 ms), żeby nie nakładały się jednocześnie.
3. PermissionAlertDialog:
   • „Zezwól” otwiera systemowe okno lub ekran ustawień,
   • „Ustawienia” wywołuje openSettings(), czyli autostart producenta (Xiaomi, Huawei/Honor, Oppo, Vivo), a w razie braku ustawienia ogólne lub szczegóły aplikacji.

14. Obsługa numerów telefonów #

• Biblioteka: libphonenumber-android (port Google libphonenumber z metadanymi w zasobach).

• Lista krajów: PhoneNumberUtil.supportedRegions.

  • Nazwy pochodzą z Locale.getDisplayCountry() w bieżącym języku.
  • Flagi emoji są wyliczane z kodu ISO (regional indicator symbols).
  • Lista jest posortowana alfabetycznie, z Polską na początku.

• Walidacja: LaunchedEffect(phoneNumber, selectedCountry):

  1. parse(numer, region),
  2. isValidNumber,
  3. format(E164).

  Wynik (e164, isValid) trafia do wywołującego.

• Zapis: numery opiekunów zapisywane są wyłącznie w formacie E.164 (np. +48601234567).

• GhostMaskTransformation: wizualna maska w polu.

  • Na podstawie przykładowego numeru komórkowego kraju wyznacza oczekiwaną liczbę cyfr.
  • Formatuje „na żywo” przez AsYouTypeFormatter.
  • Cyfry wpisane są czarne, a brakujące szare zera.
  • Własny OffsetMapping utrzymuje poprawną pozycję kursora.

• Ograniczenia pola: tylko cyfry, maks. 15 znaków. Kierunkowy wybiera się z listy krajów.

15. Reklamy (AdMob) #

• Inicjalizacja: dopiero po uzyskaniu zgody, w AdsConsentManager.initializeAdsOnce() (wywoływane z MainActivity.onCreate przez gatherConsent).
• Zgoda RODO/TCF: Google UMP (AdsConsentManager.kt). Formularz pokazuje się użytkownikom z EOG, UK i Szwajcarii. Zmiana decyzji: „O aplikacji” → „Ustawienia prywatności reklam”.
• ID aplikacji (com.google.android.gms.ads.APPLICATION_ID) jest w manifeście jako ${admobAppId}.
• Reklamy nigdy nie są wyświetlane podczas alarmu (AlarmActivity ich nie zawiera).

Wymagania przed publikacją:

1. Konto AdMob, aplikacja i dwie jednostki reklamowe → ID do gradle.properties.
2. Plik app-ads.txt na stronie dewelopera.
3. W konsoli AdMob: Privacy & messaging → European regulations – utwórz i opublikuj komunikat zgody dla swojej aplikacji (język, logo, link do polityki prywatności). Bez tego formularz UMP się nie pojawi. Na testowym ID Google wyświetla się komunikat „Publisher Test Ads”.
4. Aplikacja spoza sklepu (obecny model dystrybucji): AdMob weryfikuje aplikacje przez powiązanie z kartą w obsługiwanym sklepie (Google Play i inne). Aplikacja niepowiązana ze sklepem może mieć ograniczone wyświetlanie reklam (limited ad serving), więc przychód z reklam przy dystrybucji wyłącznie przez APK jest niepewny – patrz ryzyko R5 (rozdz. 20.1).

Całkowite usunięcie reklam:

1. usuń AndroidView { AdView … } z MainDashboard,
2. usuń loadInterstitialAd, showInterstitial, wywołanie showInterstitial(), wywołanie AdsConsentManager.gatherConsent (oraz plik AdsConsentManager.kt i przycisk w AboutAppDialog),
3. usuń zależność play-services-ads i wpis APPLICATION_ID z manifestu,
4. usuń safecheck.admob* z gradle.properties i odpowiadające im wywołania config() oraz zależność user-messaging-platform.

16. Internacjonalizacja #

• Zasoby tekstowe: values/ (angielski, domyślny), values-pl/, values-de/, values-fr/.
• Język wybiera się w aplikacji, niezależnie od systemu. ContextUtils.updateLocale() jest stosowane w attachBaseContext, a zmiana wymaga recreate().
• Dodanie języka:
  1. utwórz values-XX/strings.xml,
  2. dopisz LanguageOption w LanguageSelectionScreen i LanguageChangeDialog.

Teksty niezlokalizowane (wpisane po polsku w kodzie; patrz rozdział 20):

• treści SMS-ów i powiadomień w AlarmService,
• tytuły i opisy okien uprawnień,
• część etykiet: „Proszę podaj swoje imię”, „Cześć, …!”, „Dodaj”, „Start”, „System i Bateria”, „Zezwól”, „Ustawienia”, „Brak przeglądarki”, komunikaty błędów numeru,
• teksty ekranu alarmu: „Ładowanie...”, „ŻYJĘ!”.

Stringi nieużywane (pozostałość po wcześniejszej wersji z weryfikacją SMS): reason_1..4, verify, enter_code, send_sms, sms_verification_req, reg_user, change_btn, change_phone_btn, confirm_delete_btn, delete_why, delete_account_title, error_same_number, current_phone_format, copy_toast_msg, menu_logout, save.

17. Bezpieczeństwo i prywatność #

Szczegóły dla użytkownika są w polityce prywatności.

Tylko przy ewentualnej publikacji w Google Play – sekcja „Bezpieczeństwo danych” (Data safety), propozycja wypełnienia:

• Lokalizacja (przybliżona i dokładna): udostępniana (w SMS do opiekunów wskazanych przez użytkownika), funkcja aplikacji, nie jest zbierana przez dewelopera.
• Informacje osobiste (imię, numery telefonów): przechowywane na urządzeniu; mogą trafić do systemowej kopii zapasowej Google użytkownika.
• Identyfikatory urządzenia / reklamowe: zbierane przez AdMob (reklamy, analityka, zapobieganie oszustwom).
• Dane nie są szyfrowane podczas przesyłania przez sieć SMS (ograniczenie technologii SMS).
• Użytkownik może usunąć dane: „Usuń konto” w aplikacji albo odinstalowanie.

Ostateczne odpowiedzi należy zweryfikować z aktualnym formularzem Play Console i dokumentacją SDK AdMob dotyczącą danych.

18. Testowanie #

Projekt nie zawiera testów automatycznych (patrz roadmapa).

18.1 Scenariusze testów ręcznych #

18.2 Przydatne polecenia ADB #

# zaplanowane alarmy aplikacji
adb shell dumpsys alarm | grep -A3 com.example.safecheck

# podgląd zapisanych danych (tylko build debug)
adb shell run-as com.example.safecheck cat shared_prefs/safecheck_local_db.xml
adb shell run-as com.example.safecheck cat shared_prefs/safecheck_device_state.xml

# T15: kopia zapasowa i przywrócenie (transport lokalny, bez konta Google)
adb shell bmgr enable true
adb shell bmgr transport com.android.localtransport/.LocalTransport
adb shell settings put secure backup_auto_restore 1
adb shell bmgr backupnow com.example.safecheck
adb uninstall com.example.safecheck
adb install app-debug.apk            # przywrócenie następuje przy instalacji
adb shell run-as com.example.safecheck ls shared_prefs
# po teście: powrót do transportu Google
adb shell bmgr transport com.google.android.gms/.backup.BackupTransportService

# nadanie uprawnień bez klikania (emulator / testy)
adb shell pm grant com.example.safecheck android.permission.SEND_SMS
adb shell appops set com.example.safecheck SCHEDULE_EXACT_ALARM allow
adb shell dumpsys deviceidle whitelist +com.example.safecheck

# symulacja trybu Doze
adb shell dumpsys deviceidle force-idle

Uwaga: przy testach na prawdziwym telefonie SMS-y są wysyłane naprawdę i płatne według taryfy. Jako opiekuna wpisz własny drugi numer. Emulator nie wysyła SMS-ów do sieci.

19. Wydanie i dystrybucja #

19.1 Model dystrybucji #

SafeCheck nie jest publikowany w Google Play. Aplikacja jest dystrybuowana jako plik APK:

Konsekwencje dla użytkownika i kodu:

• instalacja wymaga zgody na „instalowanie nieznanych aplikacji” (opisane w instrukcji),
• brak automatycznych aktualizacji – użytkownik pobiera nową wersję ze strony; instaluje się ona na poprzedniej z zachowaniem danych, jeśli ma ten sam klucz podpisu (19.2) i wyższy versionCode (19.3),
• nowy telefon nie zainstaluje aplikacji sam podczas konfiguracji (wpływ na kopię zapasową – rozdz. 10.3),
• wymagania Google Play dotyczące uprawnień (SMS, pełnoekranowe powiadomienia, dokładne alarmy) nie mają zastosowania, dopóki aplikacja nie jest publikowana w sklepie (19.6).

Wydanie nowej wersji (obecny proces):

1. podnieś versionCode / versionName, uzupełnij CHANGELOG.md,
2. ./gradlew assembleRelease, podpisz APK (19.2), zweryfikuj apksigner verify,
3. utwórz wydanie na GitHub (gh release create vX.Y.Z SafeCheck.apk …),
4. zaktualizuj na stronie numer wersji i sumę SHA-256 (sha256sum SafeCheck.apk).

19.2 Podpis aplikacji #

1. Wygeneruj klucz podpisu release (przechowuj go poza repozytorium i w kopii zapasowej):

   keytool -genkeypair -v -keystore safecheck-release.jks -alias safecheck \
           -keyalg RSA -keysize 2048 -validity 10000

2. Dodaj do ~/.gradle/gradle.properties (nie do repozytorium):

   SAFECHECK_STORE_FILE=C:/sciezka/safecheck-release.jks
   SAFECHECK_STORE_PASSWORD=...
   SAFECHECK_KEY_ALIAS=safecheck
   SAFECHECK_KEY_PASSWORD=...

3. W app/build.gradle.kts:

   android {
       signingConfigs {
           create("release") {
               storeFile = file(providers.gradleProperty("SAFECHECK_STORE_FILE").get())
               storePassword = providers.gradleProperty("SAFECHECK_STORE_PASSWORD").get()
               keyAlias = providers.gradleProperty("SAFECHECK_KEY_ALIAS").get()
               keyPassword = providers.gradleProperty("SAFECHECK_KEY_PASSWORD").get()
           }
       }
       buildTypes { release { signingConfig = signingConfigs.getByName("release") } }
   }

Klucz podpisu jest krytyczny przy dystrybucji APK. Android zainstaluje nową wersję na poprzedniej tylko wtedy, gdy obie są podpisane tym samym kluczem. Utrata klucza oznacza, że użytkownicy muszą odinstalować aplikację (tracąc ustawienia) przed instalacją nowej wersji. Przechowuj plik .jks i hasła w co najmniej dwóch bezpiecznych miejscach.

Obecne APK demonstracyjne (2.5.x na stronie projektu) jest podpisane kluczem debug Android Studio. Nabywca powinien wydać kolejne wersje własnym kluczem release – pierwsza taka wersja wymaga jednorazowej reinstalacji u dotychczasowych użytkowników.

19.3 Wersjonowanie #

Przy każdym wydaniu zwiększ versionCode (liczba całkowita, zawsze rosnąca – Android odrzuci instalację wersji o niższym numerze) i versionName w app/build.gradle.kts, a zmiany dopisz do CHANGELOG.md.

19.4 Lista kontrolna wydania #

• własne wartości w gradle.properties (applicationId, AdMob, linki, strona pobierania)
• własny powered_by, ikona i logo
• dane wydawcy w regulaminie, polityce prywatności, instrukcji i licencji (obecnie: Paweł Mościbrodzki – nabywca podmienia na swoje)
• opublikowane dokumenty z docs/strona/ pod adresami z konfiguracji
• app-ads.txt na stronie dewelopera (wymóg AdMob)
• opublikowany komunikat zgody w AdMob → Privacy & messaging (formularz UMP jest już w kodzie)
• podpis release własnym kluczem, kopia zapasowa klucza
• versionCode / versionName + CHANGELOG.md
• testy T1–T16 na co najmniej 2 urządzeniach (w tym Samsung/Xiaomi) z Androidem 14+
• nowe APK w GitHub Releases, suma SHA-256 na stronie

19.5 Hosting dokumentów (instrukcja, regulamin, polityka) #

Katalog docs/strona/ jest gotowy do wrzucenia na dowolny hosting statyczny (np. GitHub Pages, Netlify, serwer WWW):

https://twoja-domena.pl/safecheck/docs.html?file=instrukcja.md
https://twoja-domena.pl/safecheck/docs.html?file=regulamin.md
https://twoja-domena.pl/safecheck/docs.html?file=polityka-prywatnosci.md

• docs.html wczytuje wskazany plik .md i wyświetla go jako sformatowaną stronę. Dopuszcza tylko pliki z białej listy w kodzie.
• Te trzy adresy wpisz do gradle.properties (safecheck.manualUrl, safecheck.termsUrl, safecheck.privacyUrl).
• Pliki .md można też podlinkować bezpośrednio lub przekonwertować do HTML.

19.6 Opcjonalnie: publikacja w Google Play (dla nabywcy) #

Obecnie nieużywane. Jeśli nabywca zdecyduje się opublikować aplikację w Google Play, dodatkowo potrzebne są:

• konto dewelopera Google Play, Play App Signing i plik AAB (./gradlew bundleRelease),
• sekcja Data safety (propozycja w rozdz. 17),
• poniższe deklaracje:

Uwaga: aplikacja z Google Play i APK ze strony podpisane różnymi kluczami nie zaktualizują się wzajemnie.

20. Znane ograniczenia i dług techniczny #

20.1 Ryzyka do weryfikacji przed publikacją #

20.2 Dług techniczny #

20.3 Błędy i braki naprawione w 2.5.2 i 2.5.3 #

21. Proponowany rozwój (roadmapa) #

Krótkoterminowo (przed publikacją / v2.6)

1. Weryfikacja lokalizacji w tle (R2).
2. Lokalizacja wszystkich tekstów (D1, D2).
3. Porządki: D5, D12, minifikacja (D9).

Średnioterminowo (v3.0) 4. Refaktoryzacja do MVVM: ViewModel + StateFlow, DataStore zamiast SharedPreferences, podział MainActivity.kt (D3, D4). 5. Testy jednostkowe i instrumentacyjne + CI (D8). 6. Aktualizacja toolchainu (D7) i migracja przestarzałych API (D6).

Pomysły produktowe

• harmonogram („przypominaj codziennie o 9:00”) zamiast samego licznika,
• wykrywanie upadku / braku ruchu (akcelerometr),
• przycisk SOS wysyłający SMS od razu,
• konfigurowalna długość etapów i liczba ostrzeżeń,
• wiadomość SMS edytowalna przez użytkownika,
• powiadomienia przez komunikatory / e-mail (wymagałoby backendu),
• widżet na ekran główny i kafelek szybkich ustawień z „ŻYJĘ!”,
• wersja Premium bez reklam (np. Google Play Billing przy publikacji w sklepie albo inna forma płatności).

22. Słownik pojęć #

↑ Na górę