Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
b44fd3a435 | ||
|
|
95b3d74ddc | ||
|
|
cebf341839 | ||
|
|
e6cd8eb055 |
@@ -97,14 +97,9 @@ open class DailyNotificationPlugin : Plugin() {
|
||||
}
|
||||
db = DailyNotificationDatabase.getDatabase(context)
|
||||
Log.i(TAG, "Daily Notification Plugin loaded successfully")
|
||||
|
||||
// Phase 1: Perform app launch recovery (cold start only)
|
||||
// Runs asynchronously, non-blocking, with timeout
|
||||
val reactivationManager = ReactivationManager(context)
|
||||
reactivationManager.performRecovery()
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to initialize Daily Notification Plugin", e)
|
||||
// Don't throw - allow plugin to load even if recovery fails
|
||||
// Don't throw - allow plugin to load but database operations will fail gracefully
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -102,47 +102,50 @@ class NotifyReceiver : BroadcastReceiver() {
|
||||
val notificationId = reminderId ?: "notify_${triggerAtMillis}"
|
||||
|
||||
// Store notification content in database before scheduling alarm
|
||||
// Phase 1: Always create NotificationContentEntity for recovery tracking
|
||||
// This allows recovery to detect missed notifications even for static reminders
|
||||
// Use runBlocking to call suspend function from non-suspend context
|
||||
// This is acceptable here because we're not in a UI thread and need to ensure
|
||||
// content is stored before scheduling the alarm
|
||||
try {
|
||||
runBlocking {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val contentCache = db.contentCacheDao().getLatest()
|
||||
|
||||
// Always create a notification content entity for recovery tracking
|
||||
// Phase 1: Recovery needs NotificationContentEntity to detect missed notifications
|
||||
val roomStorage = com.timesafari.dailynotification.storage.DailyNotificationStorageRoom(context)
|
||||
val entity = com.timesafari.dailynotification.entities.NotificationContentEntity(
|
||||
notificationId,
|
||||
"1.0.2", // Plugin version
|
||||
null, // timesafariDid - can be set if available
|
||||
"daily",
|
||||
config.title,
|
||||
config.body ?: (if (contentCache != null) String(contentCache.payload) else ""),
|
||||
triggerAtMillis,
|
||||
java.time.ZoneId.systemDefault().id
|
||||
)
|
||||
entity.priority = when (config.priority) {
|
||||
"high", "max" -> 2
|
||||
"low", "min" -> -1
|
||||
else -> 0
|
||||
// This allows DailyNotificationReceiver to retrieve content via notification ID
|
||||
// FIX: Wrap suspend function calls in coroutine
|
||||
if (!isStaticReminder) {
|
||||
try {
|
||||
// Use runBlocking to call suspend function from non-suspend context
|
||||
// This is acceptable here because we're not in a UI thread and need to ensure
|
||||
// content is stored before scheduling the alarm
|
||||
runBlocking {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val contentCache = db.contentCacheDao().getLatest()
|
||||
|
||||
// If we have cached content, create a notification content entity
|
||||
if (contentCache != null) {
|
||||
val roomStorage = com.timesafari.dailynotification.storage.DailyNotificationStorageRoom(context)
|
||||
val entity = com.timesafari.dailynotification.entities.NotificationContentEntity(
|
||||
notificationId,
|
||||
"1.0.2", // Plugin version
|
||||
null, // timesafariDid - can be set if available
|
||||
"daily",
|
||||
config.title,
|
||||
config.body ?: String(contentCache.payload),
|
||||
triggerAtMillis,
|
||||
java.time.ZoneId.systemDefault().id
|
||||
)
|
||||
entity.priority = when (config.priority) {
|
||||
"high", "max" -> 2
|
||||
"low", "min" -> -1
|
||||
else -> 0
|
||||
}
|
||||
entity.vibrationEnabled = config.vibration ?: true
|
||||
entity.soundEnabled = config.sound ?: true
|
||||
entity.deliveryStatus = "pending"
|
||||
entity.createdAt = System.currentTimeMillis()
|
||||
entity.updatedAt = System.currentTimeMillis()
|
||||
entity.ttlSeconds = contentCache.ttlSeconds.toLong()
|
||||
|
||||
// saveNotificationContent returns CompletableFuture, so we need to wait for it
|
||||
roomStorage.saveNotificationContent(entity).get()
|
||||
Log.d(TAG, "Stored notification content in database: id=$notificationId")
|
||||
}
|
||||
}
|
||||
entity.vibrationEnabled = config.vibration ?: true
|
||||
entity.soundEnabled = config.sound ?: true
|
||||
entity.deliveryStatus = "pending"
|
||||
entity.createdAt = System.currentTimeMillis()
|
||||
entity.updatedAt = System.currentTimeMillis()
|
||||
entity.ttlSeconds = contentCache?.ttlSeconds?.toLong() ?: (7 * 24 * 60 * 60).toLong() // Default 7 days if no cache
|
||||
|
||||
// saveNotificationContent returns CompletableFuture, so we need to wait for it
|
||||
roomStorage.saveNotificationContent(entity).get()
|
||||
Log.d(TAG, "Stored notification content in database: id=$notificationId (for recovery tracking)")
|
||||
} catch (e: Exception) {
|
||||
Log.w(TAG, "Failed to store notification content in database, continuing with alarm scheduling", e)
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
Log.w(TAG, "Failed to store notification content in database, continuing with alarm scheduling", e)
|
||||
}
|
||||
|
||||
// FIX: Use DailyNotificationReceiver (registered in manifest) instead of NotifyReceiver
|
||||
|
||||
@@ -1,301 +0,0 @@
|
||||
package com.timesafari.dailynotification
|
||||
|
||||
import android.content.Context
|
||||
import android.util.Log
|
||||
import kotlinx.coroutines.CoroutineScope
|
||||
import kotlinx.coroutines.Dispatchers
|
||||
import kotlinx.coroutines.launch
|
||||
import kotlinx.coroutines.withTimeout
|
||||
import java.util.concurrent.TimeUnit
|
||||
|
||||
/**
|
||||
* Manages recovery of alarms and notifications on app launch
|
||||
* Phase 1: Cold start recovery only
|
||||
*
|
||||
* Implements: [Plugin Requirements §3.1.2 - App Cold Start](../docs/alarms/03-plugin-requirements.md#312-app-cold-start)
|
||||
* Platform Reference: [Android §2.1.4](../docs/alarms/01-platform-capability-reference.md#214-alarms-can-be-restored-after-app-restart)
|
||||
*
|
||||
* @author Matthew Raymer
|
||||
* @version 1.0.0
|
||||
*/
|
||||
class ReactivationManager(private val context: Context) {
|
||||
|
||||
companion object {
|
||||
private const val TAG = "DNP-REACTIVATION"
|
||||
private const val RECOVERY_TIMEOUT_SECONDS = 2L
|
||||
}
|
||||
|
||||
/**
|
||||
* Perform recovery on app launch
|
||||
* Phase 1: Calls only performColdStartRecovery() when DB is non-empty
|
||||
*
|
||||
* Scenario detection is not implemented in Phase 1 - all app launches
|
||||
* with non-empty DB are treated as cold start. Force stop, boot, and
|
||||
* warm start handling are deferred to Phase 2.
|
||||
*
|
||||
* **Correction**: Must not run when DB is empty (first launch).
|
||||
*
|
||||
* Runs asynchronously with timeout to avoid blocking app startup
|
||||
*
|
||||
* Rollback Safety: If recovery fails, app continues normally
|
||||
*/
|
||||
fun performRecovery() {
|
||||
CoroutineScope(Dispatchers.IO).launch {
|
||||
try {
|
||||
withTimeout(TimeUnit.SECONDS.toMillis(RECOVERY_TIMEOUT_SECONDS)) {
|
||||
Log.i(TAG, "Starting app launch recovery (Phase 1: cold start only)")
|
||||
|
||||
// Correction: Short-circuit if DB is empty (first launch)
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val dbSchedules = db.scheduleDao().getEnabled()
|
||||
|
||||
if (dbSchedules.isEmpty()) {
|
||||
Log.i(TAG, "No schedules present — skipping recovery (first launch)")
|
||||
return@withTimeout
|
||||
}
|
||||
|
||||
val result = performColdStartRecovery()
|
||||
Log.i(TAG, "App launch recovery completed: $result")
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
// Rollback: Log error but don't crash
|
||||
Log.e(TAG, "Recovery failed (non-fatal): ${e.message}", e)
|
||||
// Record failure in history (best effort, don't fail if this fails)
|
||||
try {
|
||||
recordRecoveryFailure(e)
|
||||
} catch (historyError: Exception) {
|
||||
Log.w(TAG, "Failed to record recovery failure in history", historyError)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Perform cold start recovery
|
||||
*
|
||||
* Steps:
|
||||
* 1. Detect missed notifications (scheduled_time < now, not delivered)
|
||||
* 2. Mark missed notifications in database
|
||||
* 3. Verify future alarms are scheduled
|
||||
* 4. Reschedule missing future alarms
|
||||
*
|
||||
* @return RecoveryResult with counts
|
||||
*/
|
||||
private suspend fun performColdStartRecovery(): RecoveryResult {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val currentTime = System.currentTimeMillis()
|
||||
|
||||
Log.i(TAG, "Cold start recovery: checking for missed notifications")
|
||||
|
||||
// Step 1: Detect missed notifications
|
||||
val missedNotifications = try {
|
||||
db.notificationContentDao().getNotificationsReadyForDelivery(currentTime)
|
||||
.filter { it.deliveryStatus != "delivered" }
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to query missed notifications", e)
|
||||
emptyList()
|
||||
}
|
||||
|
||||
var missedCount = 0
|
||||
var missedErrors = 0
|
||||
|
||||
// Step 2: Mark missed notifications
|
||||
missedNotifications.forEach { notification ->
|
||||
try {
|
||||
// Data integrity check: verify notification is valid
|
||||
if (notification.id.isBlank()) {
|
||||
Log.w(TAG, "Skipping invalid notification: empty ID")
|
||||
return@forEach
|
||||
}
|
||||
|
||||
// Update delivery status
|
||||
notification.deliveryStatus = "missed"
|
||||
notification.lastDeliveryAttempt = currentTime
|
||||
notification.deliveryAttempts = notification.deliveryAttempts + 1
|
||||
notification.updatedAt = currentTime
|
||||
|
||||
db.notificationContentDao().updateNotification(notification)
|
||||
missedCount++
|
||||
|
||||
Log.d(TAG, "Marked missed notification: ${notification.id}")
|
||||
} catch (e: Exception) {
|
||||
missedErrors++
|
||||
Log.e(TAG, "Failed to mark missed notification: ${notification.id}", e)
|
||||
// Continue processing other notifications
|
||||
}
|
||||
}
|
||||
|
||||
// Step 3: Verify and reschedule future alarms
|
||||
val schedules = try {
|
||||
db.scheduleDao().getEnabled()
|
||||
.filter { it.kind == "notify" }
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to query schedules", e)
|
||||
emptyList()
|
||||
}
|
||||
|
||||
var rescheduledCount = 0
|
||||
var verifiedCount = 0
|
||||
var rescheduleErrors = 0
|
||||
|
||||
schedules.forEach { schedule ->
|
||||
try {
|
||||
// Data integrity check: verify schedule is valid
|
||||
if (schedule.id.isBlank() || schedule.nextRunAt == null) {
|
||||
Log.w(TAG, "Skipping invalid schedule: ${schedule.id}")
|
||||
return@forEach
|
||||
}
|
||||
|
||||
val nextRunTime = schedule.nextRunAt!!
|
||||
|
||||
// Only check future alarms
|
||||
if (nextRunTime >= currentTime) {
|
||||
// Verify alarm is scheduled
|
||||
val isScheduled = NotifyReceiver.isAlarmScheduled(context, nextRunTime)
|
||||
|
||||
if (isScheduled) {
|
||||
verifiedCount++
|
||||
Log.d(TAG, "Verified scheduled alarm: ${schedule.id} at $nextRunTime")
|
||||
} else {
|
||||
// Reschedule missing alarm
|
||||
rescheduleAlarm(schedule, nextRunTime, db)
|
||||
rescheduledCount++
|
||||
Log.i(TAG, "Rescheduled missing alarm: ${schedule.id} at $nextRunTime")
|
||||
}
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
rescheduleErrors++
|
||||
Log.e(TAG, "Failed to verify/reschedule: ${schedule.id}", e)
|
||||
// Continue processing other schedules
|
||||
}
|
||||
}
|
||||
|
||||
// Step 4: Record recovery in history
|
||||
val result = RecoveryResult(
|
||||
missedCount = missedCount,
|
||||
rescheduledCount = rescheduledCount,
|
||||
verifiedCount = verifiedCount,
|
||||
errors = missedErrors + rescheduleErrors
|
||||
)
|
||||
|
||||
recordRecoveryHistory(db, "cold_start", result)
|
||||
|
||||
Log.i(TAG, "Cold start recovery complete: $result")
|
||||
return result
|
||||
}
|
||||
|
||||
/**
|
||||
* Reschedule an alarm
|
||||
*
|
||||
* Data integrity: Validates schedule before rescheduling
|
||||
*/
|
||||
private suspend fun rescheduleAlarm(
|
||||
schedule: Schedule,
|
||||
nextRunTime: Long,
|
||||
db: DailyNotificationDatabase
|
||||
) {
|
||||
try {
|
||||
// Use existing BootReceiver logic for calculating next run time
|
||||
// For now, use schedule.nextRunAt directly
|
||||
val config = UserNotificationConfig(
|
||||
enabled = schedule.enabled,
|
||||
schedule = schedule.cron ?: schedule.clockTime ?: "0 9 * * *",
|
||||
title = "Daily Notification",
|
||||
body = "Your daily update is ready",
|
||||
sound = true,
|
||||
vibration = true,
|
||||
priority = "normal"
|
||||
)
|
||||
|
||||
NotifyReceiver.scheduleExactNotification(context, nextRunTime, config)
|
||||
|
||||
// Update schedule in database (best effort)
|
||||
try {
|
||||
db.scheduleDao().updateRunTimes(schedule.id, schedule.lastRunAt, nextRunTime)
|
||||
} catch (e: Exception) {
|
||||
Log.w(TAG, "Failed to update schedule in database: ${schedule.id}", e)
|
||||
// Don't fail rescheduling if DB update fails
|
||||
}
|
||||
|
||||
Log.i(TAG, "Rescheduled alarm: ${schedule.id} for $nextRunTime")
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to reschedule alarm: ${schedule.id}", e)
|
||||
throw e // Re-throw to be caught by caller
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Record recovery in history
|
||||
*
|
||||
* Rollback safety: If history recording fails, log warning but don't fail recovery
|
||||
*/
|
||||
private suspend fun recordRecoveryHistory(
|
||||
db: DailyNotificationDatabase,
|
||||
scenario: String,
|
||||
result: RecoveryResult
|
||||
) {
|
||||
try {
|
||||
db.historyDao().insert(
|
||||
History(
|
||||
refId = "recovery_${System.currentTimeMillis()}",
|
||||
kind = "recovery",
|
||||
occurredAt = System.currentTimeMillis(),
|
||||
outcome = if (result.errors == 0) "success" else "partial",
|
||||
diagJson = """
|
||||
{
|
||||
"scenario": "$scenario",
|
||||
"missed_count": ${result.missedCount},
|
||||
"rescheduled_count": ${result.rescheduledCount},
|
||||
"verified_count": ${result.verifiedCount},
|
||||
"errors": ${result.errors}
|
||||
}
|
||||
""".trimIndent()
|
||||
)
|
||||
)
|
||||
} catch (e: Exception) {
|
||||
Log.w(TAG, "Failed to record recovery history (non-fatal)", e)
|
||||
// Don't throw - history recording failure shouldn't fail recovery
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Record recovery failure in history
|
||||
*/
|
||||
private suspend fun recordRecoveryFailure(e: Exception) {
|
||||
try {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
db.historyDao().insert(
|
||||
History(
|
||||
refId = "recovery_failure_${System.currentTimeMillis()}",
|
||||
kind = "recovery",
|
||||
occurredAt = System.currentTimeMillis(),
|
||||
outcome = "failure",
|
||||
diagJson = """
|
||||
{
|
||||
"error": "${e.message}",
|
||||
"error_type": "${e.javaClass.simpleName}"
|
||||
}
|
||||
""".trimIndent()
|
||||
)
|
||||
)
|
||||
} catch (historyError: Exception) {
|
||||
// Silently fail - we're already in error handling
|
||||
Log.w(TAG, "Failed to record recovery failure", historyError)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Data class for recovery results
|
||||
*/
|
||||
private data class RecoveryResult(
|
||||
val missedCount: Int,
|
||||
val rescheduledCount: Int,
|
||||
val verifiedCount: Int,
|
||||
val errors: Int
|
||||
) {
|
||||
override fun toString(): String {
|
||||
return "missed=$missedCount, rescheduled=$rescheduledCount, verified=$verifiedCount, errors=$errors"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,579 +0,0 @@
|
||||
# 🔧 UNIFIED DIRECTIVE: Alarm / Schedule / Notification Documentation & Implementation Stack
|
||||
|
||||
**Author:** Matthew Raymer
|
||||
**Status:** Active – Master Coordination Directive
|
||||
**Scope:** Android & iOS, Capacitor plugin, alarms/schedules/notifications
|
||||
**Version:** 1.1.0
|
||||
**Last Updated:** November 2025
|
||||
**Last Synced With Plugin Version:** v1.1.0
|
||||
|
||||
---
|
||||
|
||||
## 0. Purpose
|
||||
|
||||
Unify all existing alarm/notification documents into a **coherent, layered system** that:
|
||||
|
||||
1. **Eliminates duplication** (especially Android alarm behavior repeated across docs)
|
||||
2. **Separates concerns** into:
|
||||
* Platform facts
|
||||
* Exploration/testing
|
||||
* Plugin requirements
|
||||
* Implementation directives (Phases 1–3)
|
||||
3. **Provides iOS parity** to the existing Android-heavy material
|
||||
4. **Maps OS-level capabilities → plugin guarantees → JS/TS API contract**
|
||||
5. **Standardizes testing** into executable matrices for exploration and regression
|
||||
6. **Connects exploration → design → implementation** and tracks status across that pipeline
|
||||
|
||||
**This directive is the top of the stack.** If any lower-level document conflicts with this one, **this directive wins** unless explicitly noted.
|
||||
|
||||
**Mission Statement**: This directive ensures that every alarm outcome on every platform is predictable, testable, and recoverable, with no undocumented behavior.
|
||||
|
||||
**⚠️ ENFORCEMENT RULE**: No new alarm-related documentation may be created outside Documents A, B, C, or P1–P3. All future changes must modify these documents, not create additional standalone files.
|
||||
|
||||
---
|
||||
|
||||
## 1. Inputs (Existing Documents)
|
||||
|
||||
### 1.1 Platform & Reference Layer
|
||||
|
||||
* `platform-capability-reference.md` – OS-level facts (Android & iOS)
|
||||
* `android-alarm-persistence-directive.md` – Android abilities & limitations, engineering-grade
|
||||
|
||||
### 1.2 Exploration & Findings
|
||||
|
||||
* `plugin-behavior-exploration-template.md` – Structured template for exploring behavior
|
||||
* `explore-alarm-behavior-directive.md` – Exploration directive for behavior & persistence
|
||||
* `exploration-findings-initial.md` – Initial code-level discovery
|
||||
|
||||
### 1.3 Requirements & Implementation
|
||||
|
||||
* `plugin-requirements-implementation.md` – Plugin behavior rules & guarantees
|
||||
* `android-implementation-directive.md` – Umbrella Android implementation overview (app launch recovery, missed alarms, force stop, boot)
|
||||
* Phase directives (normative):
|
||||
* `../android-implementation-directive-phase1.md` – Cold start recovery (minimal viable)
|
||||
* `../android-implementation-directive-phase2.md` – Force stop detection & recovery
|
||||
* `../android-implementation-directive-phase3.md` – Boot receiver missed alarm handling
|
||||
|
||||
### 1.4 Improvement Directive
|
||||
|
||||
* `improve-alarm-directives.md` – Current plan for structural and content improvements across the stack
|
||||
|
||||
---
|
||||
|
||||
## 2. Target Structure (What We're Building)
|
||||
|
||||
We standardize around **three primary doc roles**, plus implementation phases:
|
||||
|
||||
### A. **Platform Reference (Document A)**
|
||||
|
||||
**Goal:** Single, stable, normative OS facts.
|
||||
|
||||
* Merge:
|
||||
* Android section from `android-alarm-persistence-directive.md`
|
||||
* Android & iOS matrices from `platform-capability-reference.md`
|
||||
* Content rules:
|
||||
* NO plugin-specific rules
|
||||
* Just: "what Android/iOS can and cannot do"
|
||||
* Use matrices & short prose only
|
||||
* Label each item as:
|
||||
* **OS-guaranteed**, **Plugin-required**, or **Forbidden** (where relevant)
|
||||
* Output path (recommended):
|
||||
`docs/alarms/01-platform-capability-reference.md`
|
||||
|
||||
### B. **Plugin Behavior Exploration (Document B)**
|
||||
|
||||
**Goal:** Executable exploration & testing spec.
|
||||
|
||||
* Baseline: `plugin-behavior-exploration-template.md` + `explore-alarm-behavior-directive.md`
|
||||
* Remove duplicated platform explanations (refer to Document A instead)
|
||||
* For each scenario (swipe, reboot, force stop, etc.):
|
||||
* Link to source files & functions (line or section refs)
|
||||
* Provide **Expected (OS)** & **Expected (Plugin)** from Docs A + C
|
||||
* Add columns for **Actual Result** and **Notes** (checkbox matrix)
|
||||
* Output path:
|
||||
`docs/alarms/02-plugin-behavior-exploration.md`
|
||||
|
||||
### C. **Plugin Requirements & Implementation Rules (Document C)**
|
||||
|
||||
**Goal:** What the plugin MUST guarantee & how.
|
||||
|
||||
* Baseline: `plugin-requirements-implementation.md` + `improve-alarm-directives.md`
|
||||
* Must include:
|
||||
1. **Plugin Behavior Guarantees & Limitations** by platform (table)
|
||||
2. **Persistence Requirements** (fields, storage, validation, failure modes)
|
||||
3. **Recovery Requirements**:
|
||||
* Boot (Android)
|
||||
* Cold start
|
||||
* Warm start
|
||||
* Force stop (Android)
|
||||
* User-tap recovery
|
||||
4. **Missed alarm handling contract** (definition, triggers, required actions)
|
||||
5. **JS/TS API Contract**:
|
||||
* What JS devs can rely on
|
||||
* Platform caveats (e.g., Force Stop, iOS background limits)
|
||||
6. **Unsupported features / limitations** clearly called out
|
||||
* Output path:
|
||||
`docs/alarms/03-plugin-requirements.md`
|
||||
|
||||
### D. **Implementation Directives (Phase 1–3)**
|
||||
|
||||
Already exist; this directive standardizes their role:
|
||||
|
||||
* **Phase docs are normative for code.**
|
||||
If they conflict with Document C, update the phase docs and then C.
|
||||
|
||||
**⚠️ STRUCTURE FREEZE**: The structure defined in this directive is FINAL. No new document categories may be introduced without updating this master directive first.
|
||||
|
||||
---
|
||||
|
||||
## 3. Ownership, Versioning & Status
|
||||
|
||||
### 3.1 Ownership
|
||||
|
||||
**Assignable Ownership** (replace abstract roles with concrete owners):
|
||||
|
||||
| Layer | Owner | Responsibility |
|
||||
| ---------------------- | ------------------- | ------------------------------------------------- |
|
||||
| Doc A – Platform Facts | Engineering Lead | Long-lived reference, rare changes |
|
||||
| Doc B – Exploration | QA / Testing Lead | Living document, updated with test results |
|
||||
| Doc C – Requirements | Plugin Architect | Versioned with plugin, defines guarantees |
|
||||
| Phases P1–P3 | Implementation Lead | Normative code specs, tied to Doc C requirements |
|
||||
|
||||
**Note**: If owners are not yet assigned, use role names above as placeholders until assignment.
|
||||
|
||||
### 3.2 Versioning Rules
|
||||
|
||||
* Any change that alters **JS/TS-visible behavior** → bump plugin **MINOR** at least
|
||||
* Any change that breaks prior guarantees or adds new required migration → **MAJOR bump**
|
||||
* Each doc should include:
|
||||
* `Version: x.y.z`
|
||||
* `Last Synced With Plugin Version: vX.Y.Z`
|
||||
|
||||
### 3.3 Status Matrix
|
||||
|
||||
**Status matrix is maintained in Section 11** (see below). This section is kept for historical reference only.
|
||||
|
||||
---
|
||||
|
||||
## 4. Work Plan – "Do All of the Above"
|
||||
|
||||
This is the **concrete to-do list** that satisfies:
|
||||
|
||||
* Consolidation
|
||||
* Versioning & ownership
|
||||
* Status tracking
|
||||
* Single-source master structure
|
||||
* Next-phase readiness
|
||||
* Improvements from `improve-alarm-directives.md`
|
||||
|
||||
### Step 1 – Normalize Platform Reference (Doc A)
|
||||
|
||||
1. Start from `platform-capability-reference.md` + `android-alarm-persistence-directive.md`
|
||||
2. Merge into a single doc:
|
||||
* Android matrix
|
||||
* iOS matrix
|
||||
* Core principles (no plugin rules)
|
||||
3. Ensure each line is labeled:
|
||||
* **OS-guaranteed**, **Plugin-required**, or **Forbidden** (where relevant)
|
||||
4. Mark the old Android alarm persistence doc as:
|
||||
* **Deprecated in favor of Doc A** (leave file but add a banner)
|
||||
|
||||
### Step 2 – Rewrite Exploration (Doc B)
|
||||
|
||||
1. Use `plugin-behavior-exploration-template.md` as the skeleton
|
||||
2. Integrate concrete scenario descriptions and code paths from `explore-alarm-behavior-directive.md`
|
||||
3. For **each scenario**:
|
||||
* App swipe, OS kill, reboot, force stop, cold start, warm start, notification tap:
|
||||
* Add row: Step-by-step actions + Expected (OS) + Expected (Plugin) + Actual + Notes
|
||||
4. Remove any explanation that duplicates Doc A; replace with "See Doc A, section X"
|
||||
|
||||
### Step 3 – Rewrite Plugin Requirements (Doc C)
|
||||
|
||||
1. Start from `plugin-requirements-implementation.md` & improvement goals
|
||||
2. Add / enforce sections:
|
||||
* **Plugin Behavior Guarantees & Limitations**
|
||||
* **Persistence Spec** (fields, mandatory vs optional)
|
||||
* **Recovery Points** (boot, cold, warm, force stop, user tap)
|
||||
* **Missed Alarm Contract**
|
||||
* **JS/TS API Contract**
|
||||
* **Unsupported / impossible guarantees** (Force Stop, iOS background, etc.)
|
||||
3. Everywhere it relies on platform behavior:
|
||||
* Link back to Doc A using short cross-reference ("See A §2.1")
|
||||
4. Add a **"Traceability"** mini-table:
|
||||
* Row per behavior → Platform fact in A → Tested scenario in B → Implemented in Phase N
|
||||
|
||||
### Step 4 – Align Implementation Directives with Doc C
|
||||
|
||||
1. Treat Phase docs as **canonical code spec**: P1, P2, P3
|
||||
2. For each behavior required in Doc C:
|
||||
* Identify which Phase implements it (or will implement it)
|
||||
3. Update:
|
||||
* `android-implementation-directive.md` to be explicitly **descriptive/integrative**, not normative, pointing to Phases 1–3 & Doc C
|
||||
* Ensure scenario model, alarm existence checks, and boot handling match the **corrected model** already defined in Phase 2 & 3
|
||||
4. Add acceptance criteria per phase that directly reference:
|
||||
* Requirements in Doc C
|
||||
* Platform constraints in Doc A
|
||||
5. **Phase 1–3 must REMOVE**:
|
||||
* Any scenario logic (moved to Doc C)
|
||||
* Any platform behavioral claims (moved to Doc A)
|
||||
* Any recovery responsibilities not assigned to that phase
|
||||
|
||||
### Step 5 – Versioning & Status
|
||||
|
||||
1. At the top of Docs A, B, C, and each Phase doc, add:
|
||||
* `Version`, `Last Updated`, `Sync'd with Plugin vX.Y.Z`
|
||||
2. Maintain the status matrix (Section 11) as the **single source of truth** for doc maturity
|
||||
3. When a Phase is fully implemented and deployed:
|
||||
* Mark "In Use?" = ✅
|
||||
* Add link to code tags/commit hash
|
||||
|
||||
### Step 6 – Readiness Check for Next Work Phase
|
||||
|
||||
Before starting any *new* implementation work on alarms / schedules:
|
||||
|
||||
1. **Confirm:**
|
||||
* Doc A exists and is stable enough (no "TODO" in core matrices)
|
||||
* Doc B has at least the base scenarios scaffolded
|
||||
* Doc C clearly defines:
|
||||
* What we guarantee on each platform
|
||||
* What we cannot do (e.g., Force Stop auto-resume)
|
||||
2. Only then:
|
||||
* Modify or extend Phase 1–3
|
||||
* Or add new phases (e.g., warm-start optimizations, iOS parity work)
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria for THIS Directive (Revised and Final)
|
||||
|
||||
This directive is complete **ONLY** when:
|
||||
|
||||
1. **Doc A exists, is referenced, and no other doc contains platform facts**
|
||||
* File exists: `docs/alarms/01-platform-capability-reference.md`
|
||||
* All old platform docs marked as deprecated with banner
|
||||
* No platform facts duplicated in other docs
|
||||
|
||||
2. **Doc B contains**:
|
||||
* At least 6 scenarios (swipe, reboot, force stop, cold start, warm start, notification tap)
|
||||
* Expected OS vs Plugin behavior columns
|
||||
* Space for Actual Result and Notes
|
||||
* Links to source files/functions
|
||||
|
||||
3. **Doc C contains**:
|
||||
* Guarantees by platform (table format)
|
||||
* Recovery matrix (boot, cold, warm, force stop, user tap)
|
||||
* JS/TS API contract
|
||||
* Unsupported behaviors clearly called out
|
||||
|
||||
4. **Phase docs**:
|
||||
* Contain NO duplication of Doc A (platform facts)
|
||||
* Reference Doc C explicitly (requirements)
|
||||
* Have acceptance criteria tied to Doc C requirements
|
||||
|
||||
5. **Deprecated files have**:
|
||||
* Banner: "⚠️ **DEPRECATED**: Superseded by [000-UNIFIED-ALARM-DIRECTIVE](./000-UNIFIED-ALARM-DIRECTIVE.md)"
|
||||
* Link to replacement document
|
||||
|
||||
6. **Status matrix fields are no longer empty** (Section 11)
|
||||
* All docs marked as Drafted at minimum
|
||||
|
||||
---
|
||||
|
||||
## 6. Document Relationships & Cross-References
|
||||
|
||||
### 6.1 Reference Flow
|
||||
|
||||
```
|
||||
Unified Directive (this doc)
|
||||
↓
|
||||
├─→ Doc A (Platform Reference)
|
||||
│ └─→ Referenced by: B, C, P1-P3
|
||||
│
|
||||
├─→ Doc B (Exploration)
|
||||
│ └─→ References: A (platform facts), C (expected behavior)
|
||||
│ └─→ Feeds into: P1-P3 (test results inform implementation)
|
||||
│
|
||||
├─→ Doc C (Requirements)
|
||||
│ └─→ References: A (platform constraints)
|
||||
│ └─→ Referenced by: P1-P3 (implementation must satisfy)
|
||||
│
|
||||
└─→ P1-P3 (Implementation)
|
||||
└─→ References: A (platform facts), C (requirements)
|
||||
└─→ Validated by: B (exploration results)
|
||||
```
|
||||
|
||||
### 6.2 Cross-Reference Format
|
||||
|
||||
When referencing between documents, use this format:
|
||||
|
||||
* **Doc A**: `[Platform Reference §2.1](../alarms/01-platform-capability-reference.md#21-android-alarm-persistence)`
|
||||
* **Doc B**: `[Exploration §3.2](../alarms/02-plugin-behavior-exploration.md#32-cold-start-scenario)`
|
||||
* **Doc C**: `[Requirements §4.3](../alarms/03-plugin-requirements.md#43-recovery-requirements)`
|
||||
* **Phase docs**: `[Phase 1 §2.3](../android-implementation-directive-phase1.md#23-cold-start-recovery)`
|
||||
|
||||
---
|
||||
|
||||
## 7. Canonical Source of Truth Rules
|
||||
|
||||
### 7.1 Platform Facts
|
||||
|
||||
**Only Doc A** contains platform facts. All other docs reference Doc A, never duplicate platform behavior.
|
||||
|
||||
**Reference Format**: `[Doc A §X.Y]` - See [Platform Capability Reference](./01-platform-capability-reference.md)
|
||||
|
||||
### 7.2 Requirements
|
||||
|
||||
**Only Doc C** defines plugin requirements. Phase docs implement Doc C requirements.
|
||||
|
||||
**Reference Format**: `[Doc C §X.Y]` - See [Plugin Requirements](./03-plugin-requirements.md)
|
||||
|
||||
### 7.3 Implementation Details
|
||||
|
||||
**Only Phase docs (P1-P3)** contain implementation details. Unified Directive does not specify code structure or algorithms.
|
||||
|
||||
**Reference Format**: `[Phase N §X.Y]` - See Phase implementation directives
|
||||
|
||||
### 7.4 Test Results
|
||||
|
||||
**Only Doc B** contains actual test results and observed behavior. Doc B references Doc A for expected OS behavior and Doc C for expected plugin behavior.
|
||||
|
||||
---
|
||||
|
||||
## 8. Conflict Resolution
|
||||
|
||||
If conflicts arise between documents:
|
||||
|
||||
1. **This directive (000)** wins for structure and organization
|
||||
2. **Doc A** wins for platform facts
|
||||
3. **Doc C** wins for requirements
|
||||
4. **Phase docs (P1-P3)** win for implementation details
|
||||
5. **Doc B** is observational (actual test results) and may reveal conflicts
|
||||
|
||||
When a conflict is found:
|
||||
1. Document it in this section
|
||||
2. Resolve by updating the lower-priority document
|
||||
3. Update the status matrix
|
||||
|
||||
---
|
||||
|
||||
## 9. Next Steps
|
||||
|
||||
### ⚠️ Time-Based Triggers (Enforcement)
|
||||
|
||||
**Doc A must be created BEFORE any further implementation work.**
|
||||
- No Phase 2 or Phase 3 changes until Doc A exists
|
||||
- No new platform behavior claims in any doc until Doc A is canonical
|
||||
|
||||
**Doc B must be baseline-complete BEFORE Phase 2 changes.**
|
||||
- At least 6 core scenarios scaffolded
|
||||
- Expected behavior columns populated from Doc A + Doc C
|
||||
|
||||
**Doc C must be finalized BEFORE any JS/TS API changes.**
|
||||
- All guarantees documented
|
||||
- API contract defined
|
||||
- No breaking changes to JS/TS API without Doc C update first
|
||||
|
||||
### Immediate (Before New Implementation)
|
||||
|
||||
1. Create stub documents A, B, C with structure
|
||||
2. Migrate content from existing docs into new structure
|
||||
3. Update all cross-references
|
||||
4. Mark old docs as deprecated (with pointers to new docs)
|
||||
|
||||
**Deliverables Required**:
|
||||
- Doc A exists as a file in repo
|
||||
- Doc B exists with scenario tables scaffolded
|
||||
- Doc C exists with required sections
|
||||
- Status matrix updated in this document
|
||||
- Deprecated docs marked with header banner
|
||||
|
||||
### Short-term (During Implementation)
|
||||
|
||||
1. Keep Doc B updated with test results
|
||||
2. Update Phase docs as implementation progresses
|
||||
3. Maintain status matrix
|
||||
|
||||
### Long-term (Post-Implementation)
|
||||
|
||||
1. Add iOS parity documentation
|
||||
2. Expand exploration scenarios
|
||||
3. Create regression test suite based on Doc B
|
||||
|
||||
### ⚠️ iOS Parity Activation Milestone
|
||||
|
||||
**iOS parity work begins ONLY after**:
|
||||
|
||||
1. **Doc A contains iOS matrix** - All iOS platform facts documented with labels (see [Doc A](./01-platform-capability-reference.md#3-ios-notification-capability-matrix))
|
||||
2. **Doc C defines iOS limitations and guarantees** - All iOS-specific requirements documented (see [Doc C](./03-plugin-requirements.md#1-plugin-behavior-guarantees--limitations))
|
||||
3. **No references in Phase docs assume Android-only behavior** - All Phase docs are platform-agnostic or explicitly handle both platforms
|
||||
|
||||
**Blocking Rule**: No iOS implementation work may proceed until these conditions are met.
|
||||
|
||||
**Enforcement**: Phase docs MUST reference Doc A for platform facts and Doc C for requirements. No platform-specific assumptions allowed.
|
||||
|
||||
---
|
||||
|
||||
## 10. Change-Control Rules
|
||||
|
||||
Any change to Docs A–C requires:
|
||||
|
||||
1. **Update version header** in the document
|
||||
2. **Update status matrix** (Section 11) in this directive
|
||||
3. **Commit message tag**: `[ALARM-DOCS]` prefix
|
||||
4. **Notification in CHANGELOG** if JS/TS-visible behavior changes
|
||||
|
||||
**Phase docs may not be modified unless Doc C changes first** (or explicit exception documented).
|
||||
|
||||
**Example commit message**:
|
||||
```
|
||||
[ALARM-DOCS] Update Doc C with force stop recovery guarantee
|
||||
|
||||
- Added force stop detection requirement
|
||||
- Updated recovery matrix
|
||||
- Version bumped to 1.1.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Status Matrix
|
||||
|
||||
| Doc | Path | Role | Drafted? | Cleaned? | In Use? | Notes |
|
||||
| --- | ------------------------------------- | ----------------- | -------- | -------- | ------- | ---------------------------------------- |
|
||||
| A | `01-platform-capability-reference.md` | Platform facts | ✅ | ✅ | ✅ | Created, merged from platform docs, canonical rule added |
|
||||
| B | `02-plugin-behavior-exploration.md` | Exploration | ✅ | ✅ | ✅ | Converted to executable test harness + emulator script |
|
||||
| C | `03-plugin-requirements.md` | Requirements | ✅ | ✅ | ✅ | Enhanced with guarantees matrix, JS/TS contract, traceability - **complete and in compliance** |
|
||||
| P1 | `../android-implementation-directive-phase1.md` | Impl – Cold start | ✅ | ✅ | ✅ | Emulator-verified via `test-phase1.sh` (Pixel 8 API 34, 2025-11-27) |
|
||||
| P2 | `../android-implementation-directive-phase2.md` | Impl – Force stop | ✅ | ✅ | ☐ | Implemented; to be emulator-verified via `test-phase2.sh` (Pixel 8 API 34, 2025-11-XX) |
|
||||
| P3 | `../android-implementation-directive-phase3.md` | Impl – Boot Recovery | ✅ | ✅ | ☐ | Implemented; verify via `test-phase3.sh` (API 34 baseline) |
|
||||
| V1 | `PHASE1-VERIFICATION.md` | Verification – P1 | ✅ | ✅ | ✅ | Summarizes Phase 1 emulator tests and latest known good run |
|
||||
| V2 | `PHASE2-VERIFICATION.md` | Verification – P2 | ✅ | ✅ | ☐ | Summarizes Phase 2 emulator tests and latest known good run |
|
||||
| V3 | `PHASE3-VERIFICATION.md` | Verification – P3 | ✅ | ✅ | ☐ | To be completed after first clean emulator run |
|
||||
|
||||
**Doc C Compliance Milestone**: Doc C is considered complete **ONLY** when:
|
||||
- ✅ Cross-platform guarantees matrix present
|
||||
- ✅ JS/TS API contract with returned fields and error states
|
||||
- ✅ Explicit storage schema documented
|
||||
- ✅ Recovery contract with all triggers and actions
|
||||
- ✅ Unsupported behaviors explicitly listed
|
||||
- ✅ Traceability matrix mapping A → B → C → Phase
|
||||
|
||||
**Legend:**
|
||||
- ✅ = Complete
|
||||
- ☐ = Not started / In progress
|
||||
- ⚠️ = Needs attention
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
* [Android Implementation Directive](../android-implementation-directive.md) – Umbrella overview
|
||||
* [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md) – Minimal viable recovery
|
||||
* [Phase 2: Force Stop Recovery](../android-implementation-directive-phase2.md) – Force stop detection
|
||||
* [Phase 3: Boot Recovery](../android-implementation-directive-phase3.md) – Boot receiver enhancement
|
||||
* [Exploration Findings](../exploration-findings-initial.md) – Initial code discovery
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active master coordination directive
|
||||
**Last Updated**: November 2025
|
||||
**Next Review**: After implementation phases are complete
|
||||
|
||||
---
|
||||
|
||||
## 12. Single Instruction for Team
|
||||
|
||||
**⚠️ BLOCKING RULE**: No engineering or documentation work on alarms/schedules/notifications may continue until Steps 1–3 in §9 ("Immediate") are complete and committed.
|
||||
|
||||
**Specifically**:
|
||||
- Doc A must exist as a file
|
||||
- Doc B must have scenario tables scaffolded
|
||||
- Doc C must have required sections
|
||||
- Status matrix must be updated
|
||||
- Deprecated files must be marked
|
||||
|
||||
**Exception**: Only emergency bug fixes may proceed, but must be documented retroactively in the appropriate Doc A/B/C structure.
|
||||
|
||||
---
|
||||
|
||||
## 13. Prohibited Content Rules
|
||||
|
||||
**The following content may NOT appear in any document except the specified one**:
|
||||
|
||||
| Content Type | Allowed Only In | Examples |
|
||||
| ------------ | --------------- | -------- |
|
||||
| **Platform rules** | Doc A only | "Android wipes alarms on reboot", "iOS persists notifications automatically" |
|
||||
| **Guarantees or requirements** | Doc C only | "Plugin MUST detect missed alarms", "Plugin SHOULD reschedule on boot" |
|
||||
| **Actual behavior findings** | Doc B only | "Test showed alarm fired 2 seconds late", "Missed alarm not detected in scenario X" |
|
||||
| **Recovery logic** | Phase docs only | "ReactivationManager.performRecovery()", "BootReceiver sets flag" |
|
||||
| **Implementation details** | Phase docs only | Code snippets, function signatures, database queries |
|
||||
|
||||
**Violation Response**: If prohibited content is found, move it to the correct document and replace with a cross-reference.
|
||||
|
||||
---
|
||||
|
||||
## 14. Glossary
|
||||
|
||||
**Shared terminology across all documents** (must be identical):
|
||||
|
||||
| Term | Definition |
|
||||
| ---- | ---------- |
|
||||
| **recovery** | Process of detecting and handling missed alarms, rescheduling future alarms, and restoring plugin state after app launch, boot, or force stop |
|
||||
| **cold start** | App launched from terminated state (process killed, no memory state) |
|
||||
| **warm start** | App returning from background (process may still exist, memory state may persist) |
|
||||
| **missed alarm** | Alarm where `trigger_time < now`, alarm was not fired (or firing status unknown), alarm is still enabled, and alarm has not been manually cancelled |
|
||||
| **delivered alarm** | Alarm that successfully fired and displayed notification to user |
|
||||
| **persisted alarm** | Alarm definition stored in durable storage (database, files, etc.) |
|
||||
| **cleared alarm** | Alarm removed from AlarmManager/UNUserNotificationCenter but may still exist in persistent storage |
|
||||
| **first run** | First time app is launched after installation (no previous state) |
|
||||
| **notification tap** | User interaction with notification that launches app |
|
||||
| **rescheduled** | Alarm re-registered with AlarmManager/UNUserNotificationCenter after being cleared |
|
||||
| **reactivated** | Plugin state restored and alarms rescheduled after app launch or boot |
|
||||
|
||||
**Usage**: All documents MUST use these exact definitions. No synonyms or variations allowed.
|
||||
|
||||
---
|
||||
|
||||
## 15. Lifecycle Flow Diagram
|
||||
|
||||
**Document relationship and information flow**:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Unified Directive (000) - Master Coordination │
|
||||
│ Defines structure, ownership, change control │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ References & Coordinates
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||
│ Doc A │ │ Doc B │ │ Doc C │
|
||||
│ Platform │ │ Exploration │ │ Requirements│
|
||||
│ Facts │ │ & Testing │ │ & Guarantees│
|
||||
└───────────────┘ └───────────────┘ └───────────────┘
|
||||
│ │ │
|
||||
│ │ │
|
||||
│ │ │
|
||||
│ │ │
|
||||
└───────────────────┼───────────────────┘
|
||||
│
|
||||
│ Implements
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │
|
||||
│ Cold Start │ │ Force Stop │ │ Boot │
|
||||
│ Recovery │ │ Recovery │ │ Recovery │
|
||||
└───────────────┘ └───────────────┘ └───────────────┘
|
||||
```
|
||||
|
||||
**Information Flow**:
|
||||
1. **Doc A** (Platform Facts) → Informs **Doc C** (Requirements) → Drives **Phase Docs** (Implementation)
|
||||
2. **Doc B** (Exploration) → Validates **Phase Docs** → Updates **Doc C** (Requirements)
|
||||
3. **Phase Docs** → Implements **Doc C** → Tested by **Doc B**
|
||||
|
||||
**Key Principle**: Platform facts (A) constrain requirements (C), which drive implementation (Phases), which are validated by exploration (B).
|
||||
|
||||
@@ -1,468 +0,0 @@
|
||||
# Platform Capability Reference: Android & iOS Alarm/Notification Behavior
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Platform Reference - Stable
|
||||
**Version**: 1.1.0
|
||||
**Last Synced With Plugin Version**: v1.1.0
|
||||
|
||||
## Purpose
|
||||
|
||||
This document provides **pure OS-level facts** about alarm and notification capabilities on Android and iOS. It contains **no plugin-specific logic**—only platform mechanics that affect plugin design.
|
||||
|
||||
**This is a reference document** to be consulted when designing plugin behavior, not an implementation guide.
|
||||
|
||||
**⚠️ CANONICAL RULE**: No other document may contain OS-level behavior. All platform facts **MUST** reference this file. If platform behavior is described elsewhere, it **MUST** be moved here and replaced with a reference.
|
||||
|
||||
**⚠️ DEPRECATED**: The following documents are superseded by this reference:
|
||||
- `platform-capability-reference.md` - Merged into this document
|
||||
- `android-alarm-persistence-directive.md` - Merged into this document
|
||||
|
||||
**See**: [Unified Alarm Directive](./000-UNIFIED-ALARM-DIRECTIVE.md) for document structure.
|
||||
|
||||
---
|
||||
|
||||
## 1. Core Principles
|
||||
|
||||
### Android
|
||||
|
||||
Android does **not** guarantee persistence of alarms across process death, swipes, or reboot.
|
||||
|
||||
It is the app's responsibility to **persist alarm definitions** and **re-schedule them** under allowed system conditions.
|
||||
|
||||
### iOS
|
||||
|
||||
iOS **does** persist scheduled local notifications across app termination and device reboot, but:
|
||||
|
||||
* App code does **not** run when notifications fire (unless user interacts)
|
||||
* Background execution is severely limited
|
||||
* Apps must persist their own state if they need to track or recover missed notifications
|
||||
|
||||
---
|
||||
|
||||
## 2. Android Alarm Capability Matrix
|
||||
|
||||
| Scenario | Will Alarm Fire? | OS Behavior | App Responsibility | Label |
|
||||
| --------------------------------------- | --------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- | ------------- |
|
||||
| **Swipe from Recents** | ✅ Yes | AlarmManager resurrects the app process | None (OS handles) | OS-guaranteed |
|
||||
| **App silently killed by OS** | ✅ Yes | AlarmManager still holds scheduled alarms | None (OS handles) | OS-guaranteed |
|
||||
| **Device Reboot** | ❌ No (auto) / ✅ Yes (if app reschedules) | All alarms wiped on reboot | Apps may reschedule from persistent storage on boot | Plugin-required |
|
||||
| **Doze Mode** | ⚠️ Only "exact" alarms | Inexact alarms deferred; exact alarms allowed | Apps must use `setExactAndAllowWhileIdle` | Plugin-required |
|
||||
| **Force Stop** | ❌ Never | Android blocks all callbacks + receivers until next user launch | Cannot bypass; apps may detect on app restart | Forbidden |
|
||||
| **User reopens app** | ✅ Apps may reschedule & recover | App process restarted | Apps may detect missed alarms and reschedule future ones | Plugin-required |
|
||||
| **PendingIntent from user interaction** | ✅ If triggered by user | User action unlocks the app | None (OS handles) | OS-guaranteed |
|
||||
|
||||
### 2.1 Android Allowed Behaviors
|
||||
|
||||
#### 2.1.1 Alarms survive UI kills (swipe from recents)
|
||||
|
||||
**OS-guaranteed**: `AlarmManager.setExactAndAllowWhileIdle(...)` alarms **will fire** even after:
|
||||
* App is swiped away
|
||||
* App process is killed by the OS
|
||||
|
||||
The OS recreates your app's process to deliver the `PendingIntent`.
|
||||
|
||||
**Required API**: `setExactAndAllowWhileIdle()` or `setAlarmClock()`
|
||||
|
||||
#### 2.1.2 Alarms can be preserved across device reboot
|
||||
|
||||
**Plugin-required**: Android wipes all alarms on reboot, but **apps may recreate them**.
|
||||
|
||||
**OS Behavior**: All alarms are cleared on device reboot. No alarms persist automatically.
|
||||
|
||||
**App Capability**: Apps may recreate alarms after reboot by:
|
||||
1. Persisting alarm definitions in durable storage (Room DB, SharedPreferences, etc.)
|
||||
2. Registering a `BOOT_COMPLETED` / `LOCKED_BOOT_COMPLETED` broadcast receiver
|
||||
3. Rescheduling alarms from storage after boot completes
|
||||
|
||||
**Required Permission**: `RECEIVE_BOOT_COMPLETED`
|
||||
|
||||
**OS Condition**: User must have launched the app at least once before reboot for boot receiver to execute
|
||||
|
||||
#### 2.1.3 Alarms can fire full-screen notifications and wake the device
|
||||
|
||||
**OS-guaranteed**: **Required API**: `setFullScreenIntent(...)`, use an IMPORTANCE_HIGH channel with `CATEGORY_ALARM`
|
||||
|
||||
This allows Clock-app–style alarms even when the app is not foregrounded.
|
||||
|
||||
#### 2.1.4 Alarms can be restored after app restart
|
||||
|
||||
**Plugin-required**: If the user re-opens the app (direct user action), apps may:
|
||||
* Access persistent storage (database, files, etc.)
|
||||
* Query alarm definitions
|
||||
* Reschedule alarms using AlarmManager
|
||||
* Reconstruct WorkManager/JobScheduler tasks that were cleared
|
||||
|
||||
**OS Behavior**: When user opens app, app code can execute. AlarmManager and WorkManager APIs are available for rescheduling.
|
||||
|
||||
**Note**: This is an app capability, not OS-guaranteed behavior. Apps must implement this logic.
|
||||
|
||||
### 2.2 Android Forbidden Behaviors
|
||||
|
||||
#### 2.2.1 You cannot survive "Force Stop"
|
||||
|
||||
**Forbidden**: **Settings → Apps → YourApp → Force Stop** triggers:
|
||||
* Removal of all alarms
|
||||
* Removal of WorkManager tasks
|
||||
* Blocking of all broadcast receivers (including BOOT_COMPLETED)
|
||||
* Blocking of all JobScheduler jobs
|
||||
* Blocking of AlarmManager callbacks
|
||||
* Your app will NOT run until the user manually launches it again
|
||||
|
||||
**Directive**: Accept that FORCE STOP is a hard kill. No scheduling, alarms, jobs, or receivers may execute afterward.
|
||||
|
||||
#### 2.2.2 You cannot auto-resume after "Force Stop"
|
||||
|
||||
**Forbidden**: You may only resume tasks when:
|
||||
* The user opens your app
|
||||
* The user taps a notification belonging to your app
|
||||
* The user interacts with a widget/deep link
|
||||
* Another app explicitly targets your component
|
||||
|
||||
**OS Behavior**: Apps may only resume tasks when user opens app, taps notification, interacts with widget/deep link, or another app explicitly targets the component.
|
||||
|
||||
#### 2.2.3 Alarms cannot be preserved solely in RAM
|
||||
|
||||
**Forbidden**: Android can kill your app's RAM state at any time.
|
||||
|
||||
**OS Behavior**: All alarm data must be persisted in durable storage. RAM-only storage is not reliable.
|
||||
|
||||
#### 2.2.4 You cannot bypass Doze or battery optimization restrictions without permission
|
||||
|
||||
**Conditional**: Doze may defer inexact alarms; exact alarms with `setExactAndAllowWhileIdle` are allowed.
|
||||
|
||||
**Required Permission**: `SCHEDULE_EXACT_ALARM` on Android 12+ (API 31+)
|
||||
|
||||
---
|
||||
|
||||
## 3. iOS Notification Capability Matrix
|
||||
|
||||
| Scenario | Will Notification Fire? | OS Behavior | App Responsibility | Label |
|
||||
| --------------------------------------- | ----------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- | ------------- |
|
||||
| **Swipe from App Switcher** | ✅ Yes | UNUserNotificationCenter persists and fires notifications | None (OS handles) | OS-guaranteed |
|
||||
| **App Terminated by System** | ✅ Yes | UNUserNotificationCenter persists and fires notifications | None (OS handles) | OS-guaranteed |
|
||||
| **Device Reboot** | ✅ Yes (for calendar/time triggers) | iOS persists scheduled local notifications across reboot | None for notifications; must persist own state if needed | OS-guaranteed |
|
||||
| **App Force Quit (swipe away)** | ✅ Yes | UNUserNotificationCenter persists and fires notifications | None (OS handles) | OS-guaranteed |
|
||||
| **Background Execution** | ❌ No arbitrary code | Only BGTaskScheduler with strict limits | Cannot rely on background execution for recovery | Forbidden |
|
||||
| **Notification Fires** | ✅ Yes | Notification displayed; app code does NOT run unless user interacts | Must handle missed notifications on next app launch | OS-guaranteed |
|
||||
| **User Taps Notification** | ✅ Yes | App launched; code can run | Can detect and handle missed notifications | OS-guaranteed |
|
||||
|
||||
### 3.1 iOS Allowed Behaviors
|
||||
|
||||
#### 3.1.1 Notifications survive app termination
|
||||
|
||||
**OS-guaranteed**: `UNUserNotificationCenter` scheduled notifications **will fire** even after:
|
||||
* App is swiped away from app switcher
|
||||
* App is terminated by system
|
||||
* Device reboots (for calendar/time-based triggers)
|
||||
|
||||
**Required API**: `UNUserNotificationCenter.add()` with `UNCalendarNotificationTrigger` or `UNTimeIntervalNotificationTrigger`
|
||||
|
||||
#### 3.1.2 Notifications persist across device reboot
|
||||
|
||||
**OS-guaranteed**: iOS **automatically** persists scheduled local notifications across reboot.
|
||||
|
||||
**No app code required** for basic notification persistence.
|
||||
|
||||
**Limitation**: Only calendar and time-based triggers persist. Location-based triggers do not.
|
||||
|
||||
#### 3.1.3 Background tasks for prefetching
|
||||
|
||||
**Conditional**: **Required API**: `BGTaskScheduler` with `BGAppRefreshTaskRequest`
|
||||
|
||||
**Limitations**:
|
||||
* Minimum interval between tasks (system-controlled, typically hours)
|
||||
* System decides when to execute (not guaranteed)
|
||||
* Cannot rely on background execution for alarm recovery
|
||||
* Must schedule next task immediately after current one completes
|
||||
|
||||
### 3.2 iOS Forbidden Behaviors
|
||||
|
||||
#### 3.2.1 App code does not run when notification fires
|
||||
|
||||
**Forbidden**: When a scheduled notification fires:
|
||||
* Notification is displayed to user
|
||||
* **No app code executes** unless user taps the notification
|
||||
* Cannot run arbitrary code at notification time
|
||||
|
||||
**Workaround**: Use notification actions or handle missed notifications on next app launch.
|
||||
|
||||
#### 3.2.2 No repeating background execution
|
||||
|
||||
**Forbidden**: iOS does not provide repeating background execution APIs except:
|
||||
* `BGTaskScheduler` (system-controlled, not guaranteed)
|
||||
* Background fetch (deprecated, unreliable)
|
||||
|
||||
**OS Behavior**: Apps cannot rely on background execution to reconstruct alarms. Apps must persist state and recover on app launch.
|
||||
|
||||
#### 3.2.3 No arbitrary code on notification trigger
|
||||
|
||||
**Forbidden**: Unlike Android's `PendingIntent` which can execute code, iOS notifications only:
|
||||
* Display to user
|
||||
* Launch app if user taps
|
||||
* Execute notification action handlers (if configured)
|
||||
|
||||
**OS Behavior**: All recovery logic must run on app launch, not at notification time.
|
||||
|
||||
#### 3.2.4 Background execution limits
|
||||
|
||||
**Forbidden**: **BGTaskScheduler Limitations**:
|
||||
* Minimum intervals between tasks (system-controlled)
|
||||
* System may defer or skip tasks
|
||||
* Tasks have time budgets (typically 30 seconds)
|
||||
* Cannot guarantee execution timing
|
||||
|
||||
**Directive**: Use BGTaskScheduler for prefetching only, not for critical scheduling.
|
||||
|
||||
---
|
||||
|
||||
## 4. Cross-Platform Comparison
|
||||
|
||||
| Feature | Android | iOS | Label |
|
||||
| -------------------------------- | --------------------------------------- | --------------------------------------------- | ------------- |
|
||||
| **Survives swipe/termination** | ✅ Yes (with exact alarms) | ✅ Yes (automatic) | OS-guaranteed |
|
||||
| **Survives reboot** | ❌ No (must reschedule) | ✅ Yes (automatic for calendar/time triggers) | Mixed |
|
||||
| **App code runs on trigger** | ✅ Yes (via PendingIntent) | ❌ No (only if user interacts) | Mixed |
|
||||
| **Background execution** | ✅ WorkManager, JobScheduler | ⚠️ Limited (BGTaskScheduler only) | Mixed |
|
||||
| **Force stop equivalent** | ✅ Force Stop (hard kill) | ❌ No user-facing equivalent | Android-only |
|
||||
| **Boot recovery required** | ✅ Yes (must implement) | ❌ No (OS handles) | Android-only |
|
||||
| **Missed alarm detection** | ✅ Must implement on app launch | ✅ Must implement on app launch | Plugin-required |
|
||||
| **Exact timing** | ✅ Yes (with permission) | ⚠️ ±180s tolerance | Mixed |
|
||||
| **Repeating notifications** | ✅ Must reschedule each occurrence | ✅ Can use `repeats: true` in trigger | Mixed |
|
||||
|
||||
---
|
||||
|
||||
## 5. Android API Level Matrix
|
||||
|
||||
### 5.1 Alarm Scheduling APIs by API Level
|
||||
|
||||
| API Level | Available APIs | Label | Notes |
|
||||
| --------- | -------------- | ----- | ----- |
|
||||
| **API 19-20** (KitKat) | `setExact()` | OS-Permitted | May be deferred in Doze |
|
||||
| **API 21-22** (Lollipop) | `setExact()`, `setAlarmClock()` | OS-Guaranteed | `setAlarmClock()` preferred |
|
||||
| **API 23+** (Marshmallow+) | `setExact()`, `setAlarmClock()`, `setExactAndAllowWhileIdle()` | OS-Guaranteed | `setExactAndAllowWhileIdle()` required for Doze |
|
||||
| **API 31+** (Android 12+) | All above + `SCHEDULE_EXACT_ALARM` permission required | Conditional | Permission must be granted by user |
|
||||
|
||||
### 5.2 Android S+ Exact Alarm Permission Decision Tree
|
||||
|
||||
**Android 12+ (API 31+) requires `SCHEDULE_EXACT_ALARM` permission**:
|
||||
|
||||
```
|
||||
Is API level >= 31?
|
||||
├─ NO → No permission required
|
||||
└─ YES → Check permission status
|
||||
├─ Granted → Can schedule exact alarms
|
||||
├─ Not granted → Must request permission
|
||||
│ ├─ User grants → Can schedule exact alarms
|
||||
│ └─ User denies → Cannot schedule exact alarms (use inexact or show error)
|
||||
└─ Revoked → Cannot schedule exact alarms (user must re-enable in Settings)
|
||||
```
|
||||
|
||||
**Label**: Conditional (requires user permission on Android 12+)
|
||||
|
||||
### 5.3 Required Platform APIs
|
||||
|
||||
**Alarm Scheduling**:
|
||||
* `AlarmManager.setExactAndAllowWhileIdle()` - Android 6.0+ (API 23+) - **OS-Guaranteed**
|
||||
* `AlarmManager.setAlarmClock()` - Android 5.0+ (API 21+) - **OS-Guaranteed**
|
||||
* `AlarmManager.setExact()` - Android 4.4+ (API 19+) - **OS-Permitted** (may be deferred in Doze)
|
||||
|
||||
**Permissions**:
|
||||
* `RECEIVE_BOOT_COMPLETED` - Boot receiver - **OS-Permitted** (requires user to launch app once)
|
||||
* `SCHEDULE_EXACT_ALARM` - Android 12+ (API 31+) - **Conditional** (user must grant)
|
||||
|
||||
**Background Work**:
|
||||
* `WorkManager` - Deferrable background work - **OS-Permitted** (timing not guaranteed)
|
||||
* `JobScheduler` - Alternative (API 21+) - **OS-Permitted** (timing not guaranteed)
|
||||
|
||||
### 5.2 iOS
|
||||
|
||||
**Notification Scheduling**:
|
||||
* `UNUserNotificationCenter.add()` - Schedule notifications
|
||||
* `UNCalendarNotificationTrigger` - Calendar-based triggers
|
||||
* `UNTimeIntervalNotificationTrigger` - Time interval triggers
|
||||
|
||||
**Background Tasks**:
|
||||
* `BGTaskScheduler.submit()` - Schedule background tasks
|
||||
* `BGAppRefreshTaskRequest` - Background fetch requests
|
||||
|
||||
**Permissions**:
|
||||
* Notification authorization (requested at runtime)
|
||||
|
||||
---
|
||||
|
||||
## 6. iOS Timing Tolerance Table
|
||||
|
||||
### 6.1 Notification Timing Accuracy
|
||||
|
||||
| Trigger Type | Timing Tolerance | Label | Notes |
|
||||
| ------------ | ---------------- | ----- | ----- |
|
||||
| **Calendar-based** (`UNCalendarNotificationTrigger`) | ±180 seconds | OS-Permitted | System may defer for battery optimization |
|
||||
| **Time interval** (`UNTimeIntervalNotificationTrigger`) | ±180 seconds | OS-Permitted | System may defer for battery optimization |
|
||||
| **Location-based** (`UNLocationNotificationTrigger`) | Not applicable | OS-Permitted | Does not persist across reboot |
|
||||
|
||||
**Source**: [Apple Developer Documentation - UNNotificationTrigger](https://developer.apple.com/documentation/usernotifications/unnotificationtrigger)
|
||||
|
||||
### 6.2 Background Task Timing
|
||||
|
||||
| Task Type | Execution Window | Label | Notes |
|
||||
| --------- | ---------------- | ----- | ----- |
|
||||
| **BGAppRefreshTask** | System-controlled (hours between tasks) | OS-Permitted | Not guaranteed, system decides |
|
||||
| **BGProcessingTask** | System-controlled | OS-Permitted | Not guaranteed, system decides |
|
||||
|
||||
**Source**: [Apple Developer Documentation - BGTaskScheduler](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler)
|
||||
|
||||
---
|
||||
|
||||
## 7. Platform-Specific Constraints Summary
|
||||
|
||||
### 6.1 Android Constraints
|
||||
|
||||
1. **Reboot**: All alarms wiped; must reschedule from persistent storage
|
||||
2. **Force Stop**: Hard kill; cannot bypass until user opens app
|
||||
3. **Doze**: Inexact alarms deferred; must use exact alarms
|
||||
4. **Exact Alarm Permission**: Required on Android 12+ for precise timing
|
||||
5. **Boot Receiver**: Must be registered and handle `BOOT_COMPLETED`
|
||||
|
||||
### 6.2 iOS Constraints
|
||||
|
||||
1. **Background Execution**: Severely limited; cannot rely on it for recovery
|
||||
2. **Notification Firing**: App code does not run; only user interaction triggers app
|
||||
3. **Timing Tolerance**: ±180 seconds for calendar triggers
|
||||
4. **BGTaskScheduler**: System-controlled; not guaranteed execution
|
||||
5. **State Persistence**: Must persist own state if tracking missed notifications
|
||||
|
||||
---
|
||||
|
||||
## 8. Revision Sources
|
||||
|
||||
### 8.1 AOSP Version
|
||||
|
||||
**Android Open Source Project**: Based on AOSP 14 (Android 14) behavior
|
||||
|
||||
**Last Validated**: November 2025
|
||||
|
||||
**Source Files Referenced**:
|
||||
* `frameworks/base/core/java/android/app/AlarmManager.java`
|
||||
* `frameworks/base/core/java/android/app/PendingIntent.java`
|
||||
|
||||
### 8.2 Official Documentation
|
||||
|
||||
**Android**:
|
||||
* [AlarmManager - Android Developers](https://developer.android.com/reference/android/app/AlarmManager)
|
||||
* [Schedule exact alarms - Android Developers](https://developer.android.com/training/scheduling/alarms)
|
||||
|
||||
**iOS**:
|
||||
* [UNUserNotificationCenter - Apple Developer](https://developer.apple.com/documentation/usernotifications/unusernotificationcenter)
|
||||
* [BGTaskScheduler - Apple Developer](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler)
|
||||
|
||||
### 8.3 Tested Device Set
|
||||
|
||||
**Android Devices Tested**:
|
||||
* Pixel 7 (Android 14)
|
||||
* Samsung Galaxy S23 (Android 13)
|
||||
* OnePlus 11 (Android 13)
|
||||
|
||||
**iOS Devices Tested**:
|
||||
* iPhone 15 (iOS 17)
|
||||
* iPhone 14 (iOS 16)
|
||||
|
||||
**Note**: OEM-specific behavior variations documented in [§8 - OEM Variation Policy](#8-oem-variation-policy)
|
||||
|
||||
### 8.4 Last Validated on Physical Devices
|
||||
|
||||
**Last Validation Date**: November 2025
|
||||
|
||||
**Validation Scenarios**:
|
||||
* Swipe from recents - ✅ Validated on all devices
|
||||
* Device reboot - ✅ Validated on all devices
|
||||
* Force stop (Android) - ✅ Validated on Android devices
|
||||
* Background execution (iOS) - ✅ Validated on iOS devices
|
||||
|
||||
**Unvalidated Scenarios**:
|
||||
* OEM-specific variations (Xiaomi, Huawei) - ⚠️ Not yet tested
|
||||
|
||||
---
|
||||
|
||||
## 9. Label Definitions
|
||||
|
||||
**Required Labels** (every platform behavior MUST be tagged):
|
||||
|
||||
| Label | Definition | Usage |
|
||||
| ----- | ---------- | ----- |
|
||||
| **OS-Guaranteed** | The operating system provides this behavior automatically. No plugin code required. | Use when OS handles behavior without app intervention |
|
||||
| **OS-Permitted but not guaranteed** | The OS allows this behavior, but timing/execution is not guaranteed. Plugin may need fallbacks. | Use for background execution, system-controlled timing |
|
||||
| **Forbidden** | This behavior is not possible on this platform. Plugin must not attempt it. | Use for hard OS limitations (e.g., Force Stop bypass) |
|
||||
| **Undefined / OEM-variant** | Behavior varies by device manufacturer or OS version. Not universal. | Use when behavior differs across OEMs or OS versions |
|
||||
|
||||
**Legacy Labels** (maintained for backward compatibility):
|
||||
- **Plugin-required**: The plugin must implement this behavior. The OS does not provide it automatically.
|
||||
- **Conditional**: This behavior is possible but requires specific conditions (permissions, APIs, etc.).
|
||||
|
||||
---
|
||||
|
||||
## 10. OEM Variation Policy
|
||||
|
||||
**Android is not monolithic** — behavior may vary by OEM (Samsung, Xiaomi, Huawei, etc.).
|
||||
|
||||
**Policy**:
|
||||
* **Do not document** until reproduced in testing
|
||||
* **Mark as "Observed-variant (not universal)"** if behavior differs from AOSP
|
||||
* **Test on multiple devices** before claiming universal behavior
|
||||
* **Document OEM-specific workarounds** in Doc C (Requirements), not Doc A (Platform Facts)
|
||||
|
||||
**Example**:
|
||||
* ❌ **Wrong**: "All Android devices wipe alarms on reboot"
|
||||
* ✅ **Correct**: "AOSP Android wipes alarms on reboot. Observed on: Samsung, Pixel, OnePlus. Not tested on: Xiaomi, Huawei."
|
||||
|
||||
---
|
||||
|
||||
## 11. Citation Rule
|
||||
|
||||
**Platform facts must come from authoritative sources**:
|
||||
|
||||
**Allowed Sources**:
|
||||
1. **AOSP source code** - Direct inspection of Android Open Source Project
|
||||
2. **Official Android/iOS documentation** - developer.android.com, developer.apple.com
|
||||
3. **Reproducible test results** (Doc B) - Empirical evidence from testing
|
||||
|
||||
**Prohibited Sources**:
|
||||
* Stack Overflow answers (unless verified)
|
||||
* Blog posts (unless citing official docs)
|
||||
* Assumptions or "common knowledge"
|
||||
* Unverified OEM-specific claims
|
||||
|
||||
**Citation Format**:
|
||||
* For AOSP: `[AOSP: AlarmManager.java:123]`
|
||||
* For official docs: `[Android Docs: AlarmManager]`
|
||||
* For test results: `[Doc B: Test 4 - Device Reboot]`
|
||||
|
||||
**If source is unclear**: Mark as "Unverified" or "Needs citation" until verified.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Unified Alarm Directive](./000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document
|
||||
- [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md) - Uses this reference
|
||||
- [Plugin Requirements](./03-plugin-requirements.md) - Implementation based on this reference
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.1.0** (November 2025): Enhanced with API levels, timing tables, revision sources
|
||||
- Added Android API level matrix
|
||||
- Added Android S+ exact alarm permission decision tree
|
||||
- Added iOS timing tolerance table
|
||||
- Added revision sources section
|
||||
- Added tested device set
|
||||
- Enhanced labeling consistency
|
||||
|
||||
- **v1.0.0** (November 2025): Initial platform capability reference
|
||||
- Merged from `platform-capability-reference.md` and `android-alarm-persistence-directive.md`
|
||||
- Android alarm matrix with labels
|
||||
- iOS notification matrix with labels
|
||||
- Cross-platform comparison
|
||||
- Label definitions
|
||||
|
||||
@@ -1,469 +0,0 @@
|
||||
# Plugin Behavior Exploration: Alarm/Schedule/Notification Testing
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Active Exploration Template
|
||||
**Version**: 1.1.0
|
||||
**Last Synced With Plugin Version**: v1.1.0
|
||||
|
||||
## Purpose
|
||||
|
||||
This document provides an **executable test harness** for exploring and documenting the current plugin's alarm/schedule/notification behavior on Android and iOS.
|
||||
|
||||
**This is a test specification document** - it contains only test scenarios, expected results, and actual results. It does NOT contain platform explanations or requirements.
|
||||
|
||||
**Use this document to**:
|
||||
1. Execute test scenarios
|
||||
2. Document actual vs expected results
|
||||
3. Identify gaps between current behavior and requirements
|
||||
4. Generate findings for the Plugin Requirements document
|
||||
|
||||
**⚠️ RULE**: This document contains NO platform explanations. All expected OS behavior must reference [Doc A](./01-platform-capability-reference.md). All expected plugin behavior must reference [Doc C](./03-plugin-requirements.md).
|
||||
|
||||
**Reference**:
|
||||
- [Platform Capability Reference](./01-platform-capability-reference.md) - OS-level facts (Doc A)
|
||||
- [Plugin Requirements](./03-plugin-requirements.md) - Plugin guarantees and requirements (Doc C)
|
||||
|
||||
---
|
||||
|
||||
## 0. Reproducibility Protocol
|
||||
|
||||
**Each scenario MUST define**:
|
||||
|
||||
1. **Device model & OS version**: e.g., "Pixel 7, Android 14", "iPhone 15, iOS 17"
|
||||
2. **App build hash**: Git commit hash or build number
|
||||
3. **Preconditions**: State before test (alarms scheduled, app state, etc.)
|
||||
4. **Steps**: Exact sequence of actions
|
||||
5. **Expected vs Actual**: Clear comparison of expected vs observed behavior
|
||||
|
||||
**Reproducibility Requirements**:
|
||||
* Test must be repeatable by another engineer
|
||||
* All steps must be executable without special setup
|
||||
* Results must be verifiable (logs, UI state, database state)
|
||||
* Timing-sensitive tests must specify wait times
|
||||
|
||||
**Failure Documentation**:
|
||||
* Capture logs immediately
|
||||
* Screenshot UI state if relevant
|
||||
* Record exact error messages
|
||||
* Note any non-deterministic behavior
|
||||
|
||||
---
|
||||
|
||||
## 0.1 Quick Reference
|
||||
|
||||
**For platform capabilities**: See [Doc A - Platform Capability Reference](./01-platform-capability-reference.md)
|
||||
|
||||
**For plugin requirements**: See [Doc C - Plugin Requirements](./03-plugin-requirements.md)
|
||||
|
||||
**This document contains only test scenarios and results** - no platform explanations or requirements.
|
||||
|
||||
---
|
||||
|
||||
## 1. Android Exploration
|
||||
|
||||
### 1.1 Code-Level Inspection Checklist
|
||||
|
||||
**Source Locations**:
|
||||
- Plugin: `android/src/main/java/com/timesafari/dailynotification/`
|
||||
- Test App: `test-apps/android-test-app/`
|
||||
- Manifest: `test-apps/android-test-app/app/src/main/AndroidManifest.xml`
|
||||
|
||||
| Task | File/Function | Line | Status | Notes |
|
||||
| ---- | ------------- | ---- | ------ | ----- |
|
||||
| Locate main plugin class | `DailyNotificationPlugin.kt` | 1302 | ☐ | `scheduleDailyNotification()` |
|
||||
| Identify alarm scheduling | `NotifyReceiver.kt` | 92 | ☐ | `scheduleExactNotification()` |
|
||||
| Check AlarmManager usage | `NotifyReceiver.kt` | 219, 223, 231 | ☐ | `setAlarmClock()`, `setExactAndAllowWhileIdle()`, `setExact()` |
|
||||
| Check WorkManager usage | `FetchWorker.kt` | 31 | ☐ | `scheduleFetch()` |
|
||||
| Check notification display | `DailyNotificationWorker.java` | 200+ | ☐ | `displayNotification()` |
|
||||
| Check boot receiver | `BootReceiver.kt` | 24 | ☐ | `onReceive()` handles `BOOT_COMPLETED` |
|
||||
| Check persistence | `DailyNotificationPlugin.kt` | 1393+ | ☐ | Room database storage |
|
||||
| Check exact alarm permission | `DailyNotificationPlugin.kt` | 1309 | ☐ | `canScheduleExactAlarms()` |
|
||||
| Check manifest permissions | `AndroidManifest.xml` | - | ☐ | `RECEIVE_BOOT_COMPLETED`, `SCHEDULE_EXACT_ALARM` |
|
||||
|
||||
### 1.2 Behavior Testing Matrix
|
||||
|
||||
#### Test 1: Base Case
|
||||
|
||||
| Step | Action | Trigger Source | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | -------------- | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule alarm 2 minutes in future | Plugin | - | Alarm scheduled | ☐ | |
|
||||
| 2 | Leave app in foreground/background | - | - | - | ☐ | |
|
||||
| 3 | Wait for trigger time | OS | Alarm fires | Notification displayed | ☐ | |
|
||||
| 4 | Check logs | - | - | No errors | ☐ | |
|
||||
|
||||
**Trigger Source Definitions**:
|
||||
- **OS**: Operating system initiates the action (alarm fires, boot completes, etc.)
|
||||
- **User**: User initiates the action (taps notification, opens app, force stops app)
|
||||
- **Plugin**: Plugin code initiates the action (schedules alarm, detects missed alarm, etc.)
|
||||
|
||||
**Code Reference**: `NotifyReceiver.scheduleExactNotification()` line 92
|
||||
|
||||
**Platform Behavior**: See [Platform Reference §2.1.1](./01-platform-capability-reference.md#211-alarms-survive-ui-kills-swipe-from-recents)
|
||||
|
||||
---
|
||||
|
||||
#### Test 2: Swipe from Recents
|
||||
|
||||
**Preconditions**:
|
||||
- App installed and launched at least once
|
||||
- Alarm scheduling permission granted (if required)
|
||||
- Test device: [Device model, OS version]
|
||||
- App build: [Git commit hash or build number]
|
||||
|
||||
| Step | Action | Trigger Source | Expected (OS) [Doc A] | Expected (Plugin) [Doc C] | Actual Result | Notes | Result |
|
||||
| ---- | ------ | -------------- | ---------------------- | -------------------------- | ------------- | ----- | ------ |
|
||||
| 1 | Schedule alarm 2-5 minutes in future | Plugin | - | Alarm scheduled | ☐ | | ☐ |
|
||||
| 2 | Swipe app away from recents | User | - | - | ☐ | | ☐ |
|
||||
| 3 | Wait for trigger time | OS | ✅ Alarm fires (OS resurrects process) - [Doc A §2.1.1](./01-platform-capability-reference.md#211-alarms-survive-ui-kills-swipe-from-recents) | ✅ Notification displayed - [Doc C §1.1](./03-plugin-requirements.md#11-guarantees-by-platform) | ☐ | | ☐ |
|
||||
| 4 | Check app state on wake | OS | Cold start | App process recreated | ☐ | | ☐ |
|
||||
| 5 | Check logs | - | - | No errors | ☐ | | ☐ |
|
||||
|
||||
**Code Reference**: `NotifyReceiver.scheduleExactNotification()` uses `setAlarmClock()` line 219
|
||||
|
||||
**Platform Behavior Reference**: [Doc A §2.1.1](./01-platform-capability-reference.md#211-alarms-survive-ui-kills-swipe-from-recents) - OS-guaranteed
|
||||
|
||||
---
|
||||
|
||||
#### Test 3: OS Kill (Memory Pressure)
|
||||
|
||||
**Preconditions**:
|
||||
- App installed and launched at least once
|
||||
- Alarm scheduled and verified in AlarmManager
|
||||
- Test device: [Device model, OS version]
|
||||
- App build: [Git commit hash or build number]
|
||||
|
||||
| Step | Action | Trigger Source | Expected (OS) [Doc A] | Expected (Plugin) [Doc C] | Actual Result | Notes | Result |
|
||||
| ---- | ------ | -------------- | ---------------------- | -------------------------- | ------------- | ----- | ------ |
|
||||
| 1 | Schedule alarm 2-5 minutes in future | Plugin | - | Alarm scheduled | ☐ | | ☐ |
|
||||
| 2 | Force kill via `adb shell am kill <package>` | User/OS | - | - | ☐ | | ☐ |
|
||||
| 3 | Wait for trigger time | OS | ✅ Alarm fires - [Doc A §2.1.1](./01-platform-capability-reference.md#211-alarms-survive-ui-kills-swipe-from-recents) | ✅ Notification displayed - [Doc C §1.1](./03-plugin-requirements.md#11-guarantees-by-platform) | ☐ | | ☐ |
|
||||
| 4 | Check logs | - | - | No errors | ☐ | | ☐ |
|
||||
|
||||
**Platform Behavior Reference**: [Doc A §2.1.1](./01-platform-capability-reference.md#211-alarms-survive-ui-kills-swipe-from-recents) - OS-guaranteed
|
||||
|
||||
---
|
||||
|
||||
#### Test 4: Device Reboot
|
||||
|
||||
**Preconditions**:
|
||||
- App installed and launched at least once
|
||||
- Alarm scheduled and verified in database
|
||||
- Boot receiver registered in manifest
|
||||
- Test device: [Device model, OS version]
|
||||
- App build: [Git commit hash or build number]
|
||||
|
||||
| Step | Action | Trigger Source | Expected (OS) [Doc A] | Expected (Plugin) [Doc C] | Actual Result | Notes | Result |
|
||||
| ---- | ------ | -------------- | ---------------------- | -------------------------- | ------------- | ----- | ------ |
|
||||
| 1 | Schedule alarm 10 minutes in future | Plugin | - | Alarm scheduled | ☐ | | ☐ |
|
||||
| 2 | Reboot device | User | - | - | ☐ | | ☐ |
|
||||
| 3 | Do NOT open app | - | ❌ Alarm does NOT fire - [Doc A §2.1.2](./01-platform-capability-reference.md#212-alarms-can-be-preserved-across-device-reboot) | ❌ No notification | ☐ | | ☐ |
|
||||
| 4 | Wait past scheduled time | - | ❌ No automatic firing | ❌ No notification | ☐ | | ☐ |
|
||||
| 5 | Open app manually | User | - | Plugin detects missed alarm - [Doc C §4.2](./03-plugin-requirements.md#42-detection-triggers) | ☐ | | ☐ |
|
||||
| 6 | Check missed alarm handling | Plugin | - | ✅ Missed alarm detected - [Doc C §4.3](./03-plugin-requirements.md#43-required-actions) | ☐ | | ☐ |
|
||||
| 7 | Check rescheduling | Plugin | - | ✅ Future alarms rescheduled - [Doc C §3.1.1](./03-plugin-requirements.md#311-boot-event-android-only) | ☐ | | ☐ |
|
||||
|
||||
**Code Reference**:
|
||||
- Boot receiver: `BootReceiver.kt` line 24
|
||||
- Rescheduling: `BootReceiver.kt` line 38+
|
||||
|
||||
**Platform Behavior Reference**: [Doc A §2.1.2](./01-platform-capability-reference.md#212-alarms-can-be-preserved-across-device-reboot) - Plugin-required
|
||||
|
||||
**Plugin Requirement Reference**: [Doc C §3.1.1](./03-plugin-requirements.md#311-boot-event-android-only) - Boot event recovery
|
||||
|
||||
---
|
||||
|
||||
#### Test 5: Android Force Stop
|
||||
|
||||
**Preconditions**:
|
||||
- App installed and launched at least once
|
||||
- Multiple alarms scheduled (past and future)
|
||||
- Test device: [Device model, OS version]
|
||||
- App build: [Git commit hash or build number]
|
||||
|
||||
| Step | Action | Trigger Source | Expected (OS) [Doc A] | Expected (Plugin) [Doc C] | Actual Result | Notes | Result |
|
||||
| ---- | ------ | -------------- | ---------------------- | -------------------------- | ------------- | ----- | ------ |
|
||||
| 1 | Schedule alarms (past and future) | Plugin | - | Alarms scheduled | ☐ | | ☐ |
|
||||
| 2 | Go to Settings → Apps → [App] → Force Stop | User | ❌ All alarms removed - [Doc A §2.2.1](./01-platform-capability-reference.md#221-you-cannot-survive-force-stop) | ❌ All alarms removed | ☐ | | ☐ |
|
||||
| 3 | Wait for trigger time | - | ❌ Alarm does NOT fire - [Doc A §2.2.1](./01-platform-capability-reference.md#221-you-cannot-survive-force-stop) | ❌ No notification | ☐ | | ☐ |
|
||||
| 4 | Open app again | User | - | Plugin detects force stop scenario - [Doc C §3.1.4](./03-plugin-requirements.md#314-force-stop-recovery-android-only) | ☐ | | ☐ |
|
||||
| 5 | Check recovery | Plugin | - | ✅ All past alarms marked as missed - [Doc C §3.1.4](./03-plugin-requirements.md#314-force-stop-recovery-android-only) | ☐ | | ☐ |
|
||||
| 6 | Check rescheduling | Plugin | - | ✅ All future alarms rescheduled - [Doc C §3.1.4](./03-plugin-requirements.md#314-force-stop-recovery-android-only) | ☐ | | ☐ |
|
||||
|
||||
**Platform Behavior Reference**: [Doc A §2.2.1](./01-platform-capability-reference.md#221-you-cannot-survive-force-stop) - Forbidden
|
||||
|
||||
**Plugin Requirement Reference**: [Doc C §3.1.4](./03-plugin-requirements.md#314-force-stop-recovery-android-only) - Force stop recovery
|
||||
|
||||
---
|
||||
|
||||
#### Test 6: Exact Alarm Permission (Android 12+)
|
||||
|
||||
**Preconditions**:
|
||||
- Android 12+ (API 31+) device
|
||||
- App installed and launched at least once
|
||||
- Test device: [Device model, OS version]
|
||||
- App build: [Git commit hash or build number]
|
||||
|
||||
| Step | Action | Trigger Source | Expected (OS) [Doc A] | Expected (Plugin) [Doc C] | Actual Result | Notes | Result |
|
||||
| ---- | ------ | -------------- | ---------------------- | -------------------------- | ------------- | ----- | ------ |
|
||||
| 1 | Revoke exact alarm permission | User | - | - | ☐ | | ☐ |
|
||||
| 2 | Attempt to schedule alarm | Plugin | - | Plugin requests permission - [Doc C §8.1.1](./03-plugin-requirements.md#811-permissions) | ☐ | | ☐ |
|
||||
| 3 | Check settings opened | Plugin | - | ✅ Settings opened | ☐ | | ☐ |
|
||||
| 4 | Grant permission | User | - | - | ☐ | | ☐ |
|
||||
| 5 | Schedule alarm | Plugin | - | ✅ Alarm scheduled | ☐ | | ☐ |
|
||||
| 6 | Verify alarm fires | OS | ✅ Alarm fires - [Doc A §5.2](./01-platform-capability-reference.md#52-android-s-exact-alarm-permission-decision-tree) | ✅ Notification displayed | ☐ | | ☐ |
|
||||
|
||||
**Code Reference**: `DailyNotificationPlugin.kt` line 1309, 1314-1324
|
||||
|
||||
**Platform Behavior Reference**: [Doc A §5.2](./01-platform-capability-reference.md#52-android-s-exact-alarm-permission-decision-tree) - Conditional
|
||||
|
||||
**Plugin Requirement Reference**: [Doc C §8.1.1](./03-plugin-requirements.md#811-permissions) - Permission handling
|
||||
|
||||
---
|
||||
|
||||
### 1.3 Persistence Investigation
|
||||
|
||||
| Item | Expected | Actual | Code Reference | Notes |
|
||||
| ---- | -------- | ------ | -------------- | ----- |
|
||||
| Alarm ID stored | ✅ Yes | ☐ | `DailyNotificationPlugin.kt` line 1393+ | |
|
||||
| Trigger time stored | ✅ Yes | ☐ | Room database | |
|
||||
| Repeat rule stored | ✅ Yes | ☐ | Schedule entity | |
|
||||
| Channel/priority stored | ✅ Yes | ☐ | NotificationContentEntity | |
|
||||
| Payload stored | ✅ Yes | ☐ | ContentCache | |
|
||||
| Time created/modified | ✅ Yes | ☐ | Entity timestamps | |
|
||||
|
||||
**Storage Location**: Room database (`DailyNotificationDatabase`)
|
||||
|
||||
---
|
||||
|
||||
### 1.4 Recovery Points Investigation
|
||||
|
||||
| Recovery Point | Expected Behavior | Actual Behavior | Code Reference | Notes |
|
||||
| -------------- | ----------------- | --------------- | -------------- | ----- |
|
||||
| Boot event | ✅ Reschedule all alarms | ☐ | `BootReceiver.kt` line 24 | |
|
||||
| App cold start | ✅ Detect missed alarms | ☐ | Check plugin initialization | |
|
||||
| App warm start | ✅ Verify active alarms | ☐ | Check plugin initialization | |
|
||||
| Background fetch return | ⚠️ May reschedule | ☐ | `FetchWorker.kt` | |
|
||||
| User taps notification | ✅ Launch app | ☐ | Notification intent | |
|
||||
|
||||
---
|
||||
|
||||
## 2. Required Baseline Scenarios
|
||||
|
||||
**All six baseline scenarios MUST be tested**:
|
||||
|
||||
1. ✅ **Swipe-kill** - Test 2 (Android), Test 2 (iOS)
|
||||
2. ✅ **OS low-RAM kill** - Test 3 (Android)
|
||||
3. ✅ **Reboot** - Test 4 (Android), Test 3 (iOS)
|
||||
4. ✅ **Force stop** - Test 5 (Android only)
|
||||
5. ✅ **Cold start** - Test 4 Step 5 (Android), Test 4 (iOS)
|
||||
6. ✅ **Notification-tap resume** - Recovery Points §1.4 (Both)
|
||||
|
||||
---
|
||||
|
||||
## 3. iOS Exploration
|
||||
|
||||
### 3.1 Code-Level Inspection Checklist
|
||||
|
||||
**Source Locations**:
|
||||
- Plugin: `ios/Plugin/`
|
||||
- Test App: `test-apps/ios-test-app/`
|
||||
- Alternative: Check `ios-2` branch
|
||||
|
||||
| Task | File/Function | Line | Status | Notes |
|
||||
| ---- | ------------- | ---- | ------ | ----- |
|
||||
| Locate main plugin class | `DailyNotificationPlugin.swift` | 506 | ☐ | `scheduleUserNotification()` |
|
||||
| Identify notification scheduling | `DailyNotificationScheduler.swift` | 133 | ☐ | `scheduleNotification()` |
|
||||
| Check UNUserNotificationCenter usage | `DailyNotificationScheduler.swift` | 185 | ☐ | `notificationCenter.add()` |
|
||||
| Check trigger types | `DailyNotificationScheduler.swift` | 172 | ☐ | `UNCalendarNotificationTrigger` |
|
||||
| Check BGTaskScheduler usage | `DailyNotificationPlugin.swift` | 495 | ☐ | `scheduleBackgroundFetch()` |
|
||||
| Check persistence | `DailyNotificationPlugin.swift` | 35 | ☐ | `storage: DailyNotificationStorage?` |
|
||||
| Check app launch recovery | `DailyNotificationPlugin.swift` | 42 | ☐ | `load()` method |
|
||||
|
||||
### 3.2 Behavior Testing Matrix
|
||||
|
||||
#### Test 1: Base Case
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule notification 2-5 minutes in future | - | Notification scheduled | ☐ | |
|
||||
| 2 | Leave app backgrounded | - | - | ☐ | |
|
||||
| 3 | Wait for trigger time | ✅ Notification fires | ✅ Notification displayed | ☐ | |
|
||||
| 4 | Check logs | - | No errors | ☐ | |
|
||||
|
||||
**Code Reference**: `DailyNotificationScheduler.scheduleNotification()` line 133
|
||||
|
||||
**Platform Behavior**: See [Platform Reference §3.1.1](./01-platform-capability-reference.md#311-notifications-survive-app-termination)
|
||||
|
||||
---
|
||||
|
||||
#### Test 2: Swipe App Away
|
||||
|
||||
**Preconditions**:
|
||||
- App installed and launched at least once
|
||||
- Notification scheduled and verified
|
||||
- Test device: [Device model, OS version]
|
||||
- App build: [Git commit hash or build number]
|
||||
|
||||
| Step | Action | Trigger Source | Expected (OS) [Doc A] | Expected (Plugin) [Doc C] | Actual Result | Notes | Result |
|
||||
| ---- | ------ | -------------- | ---------------------- | -------------------------- | ------------- | ----- | ------ |
|
||||
| 1 | Schedule notification 2-5 minutes in future | Plugin | - | Notification scheduled | ☐ | | ☐ |
|
||||
| 2 | Swipe app away from app switcher | User | - | - | ☐ | | ☐ |
|
||||
| 3 | Wait for trigger time | OS | ✅ Notification fires (OS handles) - [Doc A §3.1.1](./01-platform-capability-reference.md#311-notifications-survive-app-termination) | ✅ Notification displayed - [Doc C §1.1](./03-plugin-requirements.md#11-guarantees-by-platform) | ☐ | | ☐ |
|
||||
| 4 | Check app state | OS | App terminated | App not running | ☐ | | ☐ |
|
||||
|
||||
**Platform Behavior Reference**: [Doc A §3.1.1](./01-platform-capability-reference.md#311-notifications-survive-app-termination) - OS-guaranteed
|
||||
|
||||
---
|
||||
|
||||
#### Test 3: Device Reboot
|
||||
|
||||
**Preconditions**:
|
||||
- App installed and launched at least once
|
||||
- Notification scheduled with calendar/time trigger
|
||||
- Test device: [Device model, OS version]
|
||||
- App build: [Git commit hash or build number]
|
||||
|
||||
| Step | Action | Trigger Source | Expected (OS) [Doc A] | Expected (Plugin) [Doc C] | Actual Result | Notes | Result |
|
||||
| ---- | ------ | -------------- | ---------------------- | -------------------------- | ------------- | ----- | ------ |
|
||||
| 1 | Schedule notification for future time | Plugin | - | Notification scheduled | ☐ | | ☐ |
|
||||
| 2 | Reboot device | User | - | - | ☐ | | ☐ |
|
||||
| 3 | Do NOT open app | OS | ✅ Notification fires (OS persists) - [Doc A §3.1.2](./01-platform-capability-reference.md#312-notifications-persist-across-device-reboot) | ✅ Notification displayed - [Doc C §1.1](./03-plugin-requirements.md#11-guarantees-by-platform) | ☐ | | ☐ |
|
||||
| 4 | Check notification timing | OS | ✅ On time (±180s tolerance) - [Doc A §6.1](./01-platform-capability-reference.md#61-notification-timing-accuracy) | ✅ On time | ☐ | | ☐ |
|
||||
|
||||
**Platform Behavior Reference**: [Doc A §3.1.2](./01-platform-capability-reference.md#312-notifications-persist-across-device-reboot) - OS-guaranteed
|
||||
|
||||
**Note**: Only calendar and time-based triggers persist. Location triggers do not - See [Doc A §3.1.2](./01-platform-capability-reference.md#312-notifications-persist-across-device-reboot)
|
||||
|
||||
---
|
||||
|
||||
#### Test 4: Hard Termination & Relaunch
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule repeating notifications | - | Notifications scheduled | ☐ | |
|
||||
| 2 | Terminate app via Xcode/switcher | - | - | ☐ | |
|
||||
| 3 | Allow some triggers to occur | ✅ Notifications fire | ✅ Notifications displayed | ☐ | |
|
||||
| 4 | Reopen app | - | Plugin checks for missed events | ☐ | |
|
||||
| 5 | Check missed event detection | ⚠️ May detect | ☐ | Plugin-specific |
|
||||
| 6 | Check state recovery | ⚠️ May recover | ☐ | Plugin-specific |
|
||||
|
||||
**Platform Behavior**: OS-guaranteed for notifications; Plugin-guaranteed for missed event detection
|
||||
|
||||
---
|
||||
|
||||
#### Test 5: Background Execution Limits
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule BGTaskScheduler task | - | Task scheduled | ☐ | |
|
||||
| 2 | Wait for system to execute | ⚠️ System-controlled | ⚠️ May not execute | ☐ | |
|
||||
| 3 | Check execution timing | ⚠️ Not guaranteed | ⚠️ Not guaranteed | ☐ | |
|
||||
| 4 | Check time budget | ⚠️ ~30 seconds | ⚠️ Limited time | ☐ | |
|
||||
|
||||
**Code Reference**: `DailyNotificationPlugin.scheduleBackgroundFetch()` line 495
|
||||
|
||||
**Platform Behavior**: Conditional (see [Platform Reference §3.1.3](./01-platform-capability-reference.md#313-background-tasks-for-prefetching))
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Persistence Investigation
|
||||
|
||||
| Item | Expected | Actual | Code Reference | Notes |
|
||||
| ---- | -------- | ------ | -------------- | ----- |
|
||||
| Notification ID stored | ✅ Yes (in UNUserNotificationCenter) | ☐ | `UNNotificationRequest` | |
|
||||
| Plugin-side storage | ⚠️ May not exist | ☐ | `DailyNotificationStorage?` | |
|
||||
| Trigger time stored | ✅ Yes (in trigger) | ☐ | `UNCalendarNotificationTrigger` | |
|
||||
| Repeat rule stored | ✅ Yes (in trigger) | ☐ | `repeats: true/false` | |
|
||||
| Payload stored | ✅ Yes (in userInfo) | ☐ | `notificationContent.userInfo` | |
|
||||
|
||||
**Storage Location**:
|
||||
- Primary: UNUserNotificationCenter (OS-managed)
|
||||
- Secondary: Plugin storage (if implemented)
|
||||
|
||||
---
|
||||
|
||||
### 3.4 Recovery Points Investigation
|
||||
|
||||
| Recovery Point | Expected Behavior | Actual Behavior | Code Reference | Notes |
|
||||
| -------------- | ----------------- | --------------- | -------------- | ----- |
|
||||
| Boot event | ✅ Notifications fire automatically | ☐ | OS handles | |
|
||||
| App cold start | ⚠️ May detect missed notifications | ☐ | Check `load()` method | |
|
||||
| App warm start | ⚠️ May verify pending notifications | ☐ | Check plugin initialization | |
|
||||
| Background fetch | ⚠️ May reschedule | ☐ | `BGTaskScheduler` | |
|
||||
| User taps notification | ✅ App launched | ☐ | Notification action | |
|
||||
|
||||
---
|
||||
|
||||
## 4. Cross-Platform Comparison
|
||||
|
||||
### 3.1 Observed Behavior Summary
|
||||
|
||||
| Scenario | Android (Observed) | iOS (Observed) | Platform Difference |
|
||||
| -------- | ------------------ | -------------- | ------------------- |
|
||||
| Swipe/termination | ☐ | ☐ | Both should work |
|
||||
| Reboot | ☐ | ☐ | iOS auto, Android manual |
|
||||
| Force stop | ☐ | N/A | Android only |
|
||||
| App code on trigger | ☐ | ☐ | Android yes, iOS no |
|
||||
| Background execution | ☐ | ☐ | Android more flexible |
|
||||
|
||||
---
|
||||
|
||||
## 5. Findings & Gaps
|
||||
|
||||
### 4.1 Android Gaps
|
||||
|
||||
| Gap | Severity | Description | Recommendation |
|
||||
| --- | -------- | ----------- | -------------- |
|
||||
| Boot recovery | ☐ Critical/Major/Minor/Expected | Does plugin reschedule on boot? | Implement if missing |
|
||||
| Missed alarm detection | ☐ Critical/Major/Minor/Expected | Does plugin detect missed alarms? | Implement if missing |
|
||||
| Force stop recovery | ☐ Critical/Major/Minor/Expected | Does plugin recover after force stop? | Implement if missing |
|
||||
| Persistence completeness | ☐ Critical/Major/Minor/Expected | Are all required fields persisted? | Verify and add if missing |
|
||||
|
||||
**Severity Classification**:
|
||||
- **Critical**: Breaks plugin guarantee (see [Doc C §1.1](./03-plugin-requirements.md#11-guarantees-by-platform))
|
||||
- **Major**: Unexpected but recoverable (plugin works but behavior differs from expected)
|
||||
- **Minor**: Non-blocking deviation (cosmetic or edge case)
|
||||
- **Expected**: Platform limitation (documented in [Doc A](./01-platform-capability-reference.md))
|
||||
|
||||
### 4.2 iOS Gaps
|
||||
|
||||
| Gap | Severity | Description | Recommendation |
|
||||
| --- | -------- | ----------- | -------------- |
|
||||
| Missed notification detection | ☐ Critical/Major/Minor/Expected | Does plugin detect missed notifications? | Implement if missing |
|
||||
| Plugin-side persistence | ☐ Critical/Major/Minor/Expected | Does plugin persist state separately? | Consider if needed |
|
||||
| Background task reliability | ☐ Critical/Major/Minor/Expected | Can plugin rely on BGTaskScheduler? | Document limitations |
|
||||
|
||||
**Severity Classification**: Same as Android (see above).
|
||||
|
||||
---
|
||||
|
||||
## 6. Deliverables from This Exploration
|
||||
|
||||
After completing this exploration, generate:
|
||||
|
||||
1. **Completed test results** - All checkboxes filled, actual results documented
|
||||
2. **Gap analysis** - Documented limitations and gaps
|
||||
3. **Annotated code pointers** - Code locations with findings
|
||||
4. **Open Questions / TODOs** - Unresolved issues
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Platform Capability Reference](./01-platform-capability-reference.md) - OS-level facts
|
||||
- [Plugin Requirements](./03-plugin-requirements.md) - Requirements based on findings
|
||||
- [Unified Alarm Directive](./000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document
|
||||
|
||||
---
|
||||
|
||||
## Notes for Explorers
|
||||
|
||||
* Fill in checkboxes (☐) as you complete each test
|
||||
* Document actual results in "Actual Result" columns
|
||||
* Add notes for any unexpected behavior
|
||||
* Reference code locations when documenting findings
|
||||
* Update "Findings & Gaps" section as you discover issues
|
||||
* Use platform capability reference to understand expected OS behavior
|
||||
* Link to Platform Reference sections instead of duplicating platform facts
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,319 +0,0 @@
|
||||
# Activation Guide: How to Use the Alarm Directive System
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Activation Guide
|
||||
**Version**: 1.0.0
|
||||
|
||||
## Purpose
|
||||
|
||||
This guide explains how to **activate and use** the unified alarm directive system for implementation work. It provides step-by-step instructions for developers to follow the documentation workflow.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites Check
|
||||
|
||||
**Before starting any implementation work**, verify these conditions are met:
|
||||
|
||||
### ✅ Documentation Status
|
||||
|
||||
Check [Unified Directive §11 - Status Matrix](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix):
|
||||
|
||||
- [x] **Doc A** (Platform Facts) - ✅ Drafted, ✅ Cleaned, ✅ In Use
|
||||
- [x] **Doc B** (Exploration) - ✅ Drafted, ✅ Cleaned, ✅ In Use (drives emulator test harness)
|
||||
- [x] **Doc C** (Requirements) - ✅ Drafted, ✅ Cleaned, ✅ In Use
|
||||
- [x] **Phase 1** (Cold Start) - ✅ Drafted, ✅ Cleaned, ✅ In Use (implemented in plugin v1.1.0, emulator-verified via `test-phase1.sh`)
|
||||
- [x] **Phase 2** (Force Stop) - ✅ Drafted, ✅ Implemented, ☐ Emulator-tested (`test-phase2.sh` + `PHASE2-EMULATOR-TESTING.md`)
|
||||
- [x] **Phase 3** (Boot Recovery) - ✅ Drafted, ✅ Implemented, ☐ Emulator-tested (`test-phase3.sh` + `PHASE3-EMULATOR-TESTING.md`)
|
||||
|
||||
**Status**: ✅ **All prerequisites met** – Phase 1 implementation is complete and emulator-verified; Phase 2 and Phase 3 are implemented and ready for emulator testing; ready for broader device testing and rollout.
|
||||
|
||||
---
|
||||
|
||||
## Activation Workflow
|
||||
|
||||
### Step 1: Choose Your Starting Point
|
||||
|
||||
**For New Implementation Work**:
|
||||
- Start with **Phase 1** (Cold Start Recovery) - See [Phase 1 Directive](../android-implementation-directive-phase1.md)
|
||||
- This is the minimal viable recovery that unblocks other work
|
||||
|
||||
**For Testing/Exploration**:
|
||||
- Start with **Doc B** (Exploration) - See [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md)
|
||||
- Fill in test scenarios as you validate current behavior
|
||||
|
||||
**For Understanding Requirements**:
|
||||
- Start with **Doc C** (Requirements) - See [Plugin Requirements](./03-plugin-requirements.md)
|
||||
- Review guarantees, limitations, and API contract
|
||||
|
||||
---
|
||||
|
||||
## Implementation Activation: Phase 1
|
||||
|
||||
### 1.1 Read the Phase Directive
|
||||
|
||||
**Start Here**: [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md)
|
||||
|
||||
**Key Sections to Read**:
|
||||
1. **Purpose** (§0) - Understand what Phase 1 implements
|
||||
2. **Acceptance Criteria** (§1) - Definition of done
|
||||
3. **Implementation** (§2) - Step-by-step code changes
|
||||
4. **Testing Requirements** (§8) - How to validate
|
||||
|
||||
### 1.2 Reference Supporting Documents
|
||||
|
||||
**During Implementation, Keep These Open**:
|
||||
|
||||
1. **Doc A** - [Platform Capability Reference](./01-platform-capability-reference.md)
|
||||
- Use for: Understanding OS behavior, API constraints, permissions
|
||||
- Example: "Can I rely on AlarmManager to persist alarms?" → See Doc A §2.1.1
|
||||
|
||||
2. **Doc C** - [Plugin Requirements](./03-plugin-requirements.md)
|
||||
- Use for: Understanding what the plugin MUST guarantee
|
||||
- Example: "What should happen on cold start?" → See Doc C §3.1.2
|
||||
|
||||
3. **Doc B** - [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md)
|
||||
- Use for: Test scenarios to validate your implementation
|
||||
- Example: "How do I test cold start recovery?" → See Doc B Test 4
|
||||
|
||||
### 1.3 Follow the Implementation Steps
|
||||
|
||||
**Phase 1 Implementation Checklist** (from Phase 1 directive):
|
||||
|
||||
- [ ] Create `ReactivationManager.kt` file
|
||||
- [ ] Implement `detectMissedNotifications()` method
|
||||
- [ ] Implement `markMissedNotifications()` method
|
||||
- [ ] Implement `verifyAndRescheduleFutureAlarms()` method
|
||||
- [ ] Integrate into `DailyNotificationPlugin.load()`
|
||||
- [ ] Add logging and error handling
|
||||
- [ ] Write unit tests
|
||||
- [ ] Test on physical device
|
||||
|
||||
**Reference**: See [Phase 1 §2 - Implementation](../android-implementation-directive-phase1.md#2-implementation)
|
||||
|
||||
---
|
||||
|
||||
## Testing Activation: Doc B
|
||||
|
||||
### 2.1 Execute Test Scenarios
|
||||
|
||||
**Start Here**: [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md)
|
||||
|
||||
**Workflow**:
|
||||
1. Choose a test scenario (e.g., "Test 4: Device Reboot")
|
||||
2. Follow the **Steps** column exactly
|
||||
3. Fill in **Actual Result** column with observed behavior
|
||||
4. Mark **Result** column (Pass/Fail)
|
||||
5. Add **Notes** for any unexpected behavior
|
||||
|
||||
### 2.2 Update Test Results
|
||||
|
||||
**As You Test**:
|
||||
- Update checkboxes (☐ → ✅) when tests pass
|
||||
- Document actual vs expected differences
|
||||
- Add findings to "Findings & Gaps" section (§4)
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
| Step | Action | Expected | Actual Result | Notes | Result |
|
||||
| ---- | ------ | -------- | ------------- | ----- | ------ |
|
||||
| 5 | Launch app | Plugin detects missed alarm | ✅ Missed alarm detected | Logs show "DNP-REACTIVATION: Detected 1 missed alarm" | ✅ Pass |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Maintenance During Work
|
||||
|
||||
### 3.1 Update Status Matrix
|
||||
|
||||
**When You Complete Work**:
|
||||
|
||||
1. Open [Unified Directive §11](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix)
|
||||
2. Update the relevant row:
|
||||
- Mark "In Use?" = ✅ when implementation is deployed
|
||||
- Update "Notes" with completion status
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
| P1 | `../android-implementation-directive-phase1.md` | Impl – Cold start | ✅ | ✅ | ✅ | **Implemented and deployed** - See commit abc123 |
|
||||
```
|
||||
|
||||
### 3.2 Update Doc B with Test Results
|
||||
|
||||
**After Testing**:
|
||||
- Fill in actual results in test matrices
|
||||
- Document any gaps or unexpected behavior
|
||||
- Update severity classifications if issues found
|
||||
|
||||
### 3.3 Follow Change Control Rules
|
||||
|
||||
**When Modifying Docs A, B, or C**:
|
||||
|
||||
1. **Update version header** in the document
|
||||
2. **Update status matrix** (Section 11) in unified directive
|
||||
3. **Use commit message tag**: `[ALARM-DOCS]` prefix
|
||||
4. **Notify in CHANGELOG** if JS/TS-visible behavior changes
|
||||
|
||||
**Reference**: See [Unified Directive §10 - Change Control](./000-UNIFIED-ALARM-DIRECTIVE.md#10-change-control-rules)
|
||||
|
||||
---
|
||||
|
||||
## Workflow Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. Read Phase Directive (P1/P2/P3) │
|
||||
│ Understand acceptance criteria │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 2. Reference Doc A (Platform Facts) │
|
||||
│ Understand OS constraints │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 3. Reference Doc C (Requirements) │
|
||||
│ Understand plugin guarantees │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 4. Implement Code (Phase Directive) │
|
||||
│ Follow step-by-step instructions │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 5. Test (Doc B Scenarios) │
|
||||
│ Execute test matrices │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 6. Update Documentation │
|
||||
│ - Status matrix │
|
||||
│ - Test results (Doc B) │
|
||||
│ - Version numbers │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Activation Scenarios
|
||||
|
||||
### Scenario 1: Starting Phase 1 Implementation
|
||||
|
||||
**Steps**:
|
||||
1. ✅ Verify prerequisites (all docs exist - **DONE**)
|
||||
2. Read [Phase 1 Directive](../android-implementation-directive-phase1.md) §1 (Acceptance Criteria)
|
||||
3. Read [Doc C §3.1.2](./03-plugin-requirements.md#312-app-cold-start) (Cold Start Requirements)
|
||||
4. Read [Doc A §2.1.4](./01-platform-capability-reference.md#214-alarms-can-be-restored-after-app-restart) (Platform Capability)
|
||||
5. Follow [Phase 1 §2](../android-implementation-directive-phase1.md#2-implementation) (Implementation Steps)
|
||||
6. Test using [Doc B Test 4](./02-plugin-behavior-exploration.md#test-4-device-reboot) (Cold Start Scenario)
|
||||
7. Update status matrix when complete
|
||||
|
||||
### Scenario 2: Testing Current Behavior
|
||||
|
||||
**Steps**:
|
||||
1. Open [Doc B](./02-plugin-behavior-exploration.md)
|
||||
2. Choose a test scenario (e.g., "Test 2: Swipe from Recents")
|
||||
3. Follow the **Steps** column
|
||||
4. Fill in **Actual Result** column
|
||||
5. Compare with **Expected (OS)** and **Expected (Plugin)** columns
|
||||
6. Document findings in **Notes** column
|
||||
7. Update "Findings & Gaps" section if issues found
|
||||
|
||||
### Scenario 3: Understanding a Requirement
|
||||
|
||||
**Steps**:
|
||||
1. Open [Doc C](./03-plugin-requirements.md)
|
||||
2. Find the relevant section (e.g., "Missed Alarm Handling" §4)
|
||||
3. Read the requirement and acceptance criteria
|
||||
4. Follow cross-references to:
|
||||
- **Doc A** for platform constraints
|
||||
- **Doc B** for test scenarios
|
||||
- **Phase docs** for implementation details
|
||||
|
||||
### Scenario 4: Adding iOS Support
|
||||
|
||||
**Steps**:
|
||||
1. ✅ Verify iOS parity milestone conditions (see [Unified Directive §9](./000-UNIFIED-ALARM-DIRECTIVE.md#9-next-steps))
|
||||
2. Ensure Doc A has iOS matrix complete
|
||||
3. Ensure Doc C has iOS guarantees defined
|
||||
4. Create iOS implementation following Android phase patterns
|
||||
5. Test using Doc B iOS scenarios
|
||||
6. Update status matrix
|
||||
|
||||
---
|
||||
|
||||
## Blocking Rules
|
||||
|
||||
**⚠️ DO NOT PROCEED** if:
|
||||
|
||||
1. **Prerequisites not met** - See [Unified Directive §12](./000-UNIFIED-ALARM-DIRECTIVE.md#12-single-instruction-for-team)
|
||||
- Doc A, B, C must exist
|
||||
- Status matrix must be updated
|
||||
- Deprecated files must be marked
|
||||
|
||||
2. **iOS work without parity milestone** - See [Unified Directive §9](./000-UNIFIED-ALARM-DIRECTIVE.md#9-next-steps)
|
||||
- Doc A must have iOS matrix
|
||||
- Doc C must define iOS guarantees
|
||||
- Phase docs must not assume Android-only
|
||||
|
||||
3. **Phase 2/3 without Phase 1** - See Phase directives
|
||||
- Phase 2 requires Phase 1 complete
|
||||
- Phase 3 requires Phase 1 & 2 complete
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Document Roles
|
||||
|
||||
| Doc | Purpose | When to Use |
|
||||
|-----|---------|-------------|
|
||||
| **Unified Directive** | Master coordination | Understanding system structure, change control |
|
||||
| **Doc A** | Platform facts | Understanding OS behavior, API constraints |
|
||||
| **Doc B** | Test scenarios | Testing, exploration, validation |
|
||||
| **Doc C** | Requirements | Understanding guarantees, API contract |
|
||||
| **Phase 1-3** | Implementation | Writing code, step-by-step instructions |
|
||||
|
||||
### Key Sections
|
||||
|
||||
- **Status Matrix**: [Unified Directive §11](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix)
|
||||
- **Change Control**: [Unified Directive §10](./000-UNIFIED-ALARM-DIRECTIVE.md#10-change-control-rules)
|
||||
- **Phase 1 Start**: [Phase 1 Directive](../android-implementation-directive-phase1.md)
|
||||
- **Test Scenarios**: [Doc B Test Matrices](./02-plugin-behavior-exploration.md#12-behavior-testing-matrix)
|
||||
- **Requirements**: [Doc C Guarantees](./03-plugin-requirements.md#1-plugin-behavior-guarantees--limitations)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
**You're Ready To**:
|
||||
|
||||
1. ✅ **Start Phase 1 Implementation** - All prerequisites met
|
||||
2. ✅ **Begin Testing** - Doc B scenarios ready
|
||||
3. ✅ **Reference Documentation** - All docs complete and cross-referenced
|
||||
|
||||
**Recommended First Action**:
|
||||
- Read [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md) §1 (Acceptance Criteria)
|
||||
- Then proceed to §2 (Implementation) when ready to code
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Unified Alarm Directive](./000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document
|
||||
- [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md) - Start here for implementation
|
||||
- [Plugin Requirements](./03-plugin-requirements.md) - What the plugin must guarantee
|
||||
- [Platform Capability Reference](./01-platform-capability-reference.md) - OS-level facts
|
||||
- [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md) - Test scenarios
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for activation
|
||||
**Last Updated**: November 2025
|
||||
|
||||
@@ -1,686 +0,0 @@
|
||||
# Phase 1 Emulator Testing Guide
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Testing Guide
|
||||
**Version**: 1.0.0
|
||||
|
||||
## Purpose
|
||||
|
||||
This guide provides step-by-step instructions for testing Phase 1 (Cold Start Recovery) implementation on an Android emulator. All Phase 1 tests can be run entirely on an emulator using ADB commands.
|
||||
|
||||
---
|
||||
|
||||
## Latest Known Good Run (Emulator)
|
||||
|
||||
**Environment**
|
||||
|
||||
- Device: Android Emulator – Pixel 8 API 34
|
||||
- App ID: `com.timesafari.dailynotification`
|
||||
- Build: Debug APK from `test-apps/android-test-app`
|
||||
- Script: `./test-phase1.sh`
|
||||
- Date: 27 November 2025
|
||||
|
||||
**Observed Results**
|
||||
|
||||
- ✅ TEST 1: Cold Start Missed Detection
|
||||
- Logs show:
|
||||
- `Marked missed notification: daily_<id>`
|
||||
- `Cold start recovery complete: missed=1, rescheduled=0, verified=0, errors=0`
|
||||
- "Stored notification content in database" present in logs
|
||||
- Alarm present in `dumpsys alarm` before kill
|
||||
|
||||
- ✅ TEST 2: Future Alarm Verification / Rescheduling
|
||||
- Logs show:
|
||||
- `Rescheduled alarm: daily_<id> for <time>`
|
||||
- `Rescheduled missing alarm: daily_<id> at <time>`
|
||||
- `Cold start recovery complete: missed=1, rescheduled=1, verified=0, errors=0`
|
||||
- Script output:
|
||||
- `✅ TEST 2 PASSED: Missing future alarms were detected and rescheduled (rescheduled=1)!`
|
||||
|
||||
- ✅ TEST 3: Recovery Timeout
|
||||
- Timeout protection confirmed at **2 seconds**
|
||||
- No blocking of app startup
|
||||
|
||||
- ✅ TEST 4: Invalid Data Handling
|
||||
- Confirmed in code review:
|
||||
- Reactivation code safely skips invalid IDs
|
||||
- Errors are logged but do not crash recovery
|
||||
|
||||
**Conclusion:**
|
||||
Phase 1 cold-start recovery behavior is **successfully verified on emulator** using `test-phase1.sh`. This run is the reference baseline for future regressions.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Software
|
||||
|
||||
- **Android SDK** with command line tools
|
||||
- **Android Emulator** (`emulator` command)
|
||||
- **ADB** (Android Debug Bridge)
|
||||
- **Gradle** (via Gradle Wrapper)
|
||||
- **Java** (JDK 11+)
|
||||
|
||||
### Emulator Setup
|
||||
|
||||
1. **List available emulators**:
|
||||
```bash
|
||||
emulator -list-avds
|
||||
```
|
||||
|
||||
2. **Start emulator** (choose one):
|
||||
```bash
|
||||
# Start in background (recommended)
|
||||
emulator -avd Pixel8_API34 -no-snapshot-load &
|
||||
|
||||
# Or start in foreground
|
||||
emulator -avd Pixel8_API34
|
||||
```
|
||||
|
||||
3. **Wait for emulator to boot**:
|
||||
```bash
|
||||
adb wait-for-device
|
||||
adb shell getprop sys.boot_completed
|
||||
# Wait until returns "1"
|
||||
```
|
||||
|
||||
4. **Verify emulator is connected**:
|
||||
```bash
|
||||
adb devices
|
||||
# Should show: emulator-5554 device
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build and Install Test App
|
||||
|
||||
### Option 1: Android Test App (Simpler)
|
||||
|
||||
```bash
|
||||
# Navigate to test app directory
|
||||
cd test-apps/android-test-app
|
||||
|
||||
# Build debug APK (builds plugin automatically)
|
||||
./gradlew assembleDebug
|
||||
|
||||
# Install on emulator
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
|
||||
# Verify installation
|
||||
adb shell pm list packages | grep timesafari
|
||||
# Should show: package:com.timesafari.dailynotification
|
||||
```
|
||||
|
||||
### Option 2: Vue Test App (More Features)
|
||||
|
||||
```bash
|
||||
# Navigate to Vue test app
|
||||
cd test-apps/daily-notification-test
|
||||
|
||||
# Build Vue app
|
||||
npm run build
|
||||
|
||||
# Sync with Capacitor
|
||||
npx cap sync android
|
||||
|
||||
# Build Android APK
|
||||
cd android
|
||||
./gradlew assembleDebug
|
||||
|
||||
# Install on emulator
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Setup
|
||||
|
||||
### 1. Clear Logs Before Testing
|
||||
|
||||
```bash
|
||||
# Clear logcat buffer
|
||||
adb logcat -c
|
||||
```
|
||||
|
||||
### 2. Monitor Logs in Separate Terminal
|
||||
|
||||
**Keep this running in a separate terminal window**:
|
||||
|
||||
```bash
|
||||
# Monitor all plugin-related logs
|
||||
adb logcat | grep -E "DNP-REACTIVATION|DNP-PLUGIN|DNP-NOTIFY|DailyNotification"
|
||||
|
||||
# Or monitor just recovery logs
|
||||
adb logcat -s DNP-REACTIVATION
|
||||
|
||||
# Or save logs to file
|
||||
adb logcat -s DNP-REACTIVATION > recovery_test.log
|
||||
```
|
||||
|
||||
### 3. Launch App Once (Initial Setup)
|
||||
|
||||
```bash
|
||||
# Launch app to initialize database
|
||||
adb shell am start -n com.timesafari.dailynotification/.MainActivity
|
||||
|
||||
# Wait a few seconds for initialization
|
||||
sleep 3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test 1: Cold Start Missed Detection
|
||||
|
||||
**Purpose**: Verify missed notifications are detected and marked.
|
||||
|
||||
### Steps
|
||||
|
||||
```bash
|
||||
# 1. Clear logs
|
||||
adb logcat -c
|
||||
|
||||
# 2. Launch app
|
||||
adb shell am start -n com.timesafari.dailynotification/.MainActivity
|
||||
|
||||
# 3. Schedule notification for 2 minutes in future
|
||||
# (Use app UI or API - see "Scheduling Notifications" below)
|
||||
|
||||
# 4. Wait for app to schedule (check logs)
|
||||
adb logcat -d | grep "DN|SCHEDULE\|DN|ALARM"
|
||||
# Should show alarm scheduled
|
||||
|
||||
# 5. Verify alarm is scheduled
|
||||
adb shell dumpsys alarm | grep -i timesafari
|
||||
# Should show scheduled alarm
|
||||
|
||||
# 6. Kill app process (simulates OS kill, NOT force stop)
|
||||
adb shell am kill com.timesafari.dailynotification
|
||||
|
||||
# 7. Verify app is killed
|
||||
adb shell ps | grep timesafari
|
||||
# Should return nothing
|
||||
|
||||
# 8. Wait 5 minutes (past scheduled time)
|
||||
# Use: sleep 300 (or wait manually)
|
||||
# Or: Set system time forward (see "Time Manipulation" below)
|
||||
|
||||
# 9. Launch app (cold start)
|
||||
adb shell am start -n com.timesafari.dailynotification/.MainActivity
|
||||
|
||||
# 10. Check recovery logs immediately
|
||||
adb logcat -d | grep DNP-REACTIVATION
|
||||
```
|
||||
|
||||
### Expected Log Output
|
||||
|
||||
```
|
||||
DNP-REACTIVATION: Starting app launch recovery (Phase 1: cold start only)
|
||||
DNP-REACTIVATION: Cold start recovery: checking for missed notifications
|
||||
DNP-REACTIVATION: Marked missed notification: <id>
|
||||
DNP-REACTIVATION: Cold start recovery complete: missed=1, rescheduled=0, verified=0, errors=0
|
||||
DNP-REACTIVATION: App launch recovery completed: missed=1, rescheduled=0, verified=0, errors=0
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
# Check database (requires root or debug build)
|
||||
adb shell run-as com.timesafari.dailynotification sqlite3 databases/daily_notification_plugin.db \
|
||||
"SELECT id, delivery_status, scheduled_time FROM notification_content WHERE delivery_status = 'missed';"
|
||||
|
||||
# Or check history table
|
||||
adb shell run-as com.timesafari.dailynotification sqlite3 databases/daily_notification_plugin.db \
|
||||
"SELECT * FROM history WHERE kind = 'recovery' ORDER BY occurredAt DESC LIMIT 1;"
|
||||
```
|
||||
|
||||
### Pass Criteria
|
||||
|
||||
- ✅ Log shows "Cold start recovery: checking for missed notifications"
|
||||
- ✅ Log shows "Marked missed notification: <id>"
|
||||
- ✅ Database shows `delivery_status = 'missed'`
|
||||
- ✅ History table has recovery entry
|
||||
|
||||
---
|
||||
|
||||
## Test 2: Future Alarm Rescheduling
|
||||
|
||||
**Purpose**: Verify missing future alarms are rescheduled.
|
||||
|
||||
### Steps
|
||||
|
||||
```bash
|
||||
# 1. Clear logs
|
||||
adb logcat -c
|
||||
|
||||
# 2. Launch app
|
||||
adb shell am start -n com.timesafari.dailynotification/.MainActivity
|
||||
|
||||
# 3. Schedule notification for 10 minutes in future
|
||||
# (Use app UI or API)
|
||||
|
||||
# 4. Verify alarm is scheduled
|
||||
adb shell dumpsys alarm | grep -i timesafari
|
||||
# Note the request code or trigger time
|
||||
|
||||
# 5. Manually cancel alarm (simulate missing alarm)
|
||||
# Find the alarm request code from dumpsys output
|
||||
# Then cancel using PendingIntent (requires root or app code)
|
||||
# OR: Use app UI to cancel if available
|
||||
|
||||
# Alternative: Use app code to cancel
|
||||
# (This test may require app modification to add cancel button)
|
||||
|
||||
# 6. Verify alarm is cancelled
|
||||
adb shell dumpsys alarm | grep -i timesafari
|
||||
# Should show no alarms (or fewer alarms)
|
||||
|
||||
# 7. Launch app (triggers recovery)
|
||||
adb shell am start -n com.timesafari.dailynotification/.MainActivity
|
||||
|
||||
# 8. Check recovery logs
|
||||
adb logcat -d | grep DNP-REACTIVATION
|
||||
|
||||
# 9. Verify alarm is rescheduled
|
||||
adb shell dumpsys alarm | grep -i timesafari
|
||||
# Should show rescheduled alarm
|
||||
```
|
||||
|
||||
### Expected Log Output
|
||||
|
||||
```
|
||||
DNP-REACTIVATION: Starting app launch recovery (Phase 1: cold start only)
|
||||
DNP-REACTIVATION: Cold start recovery: checking for missed notifications
|
||||
DNP-REACTIVATION: Rescheduled missing alarm: <id> at <timestamp>
|
||||
DNP-REACTIVATION: Cold start recovery complete: missed=0, rescheduled=1, verified=0, errors=0
|
||||
```
|
||||
|
||||
### Pass Criteria
|
||||
|
||||
- ✅ Log shows "Rescheduled missing alarm: <id>"
|
||||
- ✅ AlarmManager shows rescheduled alarm
|
||||
- ✅ No duplicate alarms created
|
||||
|
||||
---
|
||||
|
||||
## Test 3: Recovery Timeout
|
||||
|
||||
**Purpose**: Verify recovery times out gracefully.
|
||||
|
||||
### Steps
|
||||
|
||||
```bash
|
||||
# 1. Clear logs
|
||||
adb logcat -c
|
||||
|
||||
# 2. Create large number of schedules (100+)
|
||||
# This requires app modification or database manipulation
|
||||
# See "Database Manipulation" section below
|
||||
|
||||
# 3. Launch app
|
||||
adb shell am start -n com.timesafari.dailynotification/.MainActivity
|
||||
|
||||
# 4. Check logs immediately
|
||||
adb logcat -d | grep DNP-REACTIVATION
|
||||
```
|
||||
|
||||
### Expected Behavior
|
||||
|
||||
- ✅ Recovery completes within 2 seconds OR times out
|
||||
- ✅ App doesn't crash
|
||||
- ✅ Partial recovery logged if timeout occurs
|
||||
|
||||
### Pass Criteria
|
||||
|
||||
- ✅ Recovery doesn't block app launch
|
||||
- ✅ No app crash
|
||||
- ✅ Timeout logged if occurs
|
||||
|
||||
**Note**: This test may be difficult to execute without creating many schedules. Consider testing with smaller numbers first (10, 50 schedules) to verify behavior.
|
||||
|
||||
---
|
||||
|
||||
## Test 4: Invalid Data Handling
|
||||
|
||||
**Purpose**: Verify invalid data doesn't crash recovery.
|
||||
|
||||
### Steps
|
||||
|
||||
```bash
|
||||
# 1. Clear logs
|
||||
adb logcat -c
|
||||
|
||||
# 2. Manually insert invalid notification (empty ID) into database
|
||||
# See "Database Manipulation" section below
|
||||
|
||||
# 3. Launch app
|
||||
adb shell am start -n com.timesafari.dailynotification/.MainActivity
|
||||
|
||||
# 4. Check logs
|
||||
adb logcat -d | grep DNP-REACTIVATION
|
||||
```
|
||||
|
||||
### Expected Log Output
|
||||
|
||||
```
|
||||
DNP-REACTIVATION: Starting app launch recovery (Phase 1: cold start only)
|
||||
DNP-REACTIVATION: Cold start recovery: checking for missed notifications
|
||||
DNP-REACTIVATION: Skipping invalid notification: empty ID
|
||||
DNP-REACTIVATION: Cold start recovery complete: missed=0, rescheduled=0, verified=0, errors=0
|
||||
```
|
||||
|
||||
### Pass Criteria
|
||||
|
||||
- ✅ Invalid notification skipped
|
||||
- ✅ Warning logged
|
||||
- ✅ Recovery continues normally
|
||||
- ✅ App doesn't crash
|
||||
|
||||
---
|
||||
|
||||
## Helper Scripts and Commands
|
||||
|
||||
### Scheduling Notifications
|
||||
|
||||
**Option 1: Use App UI**
|
||||
- Launch app
|
||||
- Use "Schedule Notification" button
|
||||
- Set time to 2-5 minutes in future
|
||||
|
||||
**Option 2: Use Capacitor API (if test app has console)**
|
||||
```javascript
|
||||
// In browser console or test app
|
||||
const { DailyNotification } = Plugins.DailyNotification;
|
||||
await DailyNotification.scheduleDailyNotification({
|
||||
schedule: "*/2 * * * *", // Every 2 minutes
|
||||
title: "Test Notification",
|
||||
body: "Testing Phase 1 recovery"
|
||||
});
|
||||
```
|
||||
|
||||
**Option 3: Direct Database Insert (Advanced)**
|
||||
```bash
|
||||
# See "Database Manipulation" section
|
||||
```
|
||||
|
||||
### Time Manipulation (Emulator)
|
||||
|
||||
**Fast-forward system time** (for testing without waiting):
|
||||
|
||||
```bash
|
||||
# Get current time
|
||||
adb shell date +%s
|
||||
|
||||
# Set time forward (e.g., 5 minutes)
|
||||
adb shell date -s @$(($(adb shell date +%s) + 300))
|
||||
|
||||
# Or set specific time
|
||||
adb shell date -s "2025-11-15 14:30:00"
|
||||
```
|
||||
|
||||
**Note**: Some emulators may not support time changes. Test with actual waiting if time manipulation doesn't work.
|
||||
|
||||
### Database Manipulation
|
||||
|
||||
**Access database** (requires root or debug build):
|
||||
|
||||
```bash
|
||||
# Check if app is debuggable
|
||||
adb shell dumpsys package com.timesafari.dailynotification | grep debuggable
|
||||
|
||||
# Access database
|
||||
adb shell run-as com.timesafari.dailynotification sqlite3 databases/daily_notification_plugin.db
|
||||
|
||||
# Example: Insert test notification
|
||||
sqlite> INSERT INTO notification_content (
|
||||
id, plugin_version, title, body, scheduled_time,
|
||||
delivery_status, delivery_attempts, last_delivery_attempt,
|
||||
created_at, updated_at, ttl_seconds, priority,
|
||||
vibration_enabled, sound_enabled
|
||||
) VALUES (
|
||||
'test_notification_1', '1.1.0', 'Test', 'Test body',
|
||||
$(($(date +%s) * 1000 - 300000)), -- 5 minutes ago
|
||||
'pending', 0, 0,
|
||||
$(date +%s) * 1000, $(date +%s) * 1000,
|
||||
604800, 0, 1, 1
|
||||
);
|
||||
|
||||
# Example: Insert invalid notification (empty ID)
|
||||
sqlite> INSERT INTO notification_content (
|
||||
id, plugin_version, title, body, scheduled_time,
|
||||
delivery_status, delivery_attempts, last_delivery_attempt,
|
||||
created_at, updated_at, ttl_seconds, priority,
|
||||
vibration_enabled, sound_enabled
|
||||
) VALUES (
|
||||
'', '1.1.0', 'Invalid', 'Invalid body',
|
||||
$(($(date +%s) * 1000 - 300000)),
|
||||
'pending', 0, 0,
|
||||
$(date +%s) * 1000, $(date +%s) * 1000,
|
||||
604800, 0, 1, 1
|
||||
);
|
||||
|
||||
# Example: Create many schedules (for timeout test)
|
||||
sqlite> .read create_many_schedules.sql
|
||||
# (Create SQL file with 100+ INSERT statements)
|
||||
```
|
||||
|
||||
### Log Filtering
|
||||
|
||||
**Useful log filters**:
|
||||
|
||||
```bash
|
||||
# Recovery-specific logs
|
||||
adb logcat -s DNP-REACTIVATION
|
||||
|
||||
# All plugin logs
|
||||
adb logcat | grep -E "DNP-|DailyNotification"
|
||||
|
||||
# Recovery + scheduling logs
|
||||
adb logcat | grep -E "DNP-REACTIVATION|DN|SCHEDULE"
|
||||
|
||||
# Save logs to file
|
||||
adb logcat -d > phase1_test_$(date +%Y%m%d_%H%M%S).log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Test Sequence
|
||||
|
||||
**Run all tests in sequence**:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Phase 1 Complete Test Sequence
|
||||
|
||||
PACKAGE="com.timesafari.dailynotification"
|
||||
ACTIVITY="${PACKAGE}/.MainActivity"
|
||||
|
||||
echo "=== Phase 1 Testing on Emulator ==="
|
||||
echo ""
|
||||
|
||||
# Setup
|
||||
echo "1. Setting up emulator..."
|
||||
adb wait-for-device
|
||||
adb logcat -c
|
||||
|
||||
# Test 1: Cold Start Missed Detection
|
||||
echo ""
|
||||
echo "=== Test 1: Cold Start Missed Detection ==="
|
||||
echo "1. Launch app and schedule notification for 2 minutes"
|
||||
adb shell am start -n $ACTIVITY
|
||||
echo " (Use app UI to schedule notification)"
|
||||
read -p "Press Enter after scheduling notification..."
|
||||
|
||||
echo "2. Killing app process..."
|
||||
adb shell am kill $PACKAGE
|
||||
|
||||
echo "3. Waiting 5 minutes (or set time forward)..."
|
||||
echo " (You can set time forward: adb shell date -s ...)"
|
||||
read -p "Press Enter after waiting 5 minutes..."
|
||||
|
||||
echo "4. Launching app (cold start)..."
|
||||
adb shell am start -n $ACTIVITY
|
||||
sleep 2
|
||||
|
||||
echo "5. Checking recovery logs..."
|
||||
adb logcat -d | grep DNP-REACTIVATION
|
||||
|
||||
echo ""
|
||||
echo "=== Test 1 Complete ==="
|
||||
read -p "Press Enter to continue to Test 2..."
|
||||
|
||||
# Test 2: Future Alarm Rescheduling
|
||||
echo ""
|
||||
echo "=== Test 2: Future Alarm Rescheduling ==="
|
||||
echo "1. Schedule notification for 10 minutes"
|
||||
adb shell am start -n $ACTIVITY
|
||||
echo " (Use app UI to schedule notification)"
|
||||
read -p "Press Enter after scheduling..."
|
||||
|
||||
echo "2. Verify alarm scheduled..."
|
||||
adb shell dumpsys alarm | grep -i timesafari
|
||||
|
||||
echo "3. Cancel alarm (use app UI or see Database Manipulation)"
|
||||
read -p "Press Enter after cancelling alarm..."
|
||||
|
||||
echo "4. Launch app (triggers recovery)..."
|
||||
adb shell am start -n $ACTIVITY
|
||||
sleep 2
|
||||
|
||||
echo "5. Check recovery logs..."
|
||||
adb logcat -d | grep DNP-REACTIVATION
|
||||
|
||||
echo "6. Verify alarm rescheduled..."
|
||||
adb shell dumpsys alarm | grep -i timesafari
|
||||
|
||||
echo ""
|
||||
echo "=== Test 2 Complete ==="
|
||||
echo ""
|
||||
echo "=== All Tests Complete ==="
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Emulator Issues
|
||||
|
||||
**Emulator won't start**:
|
||||
```bash
|
||||
# Check available AVDs
|
||||
emulator -list-avds
|
||||
|
||||
# Kill existing emulator
|
||||
pkill -f emulator
|
||||
|
||||
# Start with verbose logging
|
||||
emulator -avd Pixel8_API34 -verbose
|
||||
```
|
||||
|
||||
**Emulator is slow**:
|
||||
```bash
|
||||
# Use hardware acceleration
|
||||
emulator -avd Pixel8_API34 -accel on -gpu host
|
||||
|
||||
# Allocate more RAM
|
||||
emulator -avd Pixel8_API34 -memory 4096
|
||||
```
|
||||
|
||||
### ADB Issues
|
||||
|
||||
**ADB not detecting emulator**:
|
||||
```bash
|
||||
# Restart ADB server
|
||||
adb kill-server
|
||||
adb start-server
|
||||
|
||||
# Check devices
|
||||
adb devices
|
||||
```
|
||||
|
||||
**Permission denied for database access**:
|
||||
```bash
|
||||
# Check if app is debuggable
|
||||
adb shell dumpsys package com.timesafari.dailynotification | grep debuggable
|
||||
|
||||
# If not debuggable, rebuild with debug signing
|
||||
cd test-apps/android-test-app
|
||||
./gradlew assembleDebug
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
```
|
||||
|
||||
### App Issues
|
||||
|
||||
**App won't launch**:
|
||||
```bash
|
||||
# Check if app is installed
|
||||
adb shell pm list packages | grep timesafari
|
||||
|
||||
# Uninstall and reinstall
|
||||
adb uninstall com.timesafari.dailynotification
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
```
|
||||
|
||||
**No logs appearing**:
|
||||
```bash
|
||||
# Check logcat buffer size
|
||||
adb logcat -G 10M
|
||||
|
||||
# Clear and monitor
|
||||
adb logcat -c
|
||||
adb logcat -s DNP-REACTIVATION
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Expected Test Results Summary
|
||||
|
||||
| Test | Expected Outcome | Verification Method |
|
||||
|------|------------------|---------------------|
|
||||
| **Test 1** | Missed notification detected and marked | Logs + Database query |
|
||||
| **Test 2** | Missing alarm rescheduled | Logs + AlarmManager check |
|
||||
| **Test 3** | Recovery times out gracefully | Logs (timeout message) |
|
||||
| **Test 4** | Invalid data skipped | Logs (warning message) |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Essential Commands
|
||||
|
||||
```bash
|
||||
# Start emulator
|
||||
emulator -avd Pixel8_API34 &
|
||||
|
||||
# Build and install
|
||||
cd test-apps/android-test-app
|
||||
./gradlew assembleDebug
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
|
||||
# Launch app
|
||||
adb shell am start -n com.timesafari.dailynotification/.MainActivity
|
||||
|
||||
# Kill app
|
||||
adb shell am kill com.timesafari.dailynotification
|
||||
|
||||
# Monitor logs
|
||||
adb logcat -s DNP-REACTIVATION
|
||||
|
||||
# Check alarms
|
||||
adb shell dumpsys alarm | grep -i timesafari
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Phase 1 Directive](../android-implementation-directive-phase1.md) - Implementation details
|
||||
- [Phase 1 Verification](./PHASE1-VERIFICATION.md) - Verification report
|
||||
- [Activation Guide](./ACTIVATION-GUIDE.md) - How to use directives
|
||||
- [Standalone Emulator Guide](../standalone-emulator-guide.md) - Emulator setup
|
||||
|
||||
---
|
||||
|
||||
**Status**: Emulator-verified (test-phase1.sh)
|
||||
**Last Updated**: 27 November 2025
|
||||
|
||||
@@ -1,259 +0,0 @@
|
||||
# Phase 1 Verification Report
|
||||
|
||||
**Date**: November 2025
|
||||
**Status**: Verification Complete
|
||||
**Phase**: Phase 1 - Cold Start Recovery
|
||||
|
||||
## Verification Summary
|
||||
|
||||
**Overall Status**: ✅ **VERIFIED** – Phase 1 is complete, aligned, implemented in plugin v1.1.0, and emulator-tested via `test-phase1.sh` on a Pixel 8 API 34 emulator.
|
||||
|
||||
**Verification Method**:
|
||||
- Automated emulator run using `PHASE1-EMULATOR-TESTING.md` + `test-phase1.sh`
|
||||
- All four Phase 1 tests (missed detection, future alarm verification/rescheduling, timeout, invalid data handling) passed with `errors=0`.
|
||||
|
||||
**Issues Found**: 2 minor documentation improvements recommended (resolved)
|
||||
|
||||
---
|
||||
|
||||
## 1. Alignment with Doc C (Requirements)
|
||||
|
||||
### ✅ Required Actions Check
|
||||
|
||||
**Doc C §3.1.2 - App Cold Start** requires:
|
||||
|
||||
| Required Action | Phase 1 Implementation | Status |
|
||||
|----------------|------------------------|--------|
|
||||
| 1. Load all enabled alarms from persistent storage | ✅ `db.scheduleDao().getEnabled()` | ✅ Complete |
|
||||
| 2. Verify active alarms match stored alarms | ✅ `NotifyReceiver.isAlarmScheduled()` check | ✅ Complete |
|
||||
| 3. Detect missed alarms (trigger_time < now) | ✅ `getNotificationsReadyForDelivery(currentTime)` | ✅ Complete |
|
||||
| 4. Reschedule future alarms | ✅ `rescheduleAlarm()` method | ✅ Complete |
|
||||
| 5. Generate missed alarm events/notifications | ⚠️ Deferred to Phase 2 | ✅ **OK** (explicitly out of scope) |
|
||||
| 6. Log recovery actions | ✅ Extensive logging with `DNP-REACTIVATION` tag | ✅ Complete |
|
||||
|
||||
**Result**: ✅ **All in-scope requirements implemented**
|
||||
|
||||
### ✅ Acceptance Criteria Check
|
||||
|
||||
**Doc C §3.1.2 Acceptance Criteria**:
|
||||
- ✅ Test scenario matches Phase 1 Test 1
|
||||
- ✅ Expected behavior matches Phase 1 implementation
|
||||
- ✅ Pass criteria align with Phase 1 success metrics
|
||||
|
||||
**Result**: ✅ **Acceptance criteria aligned**
|
||||
|
||||
---
|
||||
|
||||
## 2. Alignment with Doc A (Platform Facts)
|
||||
|
||||
### ✅ Platform Reference Check
|
||||
|
||||
**Doc A §2.1.4 - Alarms can be restored after app restart**:
|
||||
- ✅ Phase 1 references this capability correctly
|
||||
- ✅ Implementation uses AlarmManager APIs as documented
|
||||
- ✅ No platform assumptions beyond Doc A
|
||||
|
||||
**Missing**: Phase 1 doesn't explicitly cite Doc A §2.1.4 in the implementation section (minor)
|
||||
|
||||
**Recommendation**: Add explicit reference to Doc A §2.1.4 in Phase 1 §2 (Implementation)
|
||||
|
||||
---
|
||||
|
||||
## 3. Alignment with Doc B (Test Scenarios)
|
||||
|
||||
### ✅ Test Scenario Check
|
||||
|
||||
**Doc B Test 4 - Device Reboot** (Step 5: Cold Start):
|
||||
- ✅ Phase 1 Test 1 matches Doc B scenario
|
||||
- ✅ Test steps align
|
||||
- ✅ Expected results match
|
||||
|
||||
**Result**: ✅ **Test scenarios aligned**
|
||||
|
||||
---
|
||||
|
||||
## 4. Cross-Reference Verification
|
||||
|
||||
### ✅ Cross-References Present
|
||||
|
||||
| Reference | Location | Status |
|
||||
|-----------|----------|--------|
|
||||
| Doc C §3.1.2 | Phase 1 line 9 | ✅ Correct |
|
||||
| Doc A (general) | Phase 1 line 19 | ✅ Present |
|
||||
| Doc C (general) | Phase 1 line 18 | ✅ Present |
|
||||
| Phase 2/3 | Phase 1 lines 21-22 | ✅ Present |
|
||||
|
||||
### ⚠️ Missing Cross-References
|
||||
|
||||
| Missing Reference | Should Be Added | Priority |
|
||||
|-------------------|-----------------|----------|
|
||||
| Doc A §2.1.4 | In §2 (Implementation) | Minor |
|
||||
| Doc B Test 4 | In §8 (Testing) | Minor |
|
||||
|
||||
**Result**: ✅ **Core references present**, minor improvements recommended
|
||||
|
||||
---
|
||||
|
||||
## 5. Structure Verification
|
||||
|
||||
### ✅ Required Sections Present
|
||||
|
||||
| Section | Present | Notes |
|
||||
|---------|---------|-------|
|
||||
| Purpose | ✅ | Clear scope definition |
|
||||
| Acceptance Criteria | ✅ | Detailed with metrics |
|
||||
| Implementation | ✅ | Step-by-step with code |
|
||||
| Data Integrity | ✅ | Validation rules defined |
|
||||
| Rollback Safety | ✅ | No-crash guarantee |
|
||||
| Testing Requirements | ✅ | 4 test scenarios |
|
||||
| Implementation Checklist | ✅ | Complete checklist |
|
||||
| Code References | ✅ | Existing code listed |
|
||||
|
||||
**Result**: ✅ **All required sections present**
|
||||
|
||||
---
|
||||
|
||||
## 6. Scope Verification
|
||||
|
||||
### ✅ Out of Scope Items Correctly Deferred
|
||||
|
||||
| Item | Phase 1 Status | Correct? |
|
||||
|------|----------------|----------|
|
||||
| Force stop detection | ❌ Deferred to Phase 2 | ✅ Correct |
|
||||
| Warm start optimization | ❌ Deferred to Phase 2 | ✅ Correct |
|
||||
| Boot receiver handling | ❌ Deferred to Phase 3 | ✅ Correct |
|
||||
| Callback events | ❌ Deferred to Phase 2 | ✅ Correct |
|
||||
| Fetch work recovery | ❌ Deferred to Phase 2 | ✅ Correct |
|
||||
|
||||
**Result**: ✅ **Scope boundaries correctly defined**
|
||||
|
||||
---
|
||||
|
||||
## 7. Code Quality Verification
|
||||
|
||||
### ✅ Implementation Quality
|
||||
|
||||
| Aspect | Status | Notes |
|
||||
|--------|--------|-------|
|
||||
| Error handling | ✅ | All exceptions caught |
|
||||
| Timeout protection | ✅ | 2-second timeout |
|
||||
| Data validation | ✅ | Integrity checks present |
|
||||
| Logging | ✅ | Comprehensive logging |
|
||||
| Non-blocking | ✅ | Async with coroutines |
|
||||
| Rollback safety | ✅ | No-crash guarantee |
|
||||
|
||||
**Result**: ✅ **Code quality meets requirements**
|
||||
|
||||
---
|
||||
|
||||
## 8. Testing Verification
|
||||
|
||||
### ✅ Test Coverage
|
||||
|
||||
| Test Scenario | Present | Aligned with Doc B? |
|
||||
|---------------|---------|---------------------|
|
||||
| Cold start missed detection | ✅ | ✅ Yes |
|
||||
| Future alarm rescheduling | ✅ | ✅ Yes |
|
||||
| Recovery timeout | ✅ | ✅ Yes |
|
||||
| Invalid data handling | ✅ | ✅ Yes |
|
||||
|
||||
**Result**: ✅ **Test coverage complete**
|
||||
|
||||
---
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Issue 1: Missing Explicit Doc A Reference (Minor)
|
||||
|
||||
**Location**: Phase 1 §2 (Implementation)
|
||||
|
||||
**Problem**: Implementation doesn't explicitly cite Doc A §2.1.4
|
||||
|
||||
**Recommendation**: Add reference in §2.3 (Cold Start Recovery):
|
||||
```markdown
|
||||
**Platform Reference**: [Android §2.1.4](./alarms/01-platform-capability-reference.md#214-alarms-can-be-restored-after-app-restart)
|
||||
```
|
||||
|
||||
**Priority**: Minor (documentation improvement)
|
||||
|
||||
---
|
||||
|
||||
### Issue 2: Related Documentation Section (Minor)
|
||||
|
||||
**Location**: Phase 1 §11 (Related Documentation)
|
||||
|
||||
**Problem**: References old documentation files instead of unified docs
|
||||
|
||||
**Current**:
|
||||
```markdown
|
||||
- [Full Implementation Directive](./android-implementation-directive.md) - Complete scope (all phases)
|
||||
- [Exploration Findings](./exploration-findings-initial.md) - Gap analysis
|
||||
- [Plugin Requirements](./plugin-requirements-implementation.md) - Requirements
|
||||
```
|
||||
|
||||
**Should Be**:
|
||||
```markdown
|
||||
- [Unified Alarm Directive](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document
|
||||
- [Plugin Requirements](./alarms/03-plugin-requirements.md) - Requirements this phase implements
|
||||
- [Platform Capability Reference](./alarms/01-platform-capability-reference.md) - OS-level facts
|
||||
- [Plugin Behavior Exploration](./alarms/02-plugin-behavior-exploration.md) - Test scenarios
|
||||
- [Full Implementation Directive](./android-implementation-directive.md) - Complete scope (all phases)
|
||||
```
|
||||
|
||||
**Priority**: Minor (documentation improvement)
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [x] Phase 1 implements all required actions from Doc C §3.1.2
|
||||
- [x] Acceptance criteria align with Doc C
|
||||
- [x] Platform facts referenced (implicitly, could be explicit)
|
||||
- [x] Test scenarios align with Doc B
|
||||
- [x] Cross-references to Doc C present and correct
|
||||
- [x] Scope boundaries correctly defined
|
||||
- [x] Implementation quality meets requirements
|
||||
- [x] Testing requirements complete
|
||||
- [x] Code structure follows best practices
|
||||
- [x] Error handling comprehensive
|
||||
- [x] Rollback safety guaranteed
|
||||
|
||||
---
|
||||
|
||||
## Final Verdict
|
||||
|
||||
**Status**: ✅ **VERIFIED AND READY**
|
||||
|
||||
Phase 1 is:
|
||||
- ✅ Complete and well-structured
|
||||
- ✅ Aligned with Doc C requirements
|
||||
- ✅ Properly scoped (cold start only)
|
||||
- ✅ Ready for implementation
|
||||
- ⚠️ Minor documentation improvements recommended (non-blocking)
|
||||
|
||||
**Recommendation**: Proceed with implementation. Apply minor documentation improvements during implementation or in a follow-up commit.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ **Begin Implementation** - Phase 1 is verified and ready
|
||||
2. ⚠️ **Apply Minor Fixes** (optional) - Add explicit Doc A reference, update Related Documentation
|
||||
3. ✅ **Follow Testing Requirements** - Use Phase 1 §8 test scenarios
|
||||
4. ✅ **Update Status Matrix** - Mark Phase 1 as "In Use" when deployed
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Phase 1 Directive](../android-implementation-directive-phase1.md) - Implementation guide
|
||||
- [Plugin Requirements](./03-plugin-requirements.md#312-app-cold-start) - Requirements
|
||||
- [Platform Capability Reference](./01-platform-capability-reference.md#214-alarms-can-be-restored-after-app-restart) - OS facts
|
||||
- [Activation Guide](./ACTIVATION-GUIDE.md) - How to use directives
|
||||
|
||||
---
|
||||
|
||||
**Verification Date**: November 2025
|
||||
**Verified By**: Documentation Review
|
||||
**Status**: Complete
|
||||
|
||||
@@ -1,358 +0,0 @@
|
||||
# PHASE 2 – EMULATOR TESTING
|
||||
|
||||
**Force Stop Detection & Recovery**
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Phase 2 verifies that the Daily Notification Plugin correctly:
|
||||
|
||||
1. Detects **force stop** scenarios (where alarms may be cleared by the OS).
|
||||
2. **Reschedules** future notifications when alarms are missing but schedules remain in the database.
|
||||
3. **Avoids heavy recovery** when alarms are still intact.
|
||||
4. **Does not misfire** force-stop recovery on first launch / empty database.
|
||||
|
||||
This document defines the emulator test procedure for Phase 2 using the script:
|
||||
|
||||
```bash
|
||||
test-apps/android-test-app/test-phase2.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Prerequisites
|
||||
|
||||
* Android emulator or device, e.g.:
|
||||
* Pixel 8 / API 34 (recommended baseline)
|
||||
* ADB available in `PATH` (or `ADB_BIN` exported)
|
||||
* Project built with:
|
||||
* Daily Notification Plugin integrated
|
||||
* Test app at: `test-apps/android-test-app`
|
||||
* Debug APK path:
|
||||
* `app/build/outputs/apk/debug/app-debug.apk`
|
||||
* Phase 1 behavior already implemented and verified:
|
||||
* Cold start detection
|
||||
* Missed notification marking
|
||||
|
||||
> **Note:** Some OS/device combinations do not clear alarms on `am force-stop`. In such cases, TEST 1 may partially skip or only verify scenario logging.
|
||||
|
||||
---
|
||||
|
||||
## 3. How to Run
|
||||
|
||||
From the `android-test-app` directory:
|
||||
|
||||
```bash
|
||||
cd test-apps/android-test-app
|
||||
chmod +x test-phase2.sh # first time only
|
||||
./test-phase2.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
|
||||
1. Perform pre-flight checks (ADB/emulator).
|
||||
2. Build and install the debug APK.
|
||||
3. Guide you through three tests:
|
||||
* TEST 1: Force stop – alarms cleared
|
||||
* TEST 2: Force stop / process stop – alarms intact
|
||||
* TEST 3: First launch / empty DB safeguard
|
||||
4. Print parsed recovery summaries from `DNP-REACTIVATION` logs.
|
||||
|
||||
You will be prompted for **UI actions** at each step (e.g., configuring the plugin, pressing "Test Notification").
|
||||
|
||||
---
|
||||
|
||||
## 4. Test Cases
|
||||
|
||||
### 4.1 TEST 1 – Force Stop with Cleared Alarms
|
||||
|
||||
**Goal:**
|
||||
|
||||
Verify that when a force stop clears alarms, the plugin:
|
||||
|
||||
* Detects the **FORCE_STOP** scenario.
|
||||
* Reschedules future notifications.
|
||||
* Completes recovery with `errors=0`.
|
||||
|
||||
**Steps (Script Flow):**
|
||||
|
||||
1. **Launch & configure plugin**
|
||||
* Script launches the app.
|
||||
* In the app UI, confirm:
|
||||
* `⚙️ Plugin Settings: ✅ Configured`
|
||||
* `🔌 Native Fetcher: ✅ Configured`
|
||||
* If not, press **Configure Plugin** and wait until both are ✅.
|
||||
|
||||
2. **Schedule a future notification**
|
||||
* Click **Test Notification** (or equivalent) to schedule a notification a few minutes in the future.
|
||||
|
||||
3. **Verify alarms are scheduled**
|
||||
* Script runs:
|
||||
```bash
|
||||
adb shell dumpsys alarm | grep com.timesafari.dailynotification
|
||||
```
|
||||
* Confirm at least one `RTC_WAKEUP` alarm for `com.timesafari.dailynotification`.
|
||||
|
||||
4. **Force stop the app**
|
||||
* Script executes:
|
||||
```bash
|
||||
adb shell am force-stop com.timesafari.dailynotification
|
||||
```
|
||||
|
||||
5. **Confirm alarms after force stop**
|
||||
* Script re-runs `dumpsys alarm`.
|
||||
* Ideal test case: **0** alarms for `com.timesafari.dailynotification` (alarms cleared).
|
||||
|
||||
6. **Trigger recovery**
|
||||
* Script clears logcat and launches the app.
|
||||
* Wait ~5 seconds for recovery.
|
||||
|
||||
7. **Collect and inspect logs**
|
||||
* Script collects `DNP-REACTIVATION` logs and parses:
|
||||
* `scenario=<value>`
|
||||
* `missed=<n>`
|
||||
* `rescheduled=<n>`
|
||||
* `verified=<n>`
|
||||
* `errors=<n>`
|
||||
|
||||
**Expected Logs (Ideal Case):**
|
||||
|
||||
* Scenario:
|
||||
```text
|
||||
DNP-REACTIVATION: Detected scenario: FORCE_STOP
|
||||
```
|
||||
|
||||
* Alarm handling:
|
||||
```text
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <time>
|
||||
DNP-REACTIVATION: Rescheduled missing alarm: daily_<id> at <time>
|
||||
```
|
||||
|
||||
* Summary:
|
||||
```text
|
||||
DNP-REACTIVATION: Force stop recovery completed: missed=1, rescheduled=1, verified=0, errors=0
|
||||
```
|
||||
|
||||
**Pass Criteria:**
|
||||
|
||||
* `scenario=FORCE_STOP`
|
||||
* `rescheduled > 0`
|
||||
* `errors = 0`
|
||||
* Script prints:
|
||||
> `✅ TEST 1 PASSED: Force stop detected and alarms rescheduled (scenario=FORCE_STOP, rescheduled=1).`
|
||||
|
||||
**Partial / Edge Cases:**
|
||||
|
||||
* If alarms remain after `force-stop` on this device:
|
||||
* Script warns that FORCE_STOP may not fully trigger.
|
||||
* Mark this as **environment-limited** rather than a plugin failure.
|
||||
|
||||
---
|
||||
|
||||
### 4.2 TEST 2 – Force Stop / Process Stop with Intact Alarms
|
||||
|
||||
**Goal:**
|
||||
|
||||
Ensure we **do not run heavy force-stop recovery** when alarms are still intact.
|
||||
|
||||
**Steps (Script Flow):**
|
||||
|
||||
1. **Launch & configure plugin**
|
||||
* Same as TEST 1 (ensure both plugin statuses are ✅).
|
||||
|
||||
2. **Schedule another future notification**
|
||||
* Click **Test Notification** again to create a second schedule.
|
||||
|
||||
3. **Verify alarms are scheduled**
|
||||
* Confirm multiple alarms for `com.timesafari.dailynotification` via `dumpsys alarm`.
|
||||
|
||||
4. **Simulate a "soft stop"**
|
||||
* Script runs:
|
||||
```bash
|
||||
adb shell am kill com.timesafari.dailynotification
|
||||
```
|
||||
* Intent: stop the process but **not** clear alarms (actual behavior may vary by OS).
|
||||
|
||||
5. **Check alarms after soft stop**
|
||||
* Ensure alarms are still present in `dumpsys alarm`.
|
||||
|
||||
6. **Trigger recovery**
|
||||
* Script clears logcat and relaunches the app.
|
||||
* Wait ~5 seconds.
|
||||
|
||||
7. **Collect logs**
|
||||
* Script parses `DNP-REACTIVATION` logs for:
|
||||
* `scenario`
|
||||
* `rescheduled`
|
||||
* `errors`
|
||||
|
||||
**Expected Behavior:**
|
||||
|
||||
* `scenario` should **not** be `FORCE_STOP` (e.g., `COLD_START` or another non-force-stop scenario, depending on your implementation).
|
||||
* `rescheduled = 0`.
|
||||
* `errors = 0`.
|
||||
|
||||
**Pass Criteria:**
|
||||
|
||||
* Alarms still present after soft stop.
|
||||
* Recovery summary indicates **no force-stop-level rescheduling** when alarms are intact:
|
||||
* `scenario != FORCE_STOP`
|
||||
* `rescheduled = 0`
|
||||
* Script prints:
|
||||
> `✅ TEST 2 PASSED: No heavy force-stop recovery when alarms intact (scenario=<value>, rescheduled=0).`
|
||||
|
||||
If `scenario=FORCE_STOP` and `rescheduled>0` here, treat this as a **warning** and review scenario detection logic.
|
||||
|
||||
---
|
||||
|
||||
### 4.3 TEST 3 – First Launch / Empty DB Safeguard
|
||||
|
||||
**Goal:**
|
||||
|
||||
Ensure **force-stop recovery is not mis-triggered** when the app is freshly installed with **no schedules**.
|
||||
|
||||
**Steps (Script Flow):**
|
||||
|
||||
1. **Clear state**
|
||||
* Script uninstalls the app to clear DB/state:
|
||||
```bash
|
||||
adb uninstall com.timesafari.dailynotification
|
||||
```
|
||||
|
||||
2. **Reinstall APK**
|
||||
* Script reinstalls `app-debug.apk`.
|
||||
|
||||
3. **Launch app without scheduling anything**
|
||||
* Script launches the app.
|
||||
* Do **not** schedule notifications or configure plugin beyond initial display.
|
||||
|
||||
4. **Collect logs**
|
||||
* Script grabs `DNP-REACTIVATION` logs and parses:
|
||||
* `scenario`
|
||||
* `rescheduled`
|
||||
|
||||
**Expected Behavior:**
|
||||
|
||||
* Either:
|
||||
* No `DNP-REACTIVATION` logs at all (no recovery run), **or**
|
||||
* A specific "no schedules" scenario, e.g.:
|
||||
```text
|
||||
DNP-REACTIVATION: No schedules present — skipping recovery (first launch)
|
||||
```
|
||||
or
|
||||
```text
|
||||
DNP-REACTIVATION: Detected scenario: NONE
|
||||
```
|
||||
|
||||
* In both cases:
|
||||
* `rescheduled = 0`.
|
||||
|
||||
**Pass Criteria:**
|
||||
|
||||
* If **no logs**:
|
||||
* Pass: recovery correctly doesn't run at all on empty DB.
|
||||
* If logs present:
|
||||
* `scenario=NONE` (or equivalent) **and** `rescheduled=0`.
|
||||
|
||||
Script will report success when:
|
||||
|
||||
* `scenario == NONE_SCENARIO_VALUE` and `rescheduled=0`, or
|
||||
* No recovery logs are found.
|
||||
|
||||
---
|
||||
|
||||
## 5. Latest Known Good Run (Template)
|
||||
|
||||
Fill this in after your first successful emulator run.
|
||||
|
||||
```markdown
|
||||
---
|
||||
## Latest Known Good Run (Emulator)
|
||||
|
||||
**Environment**
|
||||
|
||||
- Device: Pixel 8 API 34 (Android 14)
|
||||
- App ID: `com.timesafari.dailynotification`
|
||||
- Build: Debug APK (`app-debug.apk`) from commit `<GIT_HASH>`
|
||||
- Script: `./test-phase2.sh`
|
||||
- Date: 2025-11-XX
|
||||
|
||||
**Results**
|
||||
|
||||
- ✅ TEST 1: Force Stop – Alarms Cleared
|
||||
- `scenario=FORCE_STOP`
|
||||
- `missed=1, rescheduled=1, verified=0, errors=0`
|
||||
|
||||
- ✅ TEST 2: Force Stop / Process Stop – Alarms Intact
|
||||
- `scenario=COLD_START` (or equivalent non-force-stop scenario)
|
||||
- `rescheduled=0, errors=0`
|
||||
|
||||
- ✅ TEST 3: First Launch / No Schedules
|
||||
- `scenario=NONE` (or no logs)
|
||||
- `rescheduled=0`
|
||||
|
||||
**Conclusion:**
|
||||
Phase 2 **Force Stop Detection & Recovery** is verified on the emulator using `test-phase2.sh`. This run is the canonical reference for future regression testing.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Troubleshooting
|
||||
|
||||
### Alarms Not Cleared on Force Stop
|
||||
|
||||
**Symptom**: `am force-stop` doesn't clear alarms in AlarmManager
|
||||
|
||||
**Cause**: Some Android versions/emulators don't clear alarms on force stop
|
||||
|
||||
**Solution**:
|
||||
- This is expected behavior on some systems
|
||||
- TEST 1 will run as Phase 1 (cold start) recovery
|
||||
- For full force stop validation, test on a device/OS that clears alarms
|
||||
- Script will report this as an environment limitation, not a failure
|
||||
|
||||
### Scenario Not Detected as FORCE_STOP
|
||||
|
||||
**Symptom**: Logs show `COLD_START` even when alarms were cleared
|
||||
|
||||
**Possible Causes**:
|
||||
1. Scenario detection logic not implemented (Phase 2 not complete)
|
||||
2. Alarm count check failing (`alarmsExist()` returning true when it shouldn't)
|
||||
3. Database query timing issue
|
||||
|
||||
**Solution**:
|
||||
- Verify Phase 2 implementation is complete
|
||||
- Check `ReactivationManager.detectScenario()` implementation
|
||||
- Review logs for alarm existence checks
|
||||
- Verify `alarmsExist()` uses PendingIntent check (not `nextAlarmClock`)
|
||||
|
||||
### Recovery Doesn't Reschedule Alarms
|
||||
|
||||
**Symptom**: `rescheduled=0` even when alarms were cleared
|
||||
|
||||
**Possible Causes**:
|
||||
1. Schedules not in database
|
||||
2. Reschedule logic failing
|
||||
3. Alarm scheduling permissions missing
|
||||
|
||||
**Solution**:
|
||||
- Verify schedules exist in database
|
||||
- Check logs for reschedule errors
|
||||
- Verify exact alarm permission is granted
|
||||
- Review `performForceStopRecovery()` implementation
|
||||
|
||||
---
|
||||
|
||||
## 7. Related Documentation
|
||||
|
||||
- [Phase 2 Directive](../android-implementation-directive-phase2.md) - Implementation details
|
||||
- [Phase 2 Verification](./PHASE2-VERIFICATION.md) - Verification report
|
||||
- [Phase 1 Testing Guide](./PHASE1-EMULATOR-TESTING.md) - Prerequisite testing
|
||||
- [Activation Guide](./ACTIVATION-GUIDE.md) - How to use directives
|
||||
- [Plugin Requirements](./03-plugin-requirements.md) - Requirements Phase 2 implements
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for testing (Phase 2 implementation pending)
|
||||
**Last Updated**: November 2025
|
||||
@@ -1,195 +0,0 @@
|
||||
# Phase 2 – Force Stop Recovery Verification
|
||||
|
||||
**Plugin:** Daily Notification Plugin
|
||||
**Scope:** Force stop detection & recovery (App ID: `com.timesafari.dailynotification`)
|
||||
**Related Docs:**
|
||||
|
||||
- `android-implementation-directive-phase2.md`
|
||||
- `03-plugin-requirements.md` (Force Stop & App Termination behavior)
|
||||
- `PHASE2-EMULATOR-TESTING.md`
|
||||
- `000-UNIFIED-ALARM-DIRECTIVE.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Objective
|
||||
|
||||
Phase 2 verifies that the Daily Notification Plugin:
|
||||
|
||||
1. Correctly detects **force stop** conditions where alarms may have been cleared.
|
||||
2. **Reschedules** future notifications when schedules exist in the database but alarms are missing.
|
||||
3. **Avoids heavy recovery** when alarms are intact (no false positives).
|
||||
4. **Does not misfire** force-stop recovery on first launch / empty database.
|
||||
|
||||
Phase 2 builds on Phase 1, which already covers:
|
||||
|
||||
- Cold start detection
|
||||
- Missed notification marking
|
||||
- Basic alarm verification
|
||||
|
||||
---
|
||||
|
||||
## 2. Test Method
|
||||
|
||||
Verification is performed using the emulator test harness:
|
||||
|
||||
```bash
|
||||
cd test-apps/android-test-app
|
||||
./test-phase2.sh
|
||||
```
|
||||
|
||||
This script:
|
||||
|
||||
* Builds and installs the debug APK (`app/build/outputs/apk/debug/app-debug.apk`).
|
||||
* Guides the tester through UI steps for scheduling notifications and configuring the plugin.
|
||||
* Simulates:
|
||||
* `force-stop` behavior via `adb shell am force-stop ...`
|
||||
* "Soft stop" / process kill via `adb shell am kill ...`
|
||||
* First launch / empty DB via uninstall + reinstall
|
||||
* Collects and parses `DNP-REACTIVATION` log lines, extracting:
|
||||
* `scenario`
|
||||
* `missed`
|
||||
* `rescheduled`
|
||||
* `verified`
|
||||
* `errors`
|
||||
|
||||
Detailed steps and expectations are documented in `PHASE2-EMULATOR-TESTING.md`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Test Matrix
|
||||
|
||||
| ID | Scenario | Method / Script Step | Expected Behavior | Result | Notes |
|
||||
| --- | ---------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------ | ----- |
|
||||
| 2.1 | Force stop clears alarms | `test-phase2.sh` – TEST 1: Force Stop – Alarms Cleared | `scenario=FORCE_STOP`, `rescheduled>0`, `errors=0` | ☐ | |
|
||||
| 2.2 | Force stop / process stop with alarms intact | `test-phase2.sh` – TEST 2: Soft Stop – Alarms Intact | `scenario != FORCE_STOP`, `rescheduled=0`, `errors=0` | ☐ | |
|
||||
| 2.3 | First launch / empty DB (no schedules present) | `test-phase2.sh` – TEST 3: First Launch / No Schedules | Either no recovery logs **or** `scenario=NONE` (or equivalent) and `rescheduled=0`, `errors=0` | ☐ | |
|
||||
|
||||
> Fill in **Result** and **Notes** after executing the script on your baseline emulator/device.
|
||||
|
||||
---
|
||||
|
||||
## 4. Expected Log Patterns
|
||||
|
||||
### 4.1 Force Stop – Alarms Cleared (Test 2.1)
|
||||
|
||||
Typical expected `DNP-REACTIVATION` log patterns:
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: Detected scenario: FORCE_STOP
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <time>
|
||||
DNP-REACTIVATION: Rescheduled missing alarm: daily_<id> at <time>
|
||||
DNP-REACTIVATION: Force stop recovery completed: missed=1, rescheduled=1, verified=0, errors=0
|
||||
```
|
||||
|
||||
The **script** will report:
|
||||
|
||||
```text
|
||||
✅ TEST 1 PASSED: Force stop detected and alarms rescheduled (scenario=FORCE_STOP, rescheduled=1).
|
||||
```
|
||||
|
||||
### 4.2 Soft Stop – Alarms Intact (Test 2.2)
|
||||
|
||||
Typical expected patterns:
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: Detected scenario: COLD_START
|
||||
DNP-REACTIVATION: Cold start recovery completed: missed=0, rescheduled=0, verified>=0, errors=0
|
||||
```
|
||||
|
||||
The script should **not** treat this as a force-stop recovery:
|
||||
|
||||
```text
|
||||
✅ TEST 2 PASSED: No heavy force-stop recovery when alarms are intact (scenario=COLD_START, rescheduled=0).
|
||||
```
|
||||
|
||||
(Adjust `scenario` name to match your actual implementation.)
|
||||
|
||||
### 4.3 First Launch / Empty DB (Test 2.3)
|
||||
|
||||
Two acceptable patterns:
|
||||
|
||||
1. **No recovery logs at all** (`DNP-REACTIVATION` absent), or
|
||||
2. Explicit "no schedules" scenario, e.g.:
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: No schedules present — skipping recovery (first launch)
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: Detected scenario: NONE
|
||||
```
|
||||
|
||||
Script-level success message might be:
|
||||
|
||||
```text
|
||||
✅ TEST 3 PASSED: NONE scenario detected with no rescheduling.
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```text
|
||||
✅ TEST 3 PASSED: No recovery logs when there are no schedules (safe behavior).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Latest Known Good Run (Emulator) – Placeholder
|
||||
|
||||
> Update this section after your first successful run.
|
||||
|
||||
**Environment**
|
||||
|
||||
* Device: Pixel 8 API 34 (Android 14)
|
||||
* App ID: `com.timesafari.dailynotification`
|
||||
* Build: Debug `app-debug.apk` from commit `<GIT_HASH>`
|
||||
* Script: `./test-phase2.sh`
|
||||
* Date: 2025-11-XX
|
||||
|
||||
**Observed Results**
|
||||
|
||||
* ☐ **2.1 – Force Stop / Alarms Cleared**
|
||||
* `scenario=FORCE_STOP`
|
||||
* `missed=1, rescheduled=1, verified=0, errors=0`
|
||||
|
||||
* ☐ **2.2 – Soft Stop / Alarms Intact**
|
||||
* `scenario=COLD_START` (or equivalent non-force-stop scenario)
|
||||
* `rescheduled=0, errors=0`
|
||||
|
||||
* ☐ **2.3 – First Launch / Empty DB**
|
||||
* `scenario=NONE` (or no logs)
|
||||
* `rescheduled=0, errors=0`
|
||||
|
||||
**Conclusion:**
|
||||
|
||||
> To be filled after first successful emulator run.
|
||||
|
||||
---
|
||||
|
||||
## 6. Overall Status
|
||||
|
||||
> To be updated once the first emulator pass is complete.
|
||||
|
||||
* **Implementation Status:** ☐ Pending / ✅ Implemented in `ReactivationManager` (Android plugin)
|
||||
* **Test Harness:** ✅ `test-phase2.sh` in `test-apps/android-test-app`
|
||||
* **Emulator Verification:** ☐ Pending / ✅ Completed (update when done)
|
||||
|
||||
Once all boxes are checked:
|
||||
|
||||
> **Overall Status:** ✅ **VERIFIED** – Phase 2 behavior is implemented, emulator-tested, and aligned with `03-plugin-requirements.md` and `android-implementation-directive-phase2.md`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Related Documentation
|
||||
|
||||
- [Phase 2 Directive](../android-implementation-directive-phase2.md) - Implementation details
|
||||
- [Phase 2 Emulator Testing](./PHASE2-EMULATOR-TESTING.md) - Test procedures
|
||||
- [Phase 1 Verification](./PHASE1-VERIFICATION.md) - Prerequisite verification
|
||||
- [Plugin Requirements](./03-plugin-requirements.md) - Requirements this phase implements
|
||||
- [Platform Capability Reference](./01-platform-capability-reference.md) - OS-level facts
|
||||
|
||||
---
|
||||
|
||||
**Status**: ☐ **PENDING** – Phase 2 implementation and testing pending
|
||||
**Last Updated**: November 2025
|
||||
@@ -1,325 +0,0 @@
|
||||
# PHASE 3 – EMULATOR TESTING
|
||||
|
||||
**Boot-Time Recovery (Device Reboot / System Restart)**
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Phase 3 verifies that the Daily Notification Plugin correctly:
|
||||
|
||||
1. Reconstructs **AlarmManager** alarms after a full device/emulator reboot.
|
||||
2. Handles **past** scheduled times by marking them as missed and scheduling the next occurrence.
|
||||
3. Handles **empty DB / no schedules** without misfiring recovery.
|
||||
4. Performs **silent boot recovery** (recreate alarms) even when the app is never opened after reboot.
|
||||
|
||||
This testing is driven by the script:
|
||||
|
||||
```bash
|
||||
test-apps/android-test-app/test-phase3.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Prerequisites
|
||||
|
||||
* Android emulator or device, e.g.:
|
||||
* Pixel 8 / API 34 (recommended baseline)
|
||||
* ADB available in `PATH` (or `ADB_BIN` exported)
|
||||
* Project with:
|
||||
* Daily Notification Plugin integrated
|
||||
* Test app at `test-apps/android-test-app`
|
||||
* Debug APK path:
|
||||
* `app/build/outputs/apk/debug/app-debug.apk`
|
||||
* Phase 1 and Phase 2 behaviors already implemented:
|
||||
* Cold start detection
|
||||
* Force-stop detection
|
||||
* Missed / rescheduled / verified / errors summary fields
|
||||
|
||||
> ⚠️ **Important:**
|
||||
> This script will reboot the emulator multiple times. Each reboot may take 30–60 seconds.
|
||||
|
||||
---
|
||||
|
||||
## 3. How to Run
|
||||
|
||||
From the `android-test-app` directory:
|
||||
|
||||
```bash
|
||||
cd test-apps/android-test-app
|
||||
chmod +x test-phase3.sh # first time only
|
||||
./test-phase3.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
|
||||
1. Run pre-flight checks (ADB / emulator readiness).
|
||||
2. Build and install the debug APK.
|
||||
3. Guide you through four tests:
|
||||
* **TEST 1:** Boot with Future Alarms
|
||||
* **TEST 2:** Boot with Past Alarms
|
||||
* **TEST 3:** Boot with No Schedules
|
||||
* **TEST 4:** Silent Boot Recovery (App Never Opened)
|
||||
4. Parse and display `DNP-REACTIVATION` logs, including:
|
||||
* `scenario`
|
||||
* `missed`
|
||||
* `rescheduled`
|
||||
* `verified`
|
||||
* `errors`
|
||||
|
||||
---
|
||||
|
||||
## 4. Test Cases (Script-Driven Flow)
|
||||
|
||||
### 4.1 TEST 1 – Boot with Future Alarms
|
||||
|
||||
**Goal:**
|
||||
|
||||
Verify alarms are recreated on boot when schedules have **future run times**.
|
||||
|
||||
**Script flow:**
|
||||
|
||||
1. **Launch app & check plugin status**
|
||||
* Script calls `launch_app`.
|
||||
* UI prompt: Confirm plugin status shows:
|
||||
* `⚙️ Plugin Settings: ✅ Configured`
|
||||
* `🔌 Native Fetcher: ✅ Configured`
|
||||
* If not, click **Configure Plugin**, wait until both show ✅, then continue.
|
||||
|
||||
2. **Schedule at least one future notification**
|
||||
* UI prompt: Click e.g. **Test Notification** to schedule a notification a few minutes in the future.
|
||||
|
||||
3. **Verify alarms are scheduled (pre-boot)**
|
||||
* Script calls `show_alarms` and `count_alarms`.
|
||||
* You should see at least one `RTC_WAKEUP` entry for `com.timesafari.dailynotification`.
|
||||
|
||||
4. **Reboot emulator**
|
||||
* Script calls `reboot_emulator`:
|
||||
* `adb reboot`
|
||||
* `adb wait-for-device`
|
||||
* Polls `getprop sys.boot_completed` until `1`.
|
||||
* You are warned that reboot will take 30–60 seconds.
|
||||
|
||||
5. **Collect boot recovery logs**
|
||||
* Script calls `get_recovery_logs`:
|
||||
```bash
|
||||
adb logcat -d | grep "DNP-REACTIVATION"
|
||||
```
|
||||
* It parses:
|
||||
* `missed`, `rescheduled`, `verified`, `errors`
|
||||
* `scenario` via:
|
||||
* `Starting boot recovery`/`boot recovery` → `scenario=BOOT`
|
||||
* or `Detected scenario: <VALUE>`
|
||||
|
||||
6. **Verify alarms were recreated (post-boot)**
|
||||
* Script calls `show_alarms` and `count_alarms` again.
|
||||
* Checks `scenario` and `rescheduled`.
|
||||
|
||||
**Expected log patterns:**
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: Starting boot recovery
|
||||
DNP-REACTIVATION: Loaded <N> schedules from DB
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <time>
|
||||
DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled>=1, verified=0, errors=0
|
||||
```
|
||||
|
||||
**Pass criteria (as per script):**
|
||||
|
||||
* `errors = 0`
|
||||
* `scenario = BOOT` (or boot detected via log text)
|
||||
* `rescheduled > 0`
|
||||
* Script prints:
|
||||
> `✅ TEST 1 PASSED: Boot recovery detected and alarms rescheduled (scenario=BOOT, rescheduled=<n>).`
|
||||
|
||||
If boot recovery runs but `rescheduled=0`, script warns and suggests checking boot logic.
|
||||
|
||||
---
|
||||
|
||||
### 4.2 TEST 2 – Boot with Past Alarms
|
||||
|
||||
**Goal:**
|
||||
|
||||
Verify past alarms are marked as missed and **next occurrences are scheduled** after boot.
|
||||
|
||||
**Script flow:**
|
||||
|
||||
1. **Launch app & ensure plugin configured**
|
||||
* Same plugin status check as TEST 1.
|
||||
|
||||
2. **Schedule a notification in the near future**
|
||||
* UI prompt: Schedule such that **by the time you reboot and the device comes back, the planned notification time is in the past**.
|
||||
|
||||
3. **Wait or adjust so the alarm is effectively "in the past" at boot**
|
||||
* The script may instruct you to wait, or you can coordinate timing manually.
|
||||
|
||||
4. **Reboot emulator**
|
||||
* Same `reboot_emulator` path as TEST 1.
|
||||
|
||||
5. **Collect boot recovery logs**
|
||||
* Script parses:
|
||||
* `missed`, `rescheduled`, `errors`, `scenario`.
|
||||
|
||||
**Expected log patterns:**
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: Starting boot recovery
|
||||
DNP-REACTIVATION: Loaded <N> schedules from DB
|
||||
DNP-REACTIVATION: Marked missed notification: daily_<id>
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <next_time>
|
||||
DNP-REACTIVATION: Boot recovery complete: missed>=1, rescheduled>=1, errors=0
|
||||
```
|
||||
|
||||
**Pass criteria:**
|
||||
|
||||
* `errors = 0`
|
||||
* `missed >= 1`
|
||||
* `rescheduled >= 1`
|
||||
* Script prints:
|
||||
> `✅ TEST 2 PASSED: Past alarms detected and next occurrence scheduled (missed=<m>, rescheduled=<r>).`
|
||||
|
||||
If `missed >= 1` but `rescheduled = 0`, script warns that reschedule logic may be incomplete.
|
||||
|
||||
---
|
||||
|
||||
### 4.3 TEST 3 – Boot with No Schedules
|
||||
|
||||
**Goal:**
|
||||
|
||||
Verify boot recovery handles an **empty DB / no schedules** safely and does **not** schedule anything.
|
||||
|
||||
**Script flow:**
|
||||
|
||||
1. **Uninstall app to clear DB/state**
|
||||
* Script calls:
|
||||
```bash
|
||||
adb uninstall com.timesafari.dailynotification
|
||||
```
|
||||
|
||||
2. **Reinstall APK**
|
||||
* Script reinstalls `app-debug.apk`.
|
||||
|
||||
3. **Launch app WITHOUT scheduling anything**
|
||||
* Script launches app; you do not configure or schedule.
|
||||
|
||||
4. **Collect boot/logs**
|
||||
* Script reads `DNP-REACTIVATION` logs and checks:
|
||||
* if there are no logs, or
|
||||
* if there's a "No schedules found / present" message, or
|
||||
* if `scenario=NONE` and `rescheduled=0`.
|
||||
|
||||
**Expected patterns:**
|
||||
|
||||
* *Ideal simple case:* **No** `DNP-REACTIVATION` logs at all, or:
|
||||
* Explicit message in logs:
|
||||
```text
|
||||
DNP-REACTIVATION: ... No schedules found ...
|
||||
```
|
||||
|
||||
**Pass criteria (as per script):**
|
||||
|
||||
* If **no logs**:
|
||||
* Pass: `TEST 3 PASSED: No recovery logs when there are no schedules (safe behavior).`
|
||||
* If logs exist:
|
||||
* Contains `No schedules found` / `No schedules present` **and** `rescheduled=0`, or
|
||||
* `scenario = NONE` and `rescheduled = 0`.
|
||||
|
||||
Any case where `rescheduled > 0` with an empty DB is flagged as a warning (boot recovery misfiring).
|
||||
|
||||
---
|
||||
|
||||
### 4.4 TEST 4 – Silent Boot Recovery (App Never Opened)
|
||||
|
||||
**Goal:**
|
||||
|
||||
Verify that boot recovery **occurs silently**, recreating alarms **without opening the app** after reboot.
|
||||
|
||||
**Script flow:**
|
||||
|
||||
1. **Launch app and configure plugin**
|
||||
* Same plugin status flow:
|
||||
* Ensure both plugin checks are ✅.
|
||||
* Schedule a future notification via UI.
|
||||
|
||||
2. **Verify alarms are scheduled**
|
||||
* Script shows alarms and counts (`before_count`).
|
||||
|
||||
3. **Reboot emulator**
|
||||
* Script runs `reboot_emulator` and explicitly warns:
|
||||
* Do **not** open the app after reboot.
|
||||
* After emulator returns, script instructs you to **not touch the app UI**.
|
||||
|
||||
4. **Collect boot recovery logs**
|
||||
* Script gathers and parses `DNP-REACTIVATION` lines.
|
||||
|
||||
5. **Verify alarms were recreated without app launch**
|
||||
* Script calls `show_alarms` and `count_alarms` again.
|
||||
* Uses `rescheduled` + alarm count to decide.
|
||||
|
||||
**Pass criteria (as per script):**
|
||||
|
||||
* `rescheduled > 0` after boot, and
|
||||
* Alarm count after boot is > 0, and
|
||||
* App was **never** launched by the user after reboot.
|
||||
|
||||
Script prints one of:
|
||||
|
||||
```text
|
||||
✅ TEST 4 PASSED: Boot recovery occurred silently and alarms were recreated (rescheduled=<n>) without app launch.
|
||||
|
||||
✅ TEST 4 PASSED: Boot recovery occurred silently (rescheduled=<n>), but alarm count check unclear.
|
||||
```
|
||||
|
||||
If boot recovery logs are present but no alarms appear, script warns; if no boot-recovery logs are found at all, script suggests verifying the boot receiver and BOOT_COMPLETED permission.
|
||||
|
||||
---
|
||||
|
||||
## 5. Overall Summary Section (from Script)
|
||||
|
||||
At the end, the script prints:
|
||||
|
||||
```text
|
||||
TEST 1: Boot with Future Alarms
|
||||
- Check logs for boot recovery and rescheduled>0
|
||||
|
||||
TEST 2: Boot with Past Alarms
|
||||
- Check logs for missed>=1 and rescheduled>=1
|
||||
|
||||
TEST 3: Boot with No Schedules
|
||||
- Check that no recovery runs or that an explicit 'No schedules found' is logged without rescheduling
|
||||
|
||||
TEST 4: Silent Boot Recovery
|
||||
- Check that boot recovery occurred and alarms were recreated without app launch
|
||||
```
|
||||
|
||||
Use this as a quick checklist after a run.
|
||||
|
||||
---
|
||||
|
||||
## 6. Troubleshooting Notes
|
||||
|
||||
* If **no boot recovery logs** ever appear:
|
||||
* Check that `BootReceiver` is declared and `RECEIVE_BOOT_COMPLETED` permission is set.
|
||||
* Ensure the app is installed in internal storage (not moved to SD).
|
||||
|
||||
* If **errors > 0** in summary:
|
||||
* Inspect the full `DNP-REACTIVATION` logs printed by the script.
|
||||
|
||||
* If **alarming duplication** is observed:
|
||||
* Review `runBootRecovery` and dedupe logic around re-scheduling.
|
||||
|
||||
---
|
||||
|
||||
## 7. Related Documentation
|
||||
|
||||
- [Phase 3 Directive](../android-implementation-directive-phase3.md) - Implementation details
|
||||
- [Phase 3 Verification](./PHASE3-VERIFICATION.md) - Verification report
|
||||
- [Phase 1 Testing Guide](./PHASE1-EMULATOR-TESTING.md) - Prerequisite testing
|
||||
- [Phase 2 Testing Guide](./PHASE2-EMULATOR-TESTING.md) - Prerequisite testing
|
||||
- [Activation Guide](./ACTIVATION-GUIDE.md) - How to use directives
|
||||
- [Plugin Requirements](./03-plugin-requirements.md) - Requirements Phase 3 implements
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for testing (Phase 3 implementation pending)
|
||||
**Last Updated**: November 2025
|
||||
@@ -1,201 +0,0 @@
|
||||
# Phase 3 – Boot-Time Recovery Verification
|
||||
|
||||
**Plugin:** Daily Notification Plugin
|
||||
**Scope:** Boot-Time Recovery (Recreate Alarms After Reboot)
|
||||
**Related Docs:**
|
||||
- `android-implementation-directive-phase3.md`
|
||||
- `PHASE3-EMULATOR-TESTING.md`
|
||||
- `test-phase3.sh`
|
||||
- `000-UNIFIED-ALARM-DIRECTIVE.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Objective
|
||||
|
||||
Phase 3 confirms that the Daily Notification Plugin:
|
||||
|
||||
1. Reconstructs all daily notification alarms after a **full device reboot**.
|
||||
2. Correctly handles **past** vs **future** schedules:
|
||||
- Past: mark as missed, schedule next occurrence
|
||||
- Future: simply recreate alarms
|
||||
3. Handles **empty DB / no schedules** without misfiring recovery.
|
||||
4. Performs **silent boot recovery** (no app launch required) when schedules exist.
|
||||
5. Logs a consistent, machine-readable summary:
|
||||
- `scenario`
|
||||
- `missed`
|
||||
- `rescheduled`
|
||||
- `verified`
|
||||
- `errors`
|
||||
|
||||
Verification is performed via the emulator harness:
|
||||
|
||||
```bash
|
||||
cd test-apps/android-test-app
|
||||
./test-phase3.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Test Matrix (From Script)
|
||||
|
||||
| ID | Scenario | Script Test | Expected Behavior | Result | Notes |
|
||||
| --- | --------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------ | ----- |
|
||||
| 3.1 | Boot with Future Alarms | TEST 1 – Boot with Future Alarms | `scenario=BOOT`, `rescheduled>0`, `errors=0`; alarms present after boot | ☐ | |
|
||||
| 3.2 | Boot with Past Alarms | TEST 2 – Boot with Past Alarms | `missed>=1` and `rescheduled>=1`, `errors=0`; past schedules detected and next occurrences scheduled | ☐ | |
|
||||
| 3.3 | Boot with No Schedules (Empty DB) | TEST 3 – Boot with No Schedules | Either no recovery logs **or** explicit "No schedules found/present" or `scenario=NONE` with `rescheduled=0`, `errors=0` | ☐ | |
|
||||
| 3.4 | Silent Boot Recovery (App Never Opened) | TEST 4 – Silent Boot Recovery (App Never Opened) | `rescheduled>0`, alarms present after boot, and no user launch required; `errors=0` | ☐ | |
|
||||
|
||||
Fill **Result** and **Notes** after running `test-phase3.sh` on your baseline emulator/device.
|
||||
|
||||
---
|
||||
|
||||
## 3. Expected Log Patterns
|
||||
|
||||
The script filters logs with:
|
||||
|
||||
```bash
|
||||
adb logcat -d | grep "DNP-REACTIVATION"
|
||||
```
|
||||
|
||||
### 3.1 Boot with Future Alarms (3.1 / TEST 1)
|
||||
|
||||
* Typical logs:
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: Starting boot recovery
|
||||
DNP-REACTIVATION: Loaded <N> schedules from DB
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <time>
|
||||
DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled=<r>, verified=0, errors=0
|
||||
```
|
||||
|
||||
* The script interprets this as:
|
||||
* `scenario = BOOT` (via "Starting boot recovery" or "boot recovery" text or `Detected scenario: BOOT`)
|
||||
* `rescheduled > 0`
|
||||
* `errors = 0`
|
||||
|
||||
### 3.2 Boot with Past Alarms (3.2 / TEST 2)
|
||||
|
||||
* Typical logs:
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: Starting boot recovery
|
||||
DNP-REACTIVATION: Loaded <N> schedules from DB
|
||||
DNP-REACTIVATION: Marked missed notification: daily_<id>
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <next_time>
|
||||
DNP-REACTIVATION: Boot recovery complete: missed=<m>, rescheduled=<r>, verified=0, errors=0
|
||||
```
|
||||
|
||||
* The script parses `missed` and `rescheduled` and passes when:
|
||||
* `missed >= 1`
|
||||
* `rescheduled >= 1`
|
||||
* `errors = 0`
|
||||
|
||||
### 3.3 Boot with No Schedules (3.3 / TEST 3)
|
||||
|
||||
Two acceptable patterns:
|
||||
|
||||
1. **No `DNP-REACTIVATION` logs at all** → safe behavior
|
||||
2. Explicit "no schedules" logs:
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: ... No schedules found ...
|
||||
```
|
||||
|
||||
or a neutral scenario:
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: ... scenario=NONE ...
|
||||
DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled=0, verified=0, errors=0
|
||||
```
|
||||
|
||||
The script passes when:
|
||||
|
||||
* Either `logs` are empty, or
|
||||
* Logs contain "No schedules found / present" with `rescheduled=0`, or
|
||||
* `scenario=NONE` and `rescheduled=0`.
|
||||
|
||||
Any `rescheduled>0` in this state is flagged as a potential boot-recovery misfire.
|
||||
|
||||
### 3.4 Silent Boot Recovery (3.4 / TEST 4)
|
||||
|
||||
* Expected:
|
||||
|
||||
```text
|
||||
DNP-REACTIVATION: Starting boot recovery
|
||||
DNP-REACTIVATION: Loaded <N> schedules from DB
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <time>
|
||||
DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled=<r>, verified=0, errors=0
|
||||
```
|
||||
|
||||
* After reboot:
|
||||
* `count_alarms` > 0
|
||||
* User **did not** relaunch the app manually
|
||||
|
||||
Script passes if:
|
||||
|
||||
* `rescheduled>0`, and
|
||||
* Alarm count after boot is > 0, and
|
||||
* Boot recovery is detected from logs (via "Starting boot recovery"/"boot recovery" or scenario).
|
||||
|
||||
---
|
||||
|
||||
## 4. Latest Known Good Run (Template)
|
||||
|
||||
> Fill this in after your first clean emulator run.
|
||||
|
||||
**Environment**
|
||||
|
||||
* Device: Pixel 8 API 34 (Android 14)
|
||||
* App ID: `com.timesafari.dailynotification`
|
||||
* Build: Debug `app-debug.apk` from commit `<GIT_HASH>`
|
||||
* Script: `./test-phase3.sh`
|
||||
* Date: 2025-11-XX
|
||||
|
||||
**Observed Results**
|
||||
|
||||
* ☐ **3.1 – Boot with Future Alarms**
|
||||
* `scenario=BOOT`
|
||||
* `missed=0, rescheduled=<r>, errors=0`
|
||||
|
||||
* ☐ **3.2 – Boot with Past Alarms**
|
||||
* `missed=<m>=1`, `rescheduled=<r>≥1`, `errors=0`
|
||||
|
||||
* ☐ **3.3 – Boot with No Schedules**
|
||||
* Either no logs, or explicit "No schedules found" with `rescheduled=0`
|
||||
|
||||
* ☐ **3.4 – Silent Boot Recovery**
|
||||
* `rescheduled>0`, alarms present after boot, app not opened
|
||||
|
||||
**Conclusion:**
|
||||
|
||||
> Phase 3 **Boot-Time Recovery** is successfully verified on emulator using `test-phase3.sh`. This is the canonical baseline for future regression testing and refactors to `ReactivationManager` and `BootReceiver`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Overall Status
|
||||
|
||||
> Update once the first emulator run is complete.
|
||||
|
||||
* **Implementation Status:** ☐ Pending / ✅ Implemented (Boot receiver + `runBootRecovery`)
|
||||
* **Test Harness:** ✅ `test-phase3.sh` in `test-apps/android-test-app`
|
||||
* **Emulator Verification:** ☐ Pending / ✅ Completed
|
||||
|
||||
Once all test cases pass:
|
||||
|
||||
> **Overall Status:** ✅ **VERIFIED** – Phase 3 boot-time recovery is implemented and emulator-tested, aligned with `android-implementation-directive-phase3.md` and the unified alarm directive.
|
||||
|
||||
---
|
||||
|
||||
## 6. Related Documentation
|
||||
|
||||
- [Phase 3 Directive](../android-implementation-directive-phase3.md) - Implementation details
|
||||
- [Phase 3 Emulator Testing](./PHASE3-EMULATOR-TESTING.md) - Test procedures
|
||||
- [Phase 1 Verification](./PHASE1-VERIFICATION.md) - Prerequisite verification
|
||||
- [Phase 2 Verification](./PHASE2-VERIFICATION.md) - Prerequisite verification
|
||||
- [Plugin Requirements](./03-plugin-requirements.md) - Requirements this phase implements
|
||||
- [Platform Capability Reference](./01-platform-capability-reference.md) - OS-level facts
|
||||
|
||||
---
|
||||
|
||||
**Status**: ☐ **PENDING** – Phase 3 implementation and testing pending
|
||||
**Last Updated**: November 2025
|
||||
@@ -1,248 +0,0 @@
|
||||
# Android Alarm Persistence, Recovery, and Limitations
|
||||
|
||||
**⚠️ DEPRECATED**: This document has been superseded by [01-platform-capability-reference.md](./alarms/01-platform-capability-reference.md) as part of the unified alarm documentation structure.
|
||||
|
||||
**See**: [Unified Alarm Directive](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md) for the new documentation structure.
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: **DEPRECATED** - Superseded by unified structure
|
||||
|
||||
## Purpose
|
||||
|
||||
This document provides a **clean, consolidated, engineering-grade directive** summarizing Android's abilities and limitations for remembering, firing, and restoring alarms across:
|
||||
|
||||
- App kills
|
||||
- Swipes from recents
|
||||
- Device reboot
|
||||
- **Force stop**
|
||||
- User-triggered reactivation
|
||||
|
||||
This is the actionable version you can plug directly into your architecture docs.
|
||||
|
||||
---
|
||||
|
||||
## 1. Core Principle
|
||||
|
||||
Android does **not** guarantee persistence of alarms across process death, swipes, or reboot.
|
||||
|
||||
It is the app's responsibility to **persist alarm definitions** and **re-schedule them** under allowed system conditions.
|
||||
|
||||
The following directives outline **exactly what is possible** and **what is impossible**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Allowed Behaviors (What *Can* Work)
|
||||
|
||||
### 2.1 Alarms survive UI kills (swipe from recents)
|
||||
|
||||
`AlarmManager.setExactAndAllowWhileIdle(...)` alarms **will fire** even after:
|
||||
|
||||
- App is swiped away
|
||||
- App process is killed by the OS
|
||||
|
||||
The OS recreates your app's process to deliver the `PendingIntent`.
|
||||
|
||||
**Directive:**
|
||||
|
||||
Use `setExactAndAllowWhileIdle` for alarm execution.
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Alarms can be preserved across device reboot
|
||||
|
||||
Android wipes all alarms on reboot, but **you may recreate them**.
|
||||
|
||||
**Directive:**
|
||||
|
||||
1. Persist all alarms in storage (Room DB or SharedPreferences).
|
||||
2. Add a `BOOT_COMPLETED` / `LOCKED_BOOT_COMPLETED` broadcast receiver.
|
||||
3. On boot, load all enabled alarms and reschedule them using AlarmManager.
|
||||
|
||||
**Permissions required:**
|
||||
|
||||
- `RECEIVE_BOOT_COMPLETED`
|
||||
|
||||
**Conditions:**
|
||||
|
||||
- User must have launched your app at least once before reboot to grant boot receiver execution.
|
||||
|
||||
---
|
||||
|
||||
### 2.3 Alarms can fire full-screen notifications and wake the device
|
||||
|
||||
**Directive:**
|
||||
|
||||
Implement `setFullScreenIntent(...)`, use an IMPORTANCE_HIGH channel with `CATEGORY_ALARM`.
|
||||
|
||||
This allows Clock-app–style alarms even when the app is not foregrounded.
|
||||
|
||||
---
|
||||
|
||||
### 2.4 Alarms can be restored after app restart
|
||||
|
||||
If the user re-opens the app (direct user action), you may:
|
||||
|
||||
- Scan the persistent DB
|
||||
- Detect "missed" alarms
|
||||
- Reschedule future alarms
|
||||
- Fire "missed alarm" notifications
|
||||
- Reconstruct WorkManager/JobScheduler tasks wiped by OS
|
||||
|
||||
**Directive:**
|
||||
|
||||
Create a `ReactivationManager` that runs on every app launch and recomputes the correct alarm state.
|
||||
|
||||
---
|
||||
|
||||
## 3. Forbidden Behaviors (What *Cannot* Work)
|
||||
|
||||
### 3.1 You cannot survive "Force Stop"
|
||||
|
||||
**Settings → Apps → YourApp → Force Stop** triggers:
|
||||
|
||||
- Removal of all alarms
|
||||
- Removal of WorkManager tasks
|
||||
- Blocking of all broadcast receivers (including BOOT_COMPLETED)
|
||||
- Blocking of all JobScheduler jobs
|
||||
- Blocking of AlarmManager callbacks
|
||||
- Your app will NOT run until the user manually launches it again
|
||||
|
||||
**Directive:**
|
||||
|
||||
Accept that FORCE STOP is a hard kill.
|
||||
|
||||
No scheduling, alarms, jobs, or receivers may execute afterward.
|
||||
|
||||
---
|
||||
|
||||
### 3.2 You cannot auto-resume after "Force Stop"
|
||||
|
||||
You may only resume tasks when:
|
||||
|
||||
- The user opens your app
|
||||
- The user taps a notification belonging to your app
|
||||
- The user interacts with a widget/deep link
|
||||
- Another app explicitly targets your component
|
||||
|
||||
**Directive:**
|
||||
|
||||
Provide user-facing reactivation pathways (icon, widget, notification).
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Alarms cannot be preserved solely in RAM
|
||||
|
||||
Android can kill your app's RAM state at any time.
|
||||
|
||||
**Directive:**
|
||||
|
||||
All alarm data must be persisted in durable storage.
|
||||
|
||||
---
|
||||
|
||||
### 3.4 You cannot bypass Doze or battery optimization restrictions without permission
|
||||
|
||||
Doze may defer inexact alarms; exact alarms with `setExactAndAllowWhileIdle` are allowed.
|
||||
|
||||
**Directive:**
|
||||
|
||||
Request `SCHEDULE_EXACT_ALARM` on Android 12+.
|
||||
|
||||
---
|
||||
|
||||
## 4. Required Implementation Components
|
||||
|
||||
### 4.1 Persistent Storage
|
||||
|
||||
Create a table or serialized structure for alarms:
|
||||
|
||||
```
|
||||
id: Int
|
||||
timeMillis: Long
|
||||
repeat: NONE | DAILY | WEEKLY | CUSTOM
|
||||
label: String
|
||||
enabled: Boolean
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Alarm Scheduling
|
||||
|
||||
Use:
|
||||
|
||||
```kotlin
|
||||
alarmManager.setExactAndAllowWhileIdle(
|
||||
AlarmManager.RTC_WAKEUP,
|
||||
triggerAtMillis,
|
||||
pendingIntent
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Boot Receiver
|
||||
|
||||
Reschedules alarms from storage.
|
||||
|
||||
---
|
||||
|
||||
### 4.4 Reactivation Manager
|
||||
|
||||
Runs on **every app launch** and performs:
|
||||
|
||||
- Load pending alarms
|
||||
- Detect overdue alarms
|
||||
- Reschedule future alarms
|
||||
- Trigger notifications for missed alarms
|
||||
|
||||
---
|
||||
|
||||
### 4.5 Full-Screen Alarm UI
|
||||
|
||||
Use a `BroadcastReceiver` → Notification with full-screen intent → Activity.
|
||||
|
||||
---
|
||||
|
||||
## 5. Summary of Android Alarm Capability Matrix
|
||||
|
||||
| Scenario | Will Alarm Fire? | Reason |
|
||||
| --------------------------------------- | --------------------------------------- | --------------------------------------------------------------- |
|
||||
| **Swipe from Recents** | ✅ Yes | AlarmManager resurrects the app process |
|
||||
| **App silently killed by OS** | ✅ Yes | AlarmManager still holds scheduled alarms |
|
||||
| **Device Reboot** | ❌ No (auto) / ✅ Yes (if you reschedule) | Alarms wiped on reboot |
|
||||
| **Doze Mode** | ⚠️ Only "exact" alarms | Must use `setExactAndAllowWhileIdle` |
|
||||
| **Force Stop** | ❌ Never | Android blocks all callbacks + receivers until next user launch |
|
||||
| **User reopens app** | ✅ You may reschedule & recover | All logic must be implemented by app |
|
||||
| **PendingIntent from user interaction** | ✅ If triggered by user | User action unlocks the app |
|
||||
|
||||
---
|
||||
|
||||
## 6. Final Directive
|
||||
|
||||
> **Design alarm behavior with the assumption that Android will destroy all scheduled work on reboot or force-stop.
|
||||
>
|
||||
> Persist all alarm definitions. On every boot or app reactivation, reconstruct and reschedule alarms.
|
||||
>
|
||||
> Never rely on the OS to preserve alarms except across UI process kills.
|
||||
>
|
||||
> Accept that "force stop" is a hard stop that cannot be bypassed.**
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Boot Receiver Testing Guide](./boot-receiver-testing-guide.md)
|
||||
- [App Startup Recovery Solution](./app-startup-recovery-solution.md)
|
||||
- [Reboot Testing Procedure](./reboot-testing-procedure.md)
|
||||
|
||||
---
|
||||
|
||||
## Future Directives
|
||||
|
||||
Potential follow-up directives:
|
||||
|
||||
- **How to implement the minimal alarm system**
|
||||
- **How to implement a Clock-style robust alarm system**
|
||||
- **How to map this to your own app's architecture**
|
||||
|
||||
@@ -1,712 +0,0 @@
|
||||
# Android Implementation Directive: Phase 1 - Cold Start Recovery
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Phase 1 - Minimal Viable Recovery
|
||||
**Version**: 1.0.0
|
||||
**Last Synced With Plugin Version**: v1.1.0
|
||||
|
||||
**Implements**: [Plugin Requirements §3.1.2 - App Cold Start](./alarms/03-plugin-requirements.md#312-app-cold-start)
|
||||
|
||||
## Purpose
|
||||
|
||||
Phase 1 implements **minimal viable app launch recovery** for cold start scenarios. This focuses on detecting and handling missed notifications when the app launches after the process was killed.
|
||||
|
||||
**Scope**: Phase 1 implements **cold start recovery only**. Force stop detection, warm start optimization, and boot receiver enhancements are **out of scope** for this phase and deferred to later phases.
|
||||
|
||||
**Reference**:
|
||||
- [Plugin Requirements](./alarms/03-plugin-requirements.md) - Requirements this phase implements
|
||||
- [Platform Capability Reference](./alarms/01-platform-capability-reference.md) - OS-level facts
|
||||
- [Full Implementation Directive](./android-implementation-directive.md) - Complete scope
|
||||
- [Phase 2: Force Stop Recovery](./android-implementation-directive-phase2.md) - Next phase
|
||||
- [Phase 3: Boot Receiver Enhancement](./android-implementation-directive-phase3.md) - Final phase
|
||||
|
||||
---
|
||||
|
||||
## 1. Acceptance Criteria
|
||||
|
||||
### 1.1 Definition of Done
|
||||
|
||||
**Phase 1 is complete when:**
|
||||
|
||||
1. ✅ **On cold start, missed notifications are detected**
|
||||
- Notifications with `scheduled_time < currentTime` and `delivery_status != 'delivered'` are identified
|
||||
- Detection runs automatically on app launch (via `DailyNotificationPlugin.load()`)
|
||||
- Detection completes within 2 seconds (non-blocking)
|
||||
|
||||
2. ✅ **Missed notifications are marked in database**
|
||||
- `delivery_status` updated to `'missed'`
|
||||
- `last_delivery_attempt` updated to current time
|
||||
- Status change logged in history table
|
||||
|
||||
3. ✅ **Future alarms are verified and rescheduled if missing**
|
||||
- All enabled `notify` schedules checked against AlarmManager
|
||||
- Missing alarms rescheduled using existing `NotifyReceiver.scheduleExactNotification()`
|
||||
- No duplicate alarms created (verified before rescheduling)
|
||||
|
||||
4. ✅ **Recovery never crashes the app**
|
||||
- All exceptions caught and logged
|
||||
- Database errors don't propagate
|
||||
- Invalid data handled gracefully
|
||||
|
||||
5. ✅ **Recovery is observable**
|
||||
- All recovery actions logged with `DNP-REACTIVATION` tag
|
||||
- Recovery metrics recorded in history table
|
||||
- Logs include counts: missed detected, rescheduled, errors
|
||||
|
||||
### 1.2 Success Metrics
|
||||
|
||||
| Metric | Target | Measurement |
|
||||
|--------|--------|-------------|
|
||||
| Recovery execution time | < 2 seconds | Log timestamp difference |
|
||||
| Missed detection accuracy | 100% | Manual verification via logs |
|
||||
| Reschedule success rate | > 95% | History table outcome field |
|
||||
| Crash rate | 0% | No exceptions propagate to app |
|
||||
|
||||
### 1.3 Out of Scope (Phase 1)
|
||||
|
||||
- ❌ Force stop detection (Phase 2)
|
||||
- ❌ Warm start optimization (Phase 2)
|
||||
- ❌ Boot receiver missed alarm handling (Phase 2)
|
||||
- ❌ Callback event emission (Phase 2)
|
||||
- ❌ Fetch work recovery (Phase 2)
|
||||
|
||||
---
|
||||
|
||||
## 2. Implementation: ReactivationManager
|
||||
|
||||
### 2.1 Create New File
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/ReactivationManager.kt`
|
||||
|
||||
**Purpose**: Centralized cold start recovery logic
|
||||
|
||||
### 2.2 Class Structure
|
||||
|
||||
```kotlin
|
||||
package com.timesafari.dailynotification
|
||||
|
||||
import android.content.Context
|
||||
import android.util.Log
|
||||
import kotlinx.coroutines.CoroutineScope
|
||||
import kotlinx.coroutines.Dispatchers
|
||||
import kotlinx.coroutines.launch
|
||||
import kotlinx.coroutines.withTimeout
|
||||
import java.util.concurrent.TimeUnit
|
||||
|
||||
/**
|
||||
* Manages recovery of alarms and notifications on app launch
|
||||
* Phase 1: Cold start recovery only
|
||||
*
|
||||
* @author Matthew Raymer
|
||||
* @version 1.0.0
|
||||
*/
|
||||
class ReactivationManager(private val context: Context) {
|
||||
|
||||
companion object {
|
||||
private const val TAG = "DNP-REACTIVATION"
|
||||
private const val RECOVERY_TIMEOUT_SECONDS = 2L
|
||||
}
|
||||
|
||||
/**
|
||||
* Perform recovery on app launch
|
||||
* Phase 1: Calls only performColdStartRecovery() when DB is non-empty
|
||||
*
|
||||
* Scenario detection is not implemented in Phase 1 - all app launches
|
||||
* with non-empty DB are treated as cold start. Force stop, boot, and
|
||||
* warm start handling are deferred to Phase 2.
|
||||
*
|
||||
* **Correction**: Must not run when DB is empty (first launch).
|
||||
*
|
||||
* Runs asynchronously with timeout to avoid blocking app startup
|
||||
*
|
||||
* Rollback Safety: If recovery fails, app continues normally
|
||||
*/
|
||||
fun performRecovery() {
|
||||
CoroutineScope(Dispatchers.IO).launch {
|
||||
try {
|
||||
withTimeout(TimeUnit.SECONDS.toMillis(RECOVERY_TIMEOUT_SECONDS)) {
|
||||
Log.i(TAG, "Starting app launch recovery (Phase 1: cold start only)")
|
||||
|
||||
// Correction: Short-circuit if DB is empty (first launch)
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val dbSchedules = db.scheduleDao().getEnabled()
|
||||
|
||||
if (dbSchedules.isEmpty()) {
|
||||
Log.i(TAG, "No schedules present — skipping recovery (first launch)")
|
||||
return@withTimeout
|
||||
}
|
||||
|
||||
val result = performColdStartRecovery()
|
||||
Log.i(TAG, "App launch recovery completed: $result")
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
// Rollback: Log error but don't crash
|
||||
Log.e(TAG, "Recovery failed (non-fatal): ${e.message}", e)
|
||||
// Record failure in history (best effort, don't fail if this fails)
|
||||
try {
|
||||
recordRecoveryFailure(e)
|
||||
} catch (historyError: Exception) {
|
||||
Log.w(TAG, "Failed to record recovery failure in history", historyError)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ... implementation methods below ...
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 Cold Start Recovery
|
||||
|
||||
**Platform Reference**: [Android §2.1.4](./alarms/01-platform-capability-reference.md#214-alarms-can-be-restored-after-app-restart) - Alarms can be restored after app restart
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Perform cold start recovery
|
||||
*
|
||||
* Steps:
|
||||
* 1. Detect missed notifications (scheduled_time < now, not delivered)
|
||||
* 2. Mark missed notifications in database
|
||||
* 3. Verify future alarms are scheduled
|
||||
* 4. Reschedule missing future alarms
|
||||
*
|
||||
* @return RecoveryResult with counts
|
||||
*/
|
||||
private suspend fun performColdStartRecovery(): RecoveryResult {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val currentTime = System.currentTimeMillis()
|
||||
|
||||
Log.i(TAG, "Cold start recovery: checking for missed notifications")
|
||||
|
||||
// Step 1: Detect missed notifications
|
||||
val missedNotifications = try {
|
||||
db.notificationContentDao().getNotificationsReadyForDelivery(currentTime)
|
||||
.filter { it.deliveryStatus != "delivered" }
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to query missed notifications", e)
|
||||
emptyList()
|
||||
}
|
||||
|
||||
var missedCount = 0
|
||||
var missedErrors = 0
|
||||
|
||||
// Step 2: Mark missed notifications
|
||||
missedNotifications.forEach { notification ->
|
||||
try {
|
||||
// Data integrity check: verify notification is valid
|
||||
if (notification.id.isBlank()) {
|
||||
Log.w(TAG, "Skipping invalid notification: empty ID")
|
||||
return@forEach
|
||||
}
|
||||
|
||||
// Update delivery status
|
||||
notification.deliveryStatus = "missed"
|
||||
notification.lastDeliveryAttempt = currentTime
|
||||
notification.deliveryAttempts = (notification.deliveryAttempts ?: 0) + 1
|
||||
|
||||
db.notificationContentDao().updateNotification(notification)
|
||||
missedCount++
|
||||
|
||||
Log.d(TAG, "Marked missed notification: ${notification.id}")
|
||||
} catch (e: Exception) {
|
||||
missedErrors++
|
||||
Log.e(TAG, "Failed to mark missed notification: ${notification.id}", e)
|
||||
// Continue processing other notifications
|
||||
}
|
||||
}
|
||||
|
||||
// Step 3: Verify and reschedule future alarms
|
||||
val schedules = try {
|
||||
db.scheduleDao().getEnabled()
|
||||
.filter { it.kind == "notify" }
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to query schedules", e)
|
||||
emptyList()
|
||||
}
|
||||
|
||||
var rescheduledCount = 0
|
||||
var verifiedCount = 0
|
||||
var rescheduleErrors = 0
|
||||
|
||||
schedules.forEach { schedule ->
|
||||
try {
|
||||
// Data integrity check: verify schedule is valid
|
||||
if (schedule.id.isBlank() || schedule.nextRunAt == null) {
|
||||
Log.w(TAG, "Skipping invalid schedule: ${schedule.id}")
|
||||
return@forEach
|
||||
}
|
||||
|
||||
val nextRunTime = schedule.nextRunAt!!
|
||||
|
||||
// Only check future alarms
|
||||
if (nextRunTime >= currentTime) {
|
||||
// Verify alarm is scheduled
|
||||
val isScheduled = NotifyReceiver.isAlarmScheduled(context, nextRunTime)
|
||||
|
||||
if (isScheduled) {
|
||||
verifiedCount++
|
||||
Log.d(TAG, "Verified scheduled alarm: ${schedule.id} at $nextRunTime")
|
||||
} else {
|
||||
// Reschedule missing alarm
|
||||
rescheduleAlarm(schedule, nextRunTime, db)
|
||||
rescheduledCount++
|
||||
Log.i(TAG, "Rescheduled missing alarm: ${schedule.id} at $nextRunTime")
|
||||
}
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
rescheduleErrors++
|
||||
Log.e(TAG, "Failed to verify/reschedule: ${schedule.id}", e)
|
||||
// Continue processing other schedules
|
||||
}
|
||||
}
|
||||
|
||||
// Step 4: Record recovery in history
|
||||
val result = RecoveryResult(
|
||||
missedCount = missedCount,
|
||||
rescheduledCount = rescheduledCount,
|
||||
verifiedCount = verifiedCount,
|
||||
errors = missedErrors + rescheduleErrors
|
||||
)
|
||||
|
||||
recordRecoveryHistory(db, "cold_start", result)
|
||||
|
||||
Log.i(TAG, "Cold start recovery complete: $result")
|
||||
return result
|
||||
}
|
||||
|
||||
/**
|
||||
* Data class for recovery results
|
||||
*/
|
||||
private data class RecoveryResult(
|
||||
val missedCount: Int,
|
||||
val rescheduledCount: Int,
|
||||
val verifiedCount: Int,
|
||||
val errors: Int
|
||||
) {
|
||||
override fun toString(): String {
|
||||
return "missed=$missedCount, rescheduled=$rescheduledCount, verified=$verifiedCount, errors=$errors"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 Helper Methods
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Reschedule an alarm
|
||||
*
|
||||
* Data integrity: Validates schedule before rescheduling
|
||||
*/
|
||||
private suspend fun rescheduleAlarm(
|
||||
schedule: Schedule,
|
||||
nextRunTime: Long,
|
||||
db: DailyNotificationDatabase
|
||||
) {
|
||||
try {
|
||||
// Use existing BootReceiver logic for calculating next run time
|
||||
// For now, use schedule.nextRunAt directly
|
||||
val config = UserNotificationConfig(
|
||||
enabled = schedule.enabled,
|
||||
schedule = schedule.cron ?: schedule.clockTime ?: "0 9 * * *",
|
||||
title = "Daily Notification",
|
||||
body = "Your daily update is ready",
|
||||
sound = true,
|
||||
vibration = true,
|
||||
priority = "normal"
|
||||
)
|
||||
|
||||
NotifyReceiver.scheduleExactNotification(context, nextRunTime, config)
|
||||
|
||||
// Update schedule in database (best effort)
|
||||
try {
|
||||
db.scheduleDao().updateRunTimes(schedule.id, schedule.lastRunAt, nextRunTime)
|
||||
} catch (e: Exception) {
|
||||
Log.w(TAG, "Failed to update schedule in database: ${schedule.id}", e)
|
||||
// Don't fail rescheduling if DB update fails
|
||||
}
|
||||
|
||||
Log.i(TAG, "Rescheduled alarm: ${schedule.id} for $nextRunTime")
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to reschedule alarm: ${schedule.id}", e)
|
||||
throw e // Re-throw to be caught by caller
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Record recovery in history
|
||||
*
|
||||
* Rollback safety: If history recording fails, log warning but don't fail recovery
|
||||
*/
|
||||
private suspend fun recordRecoveryHistory(
|
||||
db: DailyNotificationDatabase,
|
||||
scenario: String,
|
||||
result: RecoveryResult
|
||||
) {
|
||||
try {
|
||||
db.historyDao().insert(
|
||||
History(
|
||||
refId = "recovery_${System.currentTimeMillis()}",
|
||||
kind = "recovery",
|
||||
occurredAt = System.currentTimeMillis(),
|
||||
outcome = if (result.errors == 0) "success" else "partial",
|
||||
diagJson = """
|
||||
{
|
||||
"scenario": "$scenario",
|
||||
"missed_count": ${result.missedCount},
|
||||
"rescheduled_count": ${result.rescheduledCount},
|
||||
"verified_count": ${result.verifiedCount},
|
||||
"errors": ${result.errors}
|
||||
}
|
||||
""".trimIndent()
|
||||
)
|
||||
)
|
||||
} catch (e: Exception) {
|
||||
Log.w(TAG, "Failed to record recovery history (non-fatal)", e)
|
||||
// Don't throw - history recording failure shouldn't fail recovery
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Record recovery failure in history
|
||||
*/
|
||||
private suspend fun recordRecoveryFailure(e: Exception) {
|
||||
try {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
db.historyDao().insert(
|
||||
History(
|
||||
refId = "recovery_failure_${System.currentTimeMillis()}",
|
||||
kind = "recovery",
|
||||
occurredAt = System.currentTimeMillis(),
|
||||
outcome = "failure",
|
||||
diagJson = """
|
||||
{
|
||||
"error": "${e.message}",
|
||||
"error_type": "${e.javaClass.simpleName}"
|
||||
}
|
||||
""".trimIndent()
|
||||
)
|
||||
)
|
||||
} catch (historyError: Exception) {
|
||||
// Silently fail - we're already in error handling
|
||||
Log.w(TAG, "Failed to record recovery failure", historyError)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Integration: DailyNotificationPlugin
|
||||
|
||||
### 3.1 Update `load()` Method
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.kt`
|
||||
|
||||
**Location**: After database initialization (line 98)
|
||||
|
||||
**Current Code**:
|
||||
```kotlin
|
||||
override fun load() {
|
||||
super.load()
|
||||
try {
|
||||
if (context == null) {
|
||||
Log.e(TAG, "Context is null, cannot initialize database")
|
||||
return
|
||||
}
|
||||
db = DailyNotificationDatabase.getDatabase(context)
|
||||
Log.i(TAG, "Daily Notification Plugin loaded successfully")
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to initialize Daily Notification Plugin", e)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Updated Code**:
|
||||
```kotlin
|
||||
override fun load() {
|
||||
super.load()
|
||||
try {
|
||||
if (context == null) {
|
||||
Log.e(TAG, "Context is null, cannot initialize database")
|
||||
return
|
||||
}
|
||||
db = DailyNotificationDatabase.getDatabase(context)
|
||||
Log.i(TAG, "Daily Notification Plugin loaded successfully")
|
||||
|
||||
// Phase 1: Perform app launch recovery (cold start only)
|
||||
// Runs asynchronously, non-blocking, with timeout
|
||||
val reactivationManager = ReactivationManager(context)
|
||||
reactivationManager.performRecovery()
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to initialize Daily Notification Plugin", e)
|
||||
// Don't throw - allow plugin to load even if recovery fails
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Integrity Checks
|
||||
|
||||
### 4.1 Validation Rules
|
||||
|
||||
**Notification Validation**:
|
||||
- ✅ `id` must not be blank
|
||||
- ✅ `scheduled_time` must be valid timestamp
|
||||
- ✅ `delivery_status` must be valid enum value
|
||||
|
||||
**Schedule Validation**:
|
||||
- ✅ `id` must not be blank
|
||||
- ✅ `kind` must be "notify" or "fetch"
|
||||
- ✅ `nextRunAt` must be set for verification
|
||||
- ✅ `enabled` must be true (filtered by DAO)
|
||||
|
||||
### 4.2 Orphaned Data Handling
|
||||
|
||||
**Orphaned Notifications** (no matching schedule):
|
||||
- Log warning but don't fail recovery
|
||||
- Mark as missed if past scheduled time
|
||||
|
||||
**Orphaned Schedules** (no matching notification content):
|
||||
- Log warning but don't fail recovery
|
||||
- Reschedule if future alarm is missing
|
||||
|
||||
**Mismatched Data**:
|
||||
- If `NotificationContentEntity.scheduled_time` doesn't match `Schedule.nextRunAt`, use `scheduled_time` for missed detection
|
||||
- Log warning for data inconsistency
|
||||
|
||||
---
|
||||
|
||||
## 5. Rollback Safety
|
||||
|
||||
### 5.1 No-Crash Guarantee
|
||||
|
||||
**All recovery operations must:**
|
||||
|
||||
1. **Catch all exceptions** - Never propagate exceptions to app
|
||||
2. **Log errors** - All failures logged with context
|
||||
3. **Continue processing** - One failure doesn't stop recovery
|
||||
4. **Timeout protection** - Recovery completes within 2 seconds or times out
|
||||
5. **Best-effort updates** - Database failures don't prevent alarm rescheduling
|
||||
|
||||
### 5.2 Error Handling Strategy
|
||||
|
||||
| Error Type | Handling | Log Level |
|
||||
|------------|----------|-----------|
|
||||
| Database query failure | Return empty list, continue | ERROR |
|
||||
| Invalid notification data | Skip notification, continue | WARN |
|
||||
| Alarm reschedule failure | Log error, continue to next | ERROR |
|
||||
| History recording failure | Log warning, don't fail | WARN |
|
||||
| Timeout | Log timeout, abort recovery | WARN |
|
||||
|
||||
### 5.3 Fallback Behavior
|
||||
|
||||
**If recovery fails completely:**
|
||||
- App continues normally
|
||||
- No alarms are lost (existing alarms remain scheduled)
|
||||
- User can manually trigger recovery via app restart
|
||||
- Error logged in history table (if possible)
|
||||
|
||||
---
|
||||
|
||||
## 6. Callback Behavior (Phase 1 - Deferred)
|
||||
|
||||
**Phase 1 does NOT emit callbacks.** Callback behavior is deferred to Phase 2.
|
||||
|
||||
**Future callback contract** (for Phase 2):
|
||||
|
||||
| Event | Fired When | Payload | Guarantees |
|
||||
|-------|------------|---------|------------|
|
||||
| `missed_notification` | Missed notification detected | `{notificationId, scheduledTime, detectedAt}` | Fired once per missed notification |
|
||||
| `recovery_complete` | Recovery finished | `{scenario, missedCount, rescheduledCount, errors}` | Fired once per recovery run |
|
||||
|
||||
**Implementation notes:**
|
||||
- Callbacks will use Capacitor event system
|
||||
- Events batched if multiple missed notifications detected
|
||||
- Callbacks fire after database updates complete
|
||||
|
||||
---
|
||||
|
||||
## 7. Versioning & Migration
|
||||
|
||||
### 7.1 Version Bump
|
||||
|
||||
**Plugin Version**: Increment patch version (e.g., `1.1.0` → `1.1.1`)
|
||||
|
||||
**Reason**: New feature (recovery), no breaking changes
|
||||
|
||||
### 7.2 Database Migration
|
||||
|
||||
**No database migration required** for Phase 1.
|
||||
|
||||
**Existing tables used:**
|
||||
- `notification_content` - Already has `delivery_status` field
|
||||
- `schedules` - Already has `nextRunAt` field
|
||||
- `history` - Already supports recovery events
|
||||
|
||||
### 7.3 Backward Compatibility
|
||||
|
||||
**Phase 1 is backward compatible:**
|
||||
- Existing alarms continue to work
|
||||
- No schema changes
|
||||
- Recovery is additive (doesn't break existing functionality)
|
||||
|
||||
---
|
||||
|
||||
## 8. Testing Requirements
|
||||
|
||||
### 8.1 Test 1: Cold Start Missed Detection
|
||||
|
||||
**Purpose**: Verify missed notifications are detected and marked.
|
||||
|
||||
**Steps**:
|
||||
1. Schedule notification for 2 minutes in future
|
||||
2. Kill app process: `adb shell am kill com.timesafari.dailynotification`
|
||||
3. Wait 5 minutes (past scheduled time)
|
||||
4. Launch app: `adb shell am start -n com.timesafari.dailynotification/.MainActivity`
|
||||
5. Check logs: `adb logcat -d | grep DNP-REACTIVATION`
|
||||
|
||||
**Expected**:
|
||||
- ✅ Log shows "Cold start recovery: checking for missed notifications"
|
||||
- ✅ Log shows "Marked missed notification: <id>"
|
||||
- ✅ Database shows `delivery_status = 'missed'`
|
||||
- ✅ History table has recovery entry
|
||||
|
||||
**Pass Criteria**: Missed notification detected and marked in database.
|
||||
|
||||
### 8.2 Test 2: Future Alarm Rescheduling
|
||||
|
||||
**Purpose**: Verify missing future alarms are rescheduled.
|
||||
|
||||
**Steps**:
|
||||
1. Schedule notification for 10 minutes in future
|
||||
2. Manually cancel alarm: `adb shell dumpsys alarm | grep timesafari` (note request code)
|
||||
3. Launch app
|
||||
4. Check logs: `adb logcat -d | grep DNP-REACTIVATION`
|
||||
5. Verify alarm rescheduled: `adb shell dumpsys alarm | grep timesafari`
|
||||
|
||||
**Expected**:
|
||||
- ✅ Log shows "Rescheduled missing alarm: <id>"
|
||||
- ✅ AlarmManager shows rescheduled alarm
|
||||
- ✅ No duplicate alarms created
|
||||
|
||||
**Pass Criteria**: Missing alarm rescheduled, no duplicates.
|
||||
|
||||
### 8.3 Test 3: Recovery Timeout
|
||||
|
||||
**Purpose**: Verify recovery times out gracefully.
|
||||
|
||||
**Steps**:
|
||||
1. Create large number of schedules (100+)
|
||||
2. Launch app
|
||||
3. Check logs for timeout
|
||||
|
||||
**Expected**:
|
||||
- ✅ Recovery completes within 2 seconds OR times out
|
||||
- ✅ App doesn't crash
|
||||
- ✅ Partial recovery logged if timeout occurs
|
||||
|
||||
**Pass Criteria**: Recovery doesn't block app launch.
|
||||
|
||||
### 8.4 Test 4: Invalid Data Handling
|
||||
|
||||
**Purpose**: Verify invalid data doesn't crash recovery.
|
||||
|
||||
**Steps**:
|
||||
1. Manually insert invalid notification (empty ID) into database
|
||||
2. Launch app
|
||||
3. Check logs
|
||||
|
||||
**Expected**:
|
||||
- ✅ Invalid notification skipped
|
||||
- ✅ Warning logged
|
||||
- ✅ Recovery continues normally
|
||||
|
||||
**Pass Criteria**: Invalid data handled gracefully.
|
||||
|
||||
### 8.4 Emulator Test Harness
|
||||
|
||||
The manual tests in §8.1–§8.3 are codified in the script `test-phase1.sh` in:
|
||||
|
||||
```bash
|
||||
test-apps/android-test-app/test-phase1.sh
|
||||
```
|
||||
|
||||
**Status:**
|
||||
|
||||
* ✅ Script implemented and polished
|
||||
* ✅ Verified on Android Emulator (Pixel 8 API 34) on 27 November 2025
|
||||
* ✅ Correctly recognizes both `verified>0` and `rescheduled>0` as PASS cases
|
||||
* ✅ Treats `DELETE_FAILED_INTERNAL_ERROR` on uninstall as non-fatal
|
||||
|
||||
For regression testing, use `PHASE1-EMULATOR-TESTING.md` + `test-phase1.sh` as the canonical procedure.
|
||||
|
||||
---
|
||||
|
||||
## 9. Implementation Checklist
|
||||
|
||||
- [ ] Create `ReactivationManager.kt` file
|
||||
- [ ] Implement `performRecovery()` with timeout
|
||||
- [ ] Implement `performColdStartRecovery()`
|
||||
- [ ] Implement missed notification detection
|
||||
- [ ] Implement missed notification marking
|
||||
- [ ] Implement future alarm verification
|
||||
- [ ] Implement missing alarm rescheduling
|
||||
- [ ] Add data integrity checks
|
||||
- [ ] Add error handling (no-crash guarantee)
|
||||
- [ ] Add recovery history recording
|
||||
- [ ] Update `DailyNotificationPlugin.load()` to call recovery
|
||||
- [ ] Test cold start missed detection
|
||||
- [ ] Test future alarm rescheduling
|
||||
- [ ] Test recovery timeout
|
||||
- [ ] Test invalid data handling
|
||||
- [ ] Verify no duplicate alarms
|
||||
- [ ] Verify recovery doesn't block app launch
|
||||
|
||||
---
|
||||
|
||||
## 10. Code References
|
||||
|
||||
**Existing Code to Reuse**:
|
||||
- `NotifyReceiver.scheduleExactNotification()` - Line 92
|
||||
- `NotifyReceiver.isAlarmScheduled()` - Line 279
|
||||
- `BootReceiver.calculateNextRunTime()` - Line 103 (for Phase 2)
|
||||
- `NotificationContentDao.getNotificationsReadyForDelivery()` - Line 99
|
||||
- `ScheduleDao.getEnabled()` - Line 298
|
||||
|
||||
**New Code to Create**:
|
||||
- `ReactivationManager.kt` - New file (Phase 1)
|
||||
|
||||
---
|
||||
|
||||
## 11. Success Criteria Summary
|
||||
|
||||
**Phase 1 is complete when:**
|
||||
|
||||
1. ✅ Missed notifications detected on cold start
|
||||
2. ✅ Missed notifications marked in database
|
||||
3. ✅ Future alarms verified and rescheduled if missing
|
||||
4. ✅ Recovery never crashes app
|
||||
5. ✅ Recovery completes within 2 seconds
|
||||
6. ✅ All tests pass
|
||||
7. ✅ No duplicate alarms created
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Unified Alarm Directive](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document
|
||||
- [Plugin Requirements](./alarms/03-plugin-requirements.md) - Requirements this phase implements
|
||||
- [Platform Capability Reference](./alarms/01-platform-capability-reference.md) - OS-level facts
|
||||
- [Plugin Behavior Exploration](./alarms/02-plugin-behavior-exploration.md) - Test scenarios
|
||||
- [Full Implementation Directive](./android-implementation-directive.md) - Complete scope (all phases)
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Incremental approach**: Phase 1 focuses on cold start only. Force stop and boot recovery in Phase 2.
|
||||
- **Safety first**: All recovery operations are non-blocking and non-fatal.
|
||||
- **Observability**: Extensive logging for debugging and monitoring.
|
||||
- **Data integrity**: Validation prevents invalid data from causing failures.
|
||||
|
||||
@@ -1,787 +0,0 @@
|
||||
# Android Implementation Directive: Phase 2 - Force Stop Detection & Recovery
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Phase 2 - Force Stop Recovery
|
||||
**Version**: 1.0.0
|
||||
**Last Synced With Plugin Version**: v1.1.0
|
||||
|
||||
**Implements**: [Plugin Requirements §3.1.4 - Force Stop Recovery](./alarms/03-plugin-requirements.md#314-force-stop-recovery-android-only)
|
||||
|
||||
## Purpose
|
||||
|
||||
Phase 2 implements **force stop detection and comprehensive recovery**. This handles the scenario where the user force-stops the app, causing all alarms to be cancelled by the OS.
|
||||
|
||||
**⚠️ IMPORTANT**: This phase **modifies and extends** the `ReactivationManager` introduced in Phase 1. Do not create a second copy; update the existing class.
|
||||
|
||||
**Prerequisites**: Phase 1 must be complete (cold start recovery implemented).
|
||||
|
||||
**Scope**: Force stop detection, scenario differentiation, and full alarm recovery.
|
||||
|
||||
**Reference**:
|
||||
- [Plugin Requirements](./alarms/03-plugin-requirements.md) - Requirements this phase implements
|
||||
- [Platform Capability Reference](./alarms/01-platform-capability-reference.md) - OS-level facts
|
||||
- [Phase 1](./android-implementation-directive-phase1.md) - Prerequisite
|
||||
- [Full Implementation Directive](./android-implementation-directive.md) - Complete scope
|
||||
|
||||
---
|
||||
|
||||
## 1. Acceptance Criteria
|
||||
|
||||
### 1.1 Definition of Done
|
||||
|
||||
**Phase 2 is complete when:**
|
||||
|
||||
1. ✅ **Force stop scenario is detected correctly**
|
||||
- Detection: `(DB schedules count > 0) && (AlarmManager alarms count == 0)`
|
||||
- Detection runs on app launch (via `ReactivationManager`)
|
||||
- False positives avoided (distinguishes from first launch)
|
||||
|
||||
2. ✅ **All past alarms are marked as missed**
|
||||
- All schedules with `nextRunAt < currentTime` marked as missed
|
||||
- Missed notifications created/updated in database
|
||||
- History records created for each missed alarm
|
||||
|
||||
3. ✅ **All future alarms are rescheduled**
|
||||
- All schedules with `nextRunAt >= currentTime` rescheduled
|
||||
- Repeating schedules calculate next occurrence correctly
|
||||
- No duplicate alarms created
|
||||
|
||||
4. ✅ **Recovery handles both notify and fetch schedules**
|
||||
- `notify` schedules rescheduled via AlarmManager
|
||||
- `fetch` schedules rescheduled via WorkManager
|
||||
- Both types recovered completely
|
||||
|
||||
5. ✅ **Recovery never crashes the app**
|
||||
- All exceptions caught and logged
|
||||
- Partial recovery logged if some schedules fail
|
||||
- App continues normally even if recovery fails
|
||||
|
||||
### 1.2 Success Metrics
|
||||
|
||||
| Metric | Target | Measurement |
|
||||
|--------|--------|-------------|
|
||||
| Force stop detection accuracy | 100% | Manual verification via logs |
|
||||
| Past alarm recovery rate | 100% | All past alarms marked as missed |
|
||||
| Future alarm recovery rate | > 95% | History table outcome field |
|
||||
| Recovery execution time | < 3 seconds | Log timestamp difference |
|
||||
| Crash rate | 0% | No exceptions propagate to app |
|
||||
|
||||
### 1.3 Out of Scope (Phase 2)
|
||||
|
||||
- ❌ Warm start optimization (Phase 3)
|
||||
- ❌ Boot receiver missed alarm handling (Phase 3)
|
||||
- ❌ Callback event emission (Phase 3)
|
||||
- ❌ User notification of missed alarms (Phase 3)
|
||||
|
||||
---
|
||||
|
||||
## 2. Implementation: Force Stop Detection
|
||||
|
||||
### 2.1 Update ReactivationManager
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/ReactivationManager.kt`
|
||||
|
||||
**Location**: Add scenario detection after Phase 1 implementation
|
||||
|
||||
### 2.2 Scenario Detection
|
||||
|
||||
**⚠️ Canonical Source**: This method supersedes any earlier scenario detection code shown in the full directive.
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Detect recovery scenario based on AlarmManager state vs database
|
||||
*
|
||||
* Phase 2: Adds force stop detection
|
||||
*
|
||||
* This is the normative implementation of scenario detection.
|
||||
*
|
||||
* @return RecoveryScenario enum value
|
||||
*/
|
||||
private suspend fun detectScenario(): RecoveryScenario {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val dbSchedules = db.scheduleDao().getEnabled()
|
||||
|
||||
// Check for first launch (empty DB)
|
||||
if (dbSchedules.isEmpty()) {
|
||||
Log.d(TAG, "No schedules in database - first launch (NONE)")
|
||||
return RecoveryScenario.NONE
|
||||
}
|
||||
|
||||
// Check for boot recovery (set by BootReceiver)
|
||||
if (isBootRecovery()) {
|
||||
Log.i(TAG, "Boot recovery detected")
|
||||
return RecoveryScenario.BOOT
|
||||
}
|
||||
|
||||
// Check for force stop: DB has schedules but no alarms exist
|
||||
if (!alarmsExist()) {
|
||||
Log.i(TAG, "Force stop detected: DB has ${dbSchedules.size} schedules, but no alarms exist")
|
||||
return RecoveryScenario.FORCE_STOP
|
||||
}
|
||||
|
||||
// Normal cold start: DB has schedules and alarms exist
|
||||
// (Alarms may have fired or may be future alarms - need to verify/resync)
|
||||
Log.d(TAG, "Cold start: DB has ${dbSchedules.size} schedules, alarms exist")
|
||||
return RecoveryScenario.COLD_START
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if this is a boot recovery scenario
|
||||
*
|
||||
* BootReceiver sets a flag in SharedPreferences when boot completes.
|
||||
* This allows ReactivationManager to detect boot scenario.
|
||||
*
|
||||
* @return true if boot recovery, false otherwise
|
||||
*/
|
||||
private fun isBootRecovery(): Boolean {
|
||||
val prefs = context.getSharedPreferences("dailynotification_recovery", Context.MODE_PRIVATE)
|
||||
val lastBootAt = prefs.getLong("last_boot_at", 0)
|
||||
val currentTime = System.currentTimeMillis()
|
||||
|
||||
// Boot flag is valid for 60 seconds after boot
|
||||
// This prevents false positives from stale flags
|
||||
if (lastBootAt > 0 && (currentTime - lastBootAt) < 60000) {
|
||||
// Clear the flag after reading
|
||||
prefs.edit().remove("last_boot_at").apply()
|
||||
return true
|
||||
}
|
||||
|
||||
return false
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if alarms exist in AlarmManager
|
||||
*
|
||||
* **Correction**: Replaces unreliable nextAlarmClock check with PendingIntent check.
|
||||
* This eliminates false positives from nextAlarmClock.
|
||||
*
|
||||
* @return true if at least one alarm exists, false otherwise
|
||||
*/
|
||||
private fun alarmsExist(): Boolean {
|
||||
return try {
|
||||
// Check if any PendingIntent for our receiver exists
|
||||
// This is more reliable than nextAlarmClock
|
||||
val intent = Intent(context, DailyNotificationReceiver::class.java).apply {
|
||||
action = "com.timesafari.daily.NOTIFICATION"
|
||||
}
|
||||
val pendingIntent = PendingIntent.getBroadcast(
|
||||
context,
|
||||
0, // Use 0 to check for any alarm
|
||||
intent,
|
||||
PendingIntent.FLAG_NO_CREATE or PendingIntent.FLAG_IMMUTABLE
|
||||
)
|
||||
val exists = pendingIntent != null
|
||||
Log.d(TAG, "Alarm check: alarms exist = $exists")
|
||||
exists
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Error checking if alarms exist", e)
|
||||
// On error, assume no alarms (conservative for force stop detection)
|
||||
false
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Recovery scenario enum
|
||||
*
|
||||
* **Corrected Model**: Only these four scenarios are supported
|
||||
*/
|
||||
enum class RecoveryScenario {
|
||||
COLD_START, // Process killed, alarms may or may not exist
|
||||
FORCE_STOP, // Alarms cleared, DB still populated
|
||||
BOOT, // Device reboot
|
||||
NONE // No recovery required (warm resume or first launch)
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 Update performRecovery()
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Perform recovery on app launch
|
||||
* Phase 2: Adds force stop handling
|
||||
*/
|
||||
fun performRecovery() {
|
||||
CoroutineScope(Dispatchers.IO).launch {
|
||||
try {
|
||||
withTimeout(TimeUnit.SECONDS.toMillis(RECOVERY_TIMEOUT_SECONDS)) {
|
||||
Log.i(TAG, "Starting app launch recovery (Phase 2)")
|
||||
|
||||
// Step 1: Detect scenario
|
||||
val scenario = detectScenario()
|
||||
Log.i(TAG, "Detected scenario: $scenario")
|
||||
|
||||
// Step 2: Handle based on scenario
|
||||
when (scenario) {
|
||||
RecoveryScenario.FORCE_STOP -> {
|
||||
// Phase 2: Force stop recovery (new in this phase)
|
||||
val result = performForceStopRecovery()
|
||||
Log.i(TAG, "Force stop recovery completed: $result")
|
||||
}
|
||||
RecoveryScenario.COLD_START -> {
|
||||
// Phase 1: Cold start recovery (reuse existing implementation)
|
||||
val result = performColdStartRecovery()
|
||||
Log.i(TAG, "Cold start recovery completed: $result")
|
||||
}
|
||||
RecoveryScenario.BOOT -> {
|
||||
// Phase 3: Boot recovery (handled via ReactivationManager)
|
||||
// Boot recovery uses same logic as force stop (all alarms wiped)
|
||||
val result = performForceStopRecovery()
|
||||
Log.i(TAG, "Boot recovery completed: $result")
|
||||
}
|
||||
RecoveryScenario.NONE -> {
|
||||
// No recovery needed (warm resume or first launch)
|
||||
Log.d(TAG, "No recovery needed (NONE scenario)")
|
||||
}
|
||||
}
|
||||
|
||||
Log.i(TAG, "App launch recovery completed")
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Recovery failed (non-fatal): ${e.message}", e)
|
||||
try {
|
||||
recordRecoveryFailure(e)
|
||||
} catch (historyError: Exception) {
|
||||
Log.w(TAG, "Failed to record recovery failure in history", historyError)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Implementation: Force Stop Recovery
|
||||
|
||||
### 3.1 Force Stop Recovery Method
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Perform force stop recovery
|
||||
*
|
||||
* Force stop scenario: ALL alarms were cancelled by OS
|
||||
* Need to:
|
||||
* 1. Mark all past alarms as missed
|
||||
* 2. Reschedule all future alarms
|
||||
* 3. Handle both notify and fetch schedules
|
||||
*
|
||||
* @return RecoveryResult with counts
|
||||
*/
|
||||
private suspend fun performForceStopRecovery(): RecoveryResult {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val currentTime = System.currentTimeMillis()
|
||||
|
||||
Log.i(TAG, "Force stop recovery: recovering all schedules")
|
||||
|
||||
val dbSchedules = try {
|
||||
db.scheduleDao().getEnabled()
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to query schedules", e)
|
||||
return RecoveryResult(0, 0, 0, 1)
|
||||
}
|
||||
|
||||
var missedCount = 0
|
||||
var rescheduledCount = 0
|
||||
var errors = 0
|
||||
|
||||
dbSchedules.forEach { schedule ->
|
||||
try {
|
||||
when (schedule.kind) {
|
||||
"notify" -> {
|
||||
val result = recoverNotifySchedule(schedule, currentTime, db)
|
||||
missedCount += result.missedCount
|
||||
rescheduledCount += result.rescheduledCount
|
||||
errors += result.errors
|
||||
}
|
||||
"fetch" -> {
|
||||
val result = recoverFetchSchedule(schedule, currentTime, db)
|
||||
rescheduledCount += result.rescheduledCount
|
||||
errors += result.errors
|
||||
}
|
||||
else -> {
|
||||
Log.w(TAG, "Unknown schedule kind: ${schedule.kind}")
|
||||
}
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
errors++
|
||||
Log.e(TAG, "Failed to recover schedule: ${schedule.id}", e)
|
||||
}
|
||||
}
|
||||
|
||||
val result = RecoveryResult(
|
||||
missedCount = missedCount,
|
||||
rescheduledCount = rescheduledCount,
|
||||
verifiedCount = 0, // Not applicable for force stop
|
||||
errors = errors
|
||||
)
|
||||
|
||||
recordRecoveryHistory(db, "force_stop", result)
|
||||
|
||||
Log.i(TAG, "Force stop recovery complete: $result")
|
||||
return result
|
||||
}
|
||||
|
||||
/**
|
||||
* Data class for schedule recovery results
|
||||
*/
|
||||
private data class ScheduleRecoveryResult(
|
||||
val missedCount: Int = 0,
|
||||
val rescheduledCount: Int = 0,
|
||||
val errors: Int = 0
|
||||
)
|
||||
```
|
||||
|
||||
### 3.2 Recover Notify Schedule
|
||||
|
||||
**Behavior**: Handles `kind == "notify"` schedules. Reschedules via AlarmManager.
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Recover a notify schedule after force stop
|
||||
*
|
||||
* Handles notify schedules (kind == "notify")
|
||||
*
|
||||
* @param schedule Schedule to recover
|
||||
* @param currentTime Current time in milliseconds
|
||||
* @param db Database instance
|
||||
* @return ScheduleRecoveryResult
|
||||
*/
|
||||
private suspend fun recoverNotifySchedule(
|
||||
schedule: Schedule,
|
||||
currentTime: Long,
|
||||
db: DailyNotificationDatabase
|
||||
): ScheduleRecoveryResult {
|
||||
|
||||
// Data integrity check
|
||||
if (schedule.id.isBlank()) {
|
||||
Log.w(TAG, "Skipping invalid schedule: empty ID")
|
||||
return ScheduleRecoveryResult(errors = 1)
|
||||
}
|
||||
|
||||
var missedCount = 0
|
||||
var rescheduledCount = 0
|
||||
var errors = 0
|
||||
|
||||
// Calculate next run time
|
||||
val nextRunTime = calculateNextRunTime(schedule, currentTime)
|
||||
|
||||
if (nextRunTime < currentTime) {
|
||||
// Past alarm - was missed during force stop
|
||||
Log.i(TAG, "Past alarm detected: ${schedule.id} scheduled for $nextRunTime")
|
||||
|
||||
try {
|
||||
// Mark as missed
|
||||
markMissedNotification(schedule, nextRunTime, db)
|
||||
missedCount++
|
||||
} catch (e: Exception) {
|
||||
errors++
|
||||
Log.e(TAG, "Failed to mark missed notification: ${schedule.id}", e)
|
||||
}
|
||||
|
||||
// Reschedule next occurrence if repeating
|
||||
if (isRepeating(schedule)) {
|
||||
try {
|
||||
val nextOccurrence = calculateNextOccurrence(schedule, currentTime)
|
||||
rescheduleAlarm(schedule, nextOccurrence, db)
|
||||
rescheduledCount++
|
||||
Log.i(TAG, "Rescheduled next occurrence: ${schedule.id} for $nextOccurrence")
|
||||
} catch (e: Exception) {
|
||||
errors++
|
||||
Log.e(TAG, "Failed to reschedule next occurrence: ${schedule.id}", e)
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// Future alarm - reschedule immediately
|
||||
Log.i(TAG, "Future alarm detected: ${schedule.id} scheduled for $nextRunTime")
|
||||
|
||||
try {
|
||||
rescheduleAlarm(schedule, nextRunTime, db)
|
||||
rescheduledCount++
|
||||
} catch (e: Exception) {
|
||||
errors++
|
||||
Log.e(TAG, "Failed to reschedule future alarm: ${schedule.id}", e)
|
||||
}
|
||||
}
|
||||
|
||||
return ScheduleRecoveryResult(missedCount, rescheduledCount, errors)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Recover Fetch Schedule
|
||||
|
||||
**Behavior**: Handles `kind == "fetch"` schedules. Reschedules via WorkManager.
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Recover a fetch schedule after force stop
|
||||
*
|
||||
* Handles fetch schedules (kind == "fetch")
|
||||
*
|
||||
* @param schedule Schedule to recover
|
||||
* @param currentTime Current time in milliseconds
|
||||
* @param db Database instance
|
||||
* @return ScheduleRecoveryResult
|
||||
*/
|
||||
private suspend fun recoverFetchSchedule(
|
||||
schedule: Schedule,
|
||||
currentTime: Long,
|
||||
db: DailyNotificationDatabase
|
||||
): ScheduleRecoveryResult {
|
||||
|
||||
// Data integrity check
|
||||
if (schedule.id.isBlank()) {
|
||||
Log.w(TAG, "Skipping invalid schedule: empty ID")
|
||||
return ScheduleRecoveryResult(errors = 1)
|
||||
}
|
||||
|
||||
var rescheduledCount = 0
|
||||
var errors = 0
|
||||
|
||||
try {
|
||||
// Reschedule fetch work via WorkManager
|
||||
val config = ContentFetchConfig(
|
||||
enabled = schedule.enabled,
|
||||
schedule = schedule.cron ?: schedule.clockTime ?: "0 9 * * *",
|
||||
url = null, // Will use registered native fetcher
|
||||
timeout = 30000,
|
||||
retryAttempts = 3,
|
||||
retryDelay = 1000,
|
||||
callbacks = CallbackConfig()
|
||||
)
|
||||
|
||||
FetchWorker.scheduleFetch(context, config)
|
||||
rescheduledCount++
|
||||
|
||||
Log.i(TAG, "Rescheduled fetch: ${schedule.id}")
|
||||
} catch (e: Exception) {
|
||||
errors++
|
||||
Log.e(TAG, "Failed to reschedule fetch: ${schedule.id}", e)
|
||||
}
|
||||
|
||||
return ScheduleRecoveryResult(rescheduledCount = rescheduledCount, errors = errors)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 Helper Methods
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Mark a notification as missed
|
||||
*
|
||||
* @param schedule Schedule that was missed
|
||||
* @param scheduledTime When the notification was scheduled
|
||||
* @param db Database instance
|
||||
*/
|
||||
private suspend fun markMissedNotification(
|
||||
schedule: Schedule,
|
||||
scheduledTime: Long,
|
||||
db: DailyNotificationDatabase
|
||||
) {
|
||||
try {
|
||||
// Try to find existing NotificationContentEntity
|
||||
val notificationId = schedule.id
|
||||
val existingNotification = db.notificationContentDao().getNotificationById(notificationId)
|
||||
|
||||
if (existingNotification != null) {
|
||||
// Update existing notification
|
||||
existingNotification.deliveryStatus = "missed"
|
||||
existingNotification.lastDeliveryAttempt = System.currentTimeMillis()
|
||||
existingNotification.deliveryAttempts = (existingNotification.deliveryAttempts ?: 0) + 1
|
||||
db.notificationContentDao().updateNotification(existingNotification)
|
||||
Log.d(TAG, "Updated existing notification as missed: $notificationId")
|
||||
} else {
|
||||
// Create missed notification entry
|
||||
// Note: This may not have full content, but marks the missed event
|
||||
Log.w(TAG, "No NotificationContentEntity found for schedule: $notificationId")
|
||||
// Could create a minimal entry here if needed
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
Log.e(TAG, "Failed to mark missed notification: ${schedule.id}", e)
|
||||
throw e
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Calculate next run time from schedule
|
||||
* Uses existing BootReceiver logic if available
|
||||
*
|
||||
* @param schedule Schedule to calculate for
|
||||
* @param currentTime Current time in milliseconds
|
||||
* @return Next run time in milliseconds
|
||||
*/
|
||||
private fun calculateNextRunTime(schedule: Schedule, currentTime: Long): Long {
|
||||
// Prefer nextRunAt if set
|
||||
if (schedule.nextRunAt != null) {
|
||||
return schedule.nextRunAt!!
|
||||
}
|
||||
|
||||
// Calculate from cron or clockTime
|
||||
// For now, simplified: use BootReceiver logic if available
|
||||
// Otherwise, default to next day at 9 AM
|
||||
return when {
|
||||
schedule.cron != null -> {
|
||||
// TODO: Parse cron and calculate next run
|
||||
// For now, return next day at 9 AM
|
||||
currentTime + (24 * 60 * 60 * 1000L)
|
||||
}
|
||||
schedule.clockTime != null -> {
|
||||
// TODO: Parse HH:mm and calculate next run
|
||||
// For now, return next day at specified time
|
||||
currentTime + (24 * 60 * 60 * 1000L)
|
||||
}
|
||||
else -> {
|
||||
// Default to next day at 9 AM
|
||||
currentTime + (24 * 60 * 60 * 1000L)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if schedule is repeating
|
||||
*
|
||||
* **Helper Consistency Note**: This helper must remain consistent with any
|
||||
* equivalent methods used in `BootReceiver` (Phase 3). If updated, update both places.
|
||||
*
|
||||
* @param schedule Schedule to check
|
||||
* @return true if repeating, false if one-time
|
||||
*/
|
||||
private fun isRepeating(schedule: Schedule): Boolean {
|
||||
// Schedules with cron or clockTime are repeating
|
||||
return schedule.cron != null || schedule.clockTime != null
|
||||
}
|
||||
|
||||
/**
|
||||
* Calculate next occurrence for repeating schedule
|
||||
*
|
||||
* **Helper Consistency Note**: This helper must remain consistent with any
|
||||
* equivalent methods used in `BootReceiver` (Phase 3). If updated, update both places.
|
||||
*
|
||||
* @param schedule Schedule to calculate for
|
||||
* @param fromTime Calculate next occurrence after this time
|
||||
* @return Next occurrence time in milliseconds
|
||||
*/
|
||||
private fun calculateNextOccurrence(schedule: Schedule, fromTime: Long): Long {
|
||||
// TODO: Implement proper calculation based on cron/clockTime
|
||||
// For now, simplified: daily schedules add 24 hours
|
||||
return fromTime + (24 * 60 * 60 * 1000L)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Integrity Checks
|
||||
|
||||
### 4.1 Force Stop Detection Validation
|
||||
|
||||
**False Positive Prevention**:
|
||||
- ✅ First launch: `DB schedules count == 0` → Not force stop
|
||||
- ✅ Normal cold start: `AlarmManager has alarms` → Not force stop
|
||||
- ✅ Only detect force stop when: `DB schedules > 0 && AlarmManager alarms == 0`
|
||||
|
||||
**Edge Cases**:
|
||||
- ✅ All alarms already fired: Still detect as force stop if AlarmManager is empty
|
||||
- ✅ Partial alarm cancellation: Not detected as force stop (handled by cold start recovery)
|
||||
|
||||
### 4.2 Schedule Validation
|
||||
|
||||
**Notify Schedule Validation**:
|
||||
- ✅ `id` must not be blank
|
||||
- ✅ `kind` must be "notify"
|
||||
- ✅ `nextRunAt` or `cron`/`clockTime` must be set
|
||||
|
||||
**Fetch Schedule Validation**:
|
||||
- ✅ `id` must not be blank
|
||||
- ✅ `kind` must be "fetch"
|
||||
- ✅ `cron` or `clockTime` must be set
|
||||
|
||||
---
|
||||
|
||||
## 5. Rollback Safety
|
||||
|
||||
### 5.1 No-Crash Guarantee
|
||||
|
||||
**All force stop recovery operations must:**
|
||||
|
||||
1. **Catch all exceptions** - Never propagate exceptions to app
|
||||
2. **Continue processing** - One schedule failure doesn't stop recovery
|
||||
3. **Log errors** - All failures logged with context
|
||||
4. **Partial recovery** - Some schedules can recover even if others fail
|
||||
|
||||
### 5.2 Error Handling Strategy
|
||||
|
||||
| Error Type | Handling | Log Level |
|
||||
|------------|----------|-----------|
|
||||
| Schedule query failure | Return empty result, log error | ERROR |
|
||||
| Invalid schedule data | Skip schedule, continue | WARN |
|
||||
| Alarm reschedule failure | Log error, continue to next | ERROR |
|
||||
| Fetch reschedule failure | Log error, continue to next | ERROR |
|
||||
| Missed notification marking failure | Log error, continue | ERROR |
|
||||
| History recording failure | Log warning, don't fail | WARN |
|
||||
|
||||
---
|
||||
|
||||
## 6. Testing Requirements
|
||||
|
||||
### 6.1 Test 1: Force Stop Detection
|
||||
|
||||
**Purpose**: Verify force stop scenario is detected correctly.
|
||||
|
||||
**Steps**:
|
||||
1. Schedule 3 notifications (2 minutes, 5 minutes, 10 minutes in future)
|
||||
2. Verify alarms scheduled: `adb shell dumpsys alarm | grep timesafari`
|
||||
3. Force stop app: `adb shell am force-stop com.timesafari.dailynotification`
|
||||
4. Verify alarms cancelled: `adb shell dumpsys alarm | grep timesafari` (should be empty)
|
||||
5. Launch app: `adb shell am start -n com.timesafari.dailynotification/.MainActivity`
|
||||
6. Check logs: `adb logcat -d | grep DNP-REACTIVATION`
|
||||
|
||||
**Expected**:
|
||||
- ✅ Log shows "Force stop detected: DB has X schedules, AlarmManager has 0 alarms"
|
||||
- ✅ Log shows "Detected scenario: FORCE_STOP"
|
||||
- ✅ Log shows "Force stop recovery: recovering all schedules"
|
||||
|
||||
**Pass Criteria**: Force stop correctly detected.
|
||||
|
||||
### 6.2 Test 2: Past Alarm Recovery
|
||||
|
||||
**Purpose**: Verify past alarms are marked as missed.
|
||||
|
||||
**Steps**:
|
||||
1. Schedule notification for 2 minutes in future
|
||||
2. Force stop app
|
||||
3. Wait 5 minutes (past scheduled time)
|
||||
4. Launch app
|
||||
5. Check database: `delivery_status = 'missed'` for past alarm
|
||||
|
||||
**Expected**:
|
||||
- ✅ Past alarm marked as missed in database
|
||||
- ✅ History entry created
|
||||
- ✅ Log shows "Past alarm detected" and "Marked missed notification"
|
||||
|
||||
**Pass Criteria**: Past alarms correctly marked as missed.
|
||||
|
||||
### 6.3 Test 3: Future Alarm Recovery
|
||||
|
||||
**Purpose**: Verify future alarms are rescheduled.
|
||||
|
||||
**Steps**:
|
||||
1. Schedule 3 notifications (5, 10, 15 minutes in future)
|
||||
2. Force stop app
|
||||
3. Launch app immediately
|
||||
4. Verify alarms rescheduled: `adb shell dumpsys alarm | grep timesafari`
|
||||
|
||||
**Expected**:
|
||||
- ✅ All 3 alarms rescheduled in AlarmManager
|
||||
- ✅ Log shows "Future alarm detected" and "Rescheduled alarm"
|
||||
- ✅ No duplicate alarms created
|
||||
|
||||
**Pass Criteria**: Future alarms correctly rescheduled.
|
||||
|
||||
### 6.4 Test 4: Repeating Schedule Recovery
|
||||
|
||||
**Purpose**: Verify repeating schedules calculate next occurrence correctly.
|
||||
|
||||
**Steps**:
|
||||
1. Schedule daily notification (cron: "0 9 * * *")
|
||||
2. Force stop app
|
||||
3. Wait past scheduled time (e.g., wait until 10 AM)
|
||||
4. Launch app
|
||||
5. Verify next occurrence scheduled for tomorrow 9 AM
|
||||
|
||||
**Expected**:
|
||||
- ✅ Past occurrence marked as missed
|
||||
- ✅ Next occurrence scheduled for tomorrow
|
||||
- ✅ Log shows "Rescheduled next occurrence"
|
||||
|
||||
**Pass Criteria**: Repeating schedules correctly calculate next occurrence.
|
||||
|
||||
### 6.5 Test 5: Fetch Schedule Recovery
|
||||
|
||||
**Purpose**: Verify fetch schedules are recovered.
|
||||
|
||||
**Steps**:
|
||||
1. Schedule fetch work (cron: "0 9 * * *")
|
||||
2. Force stop app
|
||||
3. Launch app
|
||||
4. Check WorkManager: `adb shell dumpsys jobscheduler | grep timesafari`
|
||||
|
||||
**Expected**:
|
||||
- ✅ Fetch work rescheduled in WorkManager
|
||||
- ✅ Log shows "Rescheduled fetch"
|
||||
|
||||
**Pass Criteria**: Fetch schedules correctly recovered.
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Checklist
|
||||
|
||||
- [ ] Add `detectScenario()` method to ReactivationManager
|
||||
- [ ] Add `alarmsExist()` method (replaces getActiveAlarmCount)
|
||||
- [ ] Add `isBootRecovery()` method
|
||||
- [ ] Add `RecoveryScenario` enum
|
||||
- [ ] Update `performRecovery()` to handle force stop
|
||||
- [ ] Implement `performForceStopRecovery()`
|
||||
- [ ] Implement `recoverNotifySchedule()`
|
||||
- [ ] Implement `recoverFetchSchedule()`
|
||||
- [ ] Implement `markMissedNotification()`
|
||||
- [ ] Implement `calculateNextRunTime()` (or reuse BootReceiver logic)
|
||||
- [ ] Implement `isRepeating()`
|
||||
- [ ] Implement `calculateNextOccurrence()`
|
||||
- [ ] Add data integrity checks
|
||||
- [ ] Add error handling
|
||||
- [ ] Test force stop detection
|
||||
- [ ] Test past alarm recovery
|
||||
- [ ] Test future alarm recovery
|
||||
- [ ] Test repeating schedule recovery
|
||||
- [ ] Test fetch schedule recovery
|
||||
- [ ] Verify no duplicate alarms
|
||||
|
||||
---
|
||||
|
||||
## 8. Code References
|
||||
|
||||
**Existing Code to Reuse**:
|
||||
- `NotifyReceiver.scheduleExactNotification()` - Line 92
|
||||
- `FetchWorker.scheduleFetch()` - Line 31
|
||||
- `BootReceiver.calculateNextRunTime()` - Line 103 (for next run calculation)
|
||||
- `ScheduleDao.getEnabled()` - Line 298
|
||||
- `NotificationContentDao.getNotificationById()` - Line 69
|
||||
|
||||
**New Code to Create**:
|
||||
- `detectScenario()` - Add to ReactivationManager
|
||||
- `alarmsExist()` - Add to ReactivationManager (replaces getActiveAlarmCount)
|
||||
- `isBootRecovery()` - Add to ReactivationManager
|
||||
- `performForceStopRecovery()` - Add to ReactivationManager
|
||||
- `recoverNotifySchedule()` - Add to ReactivationManager
|
||||
- `recoverFetchSchedule()` - Add to ReactivationManager
|
||||
|
||||
---
|
||||
|
||||
## 9. Success Criteria Summary
|
||||
|
||||
**Phase 2 is complete when:**
|
||||
|
||||
1. ✅ Force stop scenario detected correctly
|
||||
2. ✅ All past alarms marked as missed
|
||||
3. ✅ All future alarms rescheduled
|
||||
4. ✅ Both notify and fetch schedules recovered
|
||||
5. ✅ Repeating schedules calculate next occurrence correctly
|
||||
6. ✅ Recovery never crashes app
|
||||
7. ✅ All tests pass
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Phase 1: Cold Start Recovery](./android-implementation-directive-phase1.md) - Prerequisite
|
||||
- [Full Implementation Directive](./android-implementation-directive.md) - Complete scope
|
||||
- [Exploration Findings](./exploration-findings-initial.md) - Gap analysis
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Prerequisite**: Phase 1 must be complete before starting Phase 2
|
||||
- **Detection accuracy**: Force stop detection uses best available method (nextAlarmClock)
|
||||
- **Comprehensive recovery**: Force stop recovery handles ALL schedules (past and future)
|
||||
- **Safety first**: All recovery operations are non-blocking and non-fatal
|
||||
|
||||
@@ -1,221 +0,0 @@
|
||||
# Android Implementation Directive – Phase 3
|
||||
## Boot-Time Recovery (Device Reboot / System Restart)
|
||||
|
||||
**Plugin:** Daily Notification Plugin
|
||||
**Author:** Matthew Raymer
|
||||
**Applies to:** Android Plugin (Kotlin), Capacitor Bridge
|
||||
**Related Docs:**
|
||||
- `03-plugin-requirements.md`
|
||||
- `000-UNIFIED-ALARM-DIRECTIVE.md`
|
||||
- `android-implementation-directive-phase1.md`
|
||||
- `android-implementation-directive-phase2.md`
|
||||
- `ACTIVATION-GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Phase 3 introduces **Boot-Time Recovery**, which restores daily notifications after:
|
||||
|
||||
- Device reboot
|
||||
- OS restart
|
||||
- Update-related restart
|
||||
- App not opened after reboot (silent recovery)
|
||||
|
||||
Android clears **all alarms** on reboot.
|
||||
Therefore, if our plugin is not actively rescheduling on boot, the user will miss all daily notifications until they manually launch the app.
|
||||
|
||||
Phase 3 ensures:
|
||||
|
||||
1. Schedules stored in SQLite survive reboot
|
||||
2. Alarms are fully reconstructed
|
||||
3. No duplication / double-scheduling
|
||||
4. Boot behavior avoids unnecessary heavy recovery
|
||||
5. Recovery occurs even if the user does **not** manually open the app
|
||||
|
||||
---
|
||||
|
||||
## 2. Boot-Time Recovery Flow
|
||||
|
||||
### Trigger:
|
||||
|
||||
`BOOT_COMPLETED` broadcast received
|
||||
→ Plugin's Boot Receiver invoked
|
||||
→ Recovery logic executed with `scenario=BOOT`
|
||||
|
||||
### Recovery Steps
|
||||
|
||||
1. **Load all schedules** from SQLite (`NotificationRepository.getAllSchedules()`)
|
||||
|
||||
2. **For each schedule:**
|
||||
- Calculate next runtime based on cron expression
|
||||
- Compare with current time
|
||||
|
||||
3. **If the next scheduled time is in the future:**
|
||||
- Recreate alarm with `setAlarmClock`
|
||||
- Log:
|
||||
`Rescheduled alarm: <id> for <ts>`
|
||||
|
||||
4. **If schedule was *in the past* at boot time:**
|
||||
- Mark as missed
|
||||
- Schedule next run according to cron rules
|
||||
|
||||
5. **If no schedules found:**
|
||||
- Quiet exit, log only one line:
|
||||
`BOOT: No schedules found`
|
||||
|
||||
6. **Safeties:**
|
||||
- Boot recovery must **not** modify Plugin Settings
|
||||
- Must not regenerate Fetcher configuration
|
||||
- Must not overwrite database records
|
||||
|
||||
---
|
||||
|
||||
## 3. Required Android Components
|
||||
|
||||
### 3.1 Boot Receiver
|
||||
|
||||
```xml
|
||||
<receiver
|
||||
android:name=".BootReceiver"
|
||||
android:enabled="true"
|
||||
android:exported="true">
|
||||
<intent-filter>
|
||||
<action android:name="android.intent.action.BOOT_COMPLETED" />
|
||||
</intent-filter>
|
||||
</receiver>
|
||||
```
|
||||
|
||||
### 3.2 Kotlin Class
|
||||
|
||||
```kotlin
|
||||
class BootReceiver : BroadcastReceiver() {
|
||||
override fun onReceive(context: Context, intent: Intent?) {
|
||||
if (intent?.action != Intent.ACTION_BOOT_COMPLETED) return
|
||||
|
||||
ReactivationManager.runBootRecovery(context)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. ReactivationManager – Boot Logic
|
||||
|
||||
### Method Signature
|
||||
|
||||
```kotlin
|
||||
fun runBootRecovery(context: Context)
|
||||
```
|
||||
|
||||
### Required Logging (canonical)
|
||||
|
||||
```
|
||||
DNP-REACTIVATION: Starting boot recovery
|
||||
DNP-REACTIVATION: Loaded <N> schedules from DB
|
||||
DNP-REACTIVATION: Rescheduled alarm: <id> for <ts>
|
||||
DNP-REACTIVATION: Marked missed notification: <id>
|
||||
DNP-REACTIVATION: Boot recovery complete: missed=X, rescheduled=Y, errors=Z
|
||||
```
|
||||
|
||||
### Required Fields
|
||||
|
||||
* `scenario=BOOT`
|
||||
* `missed`
|
||||
* `rescheduled`
|
||||
* `verified` **MUST BE 0** (boot has no verification phase)
|
||||
|
||||
---
|
||||
|
||||
## 5. Constraints & Guardrails
|
||||
|
||||
1. **No plugin initialization**
|
||||
Boot must *not* require running the app UI.
|
||||
|
||||
2. **No heavy processing**
|
||||
* limit to 2 seconds
|
||||
* use the same timeout guard as Phase 2
|
||||
|
||||
3. **No scheduling duplicates**
|
||||
* Must detect existing AlarmManager entries
|
||||
* Boot always clears them, so all reschedules should be fresh
|
||||
|
||||
4. **App does not need to be opened**
|
||||
* Entire recovery must run in background context
|
||||
|
||||
5. **Idempotency**
|
||||
* Running twice should produce identical logs
|
||||
|
||||
---
|
||||
|
||||
## 6. Implementation Checklist
|
||||
|
||||
### Mandatory
|
||||
|
||||
* [ ] BootReceiver included
|
||||
* [ ] Manifest entry added
|
||||
* [ ] `runBootRecovery()` implemented
|
||||
* [ ] Scenario logged as `BOOT`
|
||||
* [ ] All alarms recreated
|
||||
* [ ] Timeout protection
|
||||
* [ ] No modifications to preferences or plugin settings
|
||||
|
||||
### Optional
|
||||
|
||||
* [ ] Additional telemetry for analytics
|
||||
* [ ] Optional debug toast for dev builds only
|
||||
|
||||
---
|
||||
|
||||
## 7. Expected Output Examples
|
||||
|
||||
### Example 1 – Normal Boot (future alarms exist)
|
||||
|
||||
```
|
||||
DNP-REACTIVATION: Starting boot recovery
|
||||
DNP-REACTIVATION: Loaded 2 schedules from DB
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_1764233911265 for 1764236120000
|
||||
DNP-REACTIVATION: Rescheduled alarm: daily_1764233465343 for 1764233700000
|
||||
DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled=2, errors=0
|
||||
```
|
||||
|
||||
### Example 2 – Schedules present but some in past
|
||||
|
||||
```
|
||||
Marked missed notification: daily_1764233300000
|
||||
Rescheduled alarm: daily_1764233300000 for next day
|
||||
```
|
||||
|
||||
### Example 3 – No schedules
|
||||
|
||||
```
|
||||
DNP-REACTIVATION: BOOT: No schedules found
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Status
|
||||
|
||||
| Item | Status |
|
||||
| -------------------- | -------------------------------- |
|
||||
| Directive | **Complete** |
|
||||
| Implementation | ☐ Pending / ✅ **Complete** (plugin v1.2+) |
|
||||
| Emulator Test Script | Ready (`test-phase3.sh`) |
|
||||
| Verification Doc | Ready (`PHASE3-VERIFICATION.md`) |
|
||||
|
||||
---
|
||||
|
||||
## 9. Related Documentation
|
||||
|
||||
- [Unified Alarm Directive](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document
|
||||
- [Plugin Requirements](./alarms/03-plugin-requirements.md) - Requirements this phase implements
|
||||
- [Platform Capability Reference](./alarms/01-platform-capability-reference.md) - OS-level facts
|
||||
- [Phase 1](./android-implementation-directive-phase1.md) - Prerequisite
|
||||
- [Phase 2](./android-implementation-directive-phase2.md) - Prerequisite
|
||||
- [Phase 3 Emulator Testing](./alarms/PHASE3-EMULATOR-TESTING.md) - Test procedures
|
||||
- [Phase 3 Verification](./alarms/PHASE3-VERIFICATION.md) - Verification report
|
||||
|
||||
---
|
||||
|
||||
**Status**: Directive complete, ready for implementation
|
||||
**Last Updated**: November 2025
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,669 +0,0 @@
|
||||
# Plugin Behavior Exploration - Initial Findings
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Initial Code Review - In Progress
|
||||
|
||||
## Purpose
|
||||
|
||||
This document contains initial findings from code-level inspection of the plugin. These findings should be verified through actual testing using [Plugin Behavior Exploration Template](./plugin-behavior-exploration-template.md).
|
||||
|
||||
---
|
||||
|
||||
## 0. Behavior Definitions & Investigation Scope
|
||||
|
||||
Before examining the code, we need to clearly define what behaviors we're investigating and what each scenario means.
|
||||
|
||||
### 0.1 App State Scenarios
|
||||
|
||||
#### Swipe from Recents (Recent Apps List)
|
||||
|
||||
**What it is**: User swipes the app away from the Android recent apps list (app switcher) or iOS app switcher.
|
||||
|
||||
**What happens**:
|
||||
- **Android**: The app's UI is removed from the recent apps list, but:
|
||||
- The app process may still be running in the background
|
||||
- The app may be killed by the OS later due to memory pressure
|
||||
- **AlarmManager alarms remain scheduled** and will fire even if the process is killed
|
||||
- The OS will recreate the app process when the alarm fires
|
||||
- **iOS**: The app is terminated, but:
|
||||
- **UNUserNotificationCenter notifications remain scheduled** and will fire
|
||||
- **Calendar/time-based triggers persist across reboot**
|
||||
- **TimeInterval triggers also persist across reboot** (UNLESS they were scheduled with `repeats = false` AND the reboot occurs before the elapsed interval)
|
||||
- The app does not run in the background (unless it has active background tasks)
|
||||
- Notifications fire even though the app is not running
|
||||
- **No plugin code runs when notification fires** unless the user interacts with the notification
|
||||
|
||||
**Key Point**: Swiping from recents does **not** cancel scheduled alarms/notifications. The OS maintains them separately from the app process.
|
||||
|
||||
**Android Nuance - Swipe vs Kill**:
|
||||
- **"Swipe away" DOES NOT kill your process**; the OS may kill it later due to memory pressure
|
||||
- **AlarmManager remains unaffected** by swipe - alarms stay scheduled
|
||||
- **WorkManager tasks remain scheduled** regardless of swipe
|
||||
- The app process may continue running in the background after swipe
|
||||
- Only Force Stop actually cancels alarms and prevents execution
|
||||
|
||||
**Investigation Goal**: Verify that alarms/notifications still fire after the app is swiped away.
|
||||
|
||||
---
|
||||
|
||||
#### Force Stop (Android Only)
|
||||
|
||||
**What it is**: User goes to Settings → Apps → [Your App] → Force Stop. This is a **hard kill** that is different from swiping from recents.
|
||||
|
||||
**What happens**:
|
||||
- **All alarms are immediately cancelled** by the OS
|
||||
- **All WorkManager tasks are cancelled**
|
||||
- **All broadcast receivers are blocked** (including BOOT_COMPLETED)
|
||||
- **All JobScheduler jobs are cancelled**
|
||||
- **The app cannot run** until the user manually opens it again
|
||||
- **No background execution** is possible
|
||||
|
||||
**Key Point**: Force Stop is a **hard boundary** that cannot be bypassed. It's more severe than swiping from recents.
|
||||
|
||||
**Investigation Goal**: Verify that alarms do NOT fire after force stop, and that the plugin can detect and recover when the app is opened again.
|
||||
|
||||
**Difference from Swipe**:
|
||||
- **Swipe**: Alarms remain scheduled, app may still run in background
|
||||
- **Force Stop**: Alarms are cancelled, app cannot run until manually opened
|
||||
|
||||
---
|
||||
|
||||
#### App Still Functioning When Not Visible
|
||||
|
||||
**Android**:
|
||||
- When an app is swiped from recents but not force-stopped:
|
||||
- The app process may continue running in the background
|
||||
- Background services can continue
|
||||
- WorkManager tasks continue
|
||||
- AlarmManager alarms remain scheduled
|
||||
- The app is just not visible in the recent apps list
|
||||
- The OS may kill the process later due to memory pressure, but alarms remain scheduled
|
||||
|
||||
**iOS**:
|
||||
- When an app is swiped from the app switcher:
|
||||
- The app process is terminated
|
||||
- Background tasks (BGTaskScheduler) may still execute (system-controlled, but **opportunistic, not exact**)
|
||||
- UNUserNotificationCenter notifications remain scheduled
|
||||
- The app does not run in the foreground or background (unless it has active background tasks)
|
||||
- **No persistent background execution** after user swipe
|
||||
- **No alarm-like wake** for plugins (unlike Android AlarmManager)
|
||||
- **No background execution at notification time** unless user interacts
|
||||
|
||||
**iOS Limitations**:
|
||||
- No background execution at notification fire time unless user interacts
|
||||
- No alarm-style wakeups exist on iOS
|
||||
- Background execution (BGTaskScheduler) cannot be used for precise timing
|
||||
- Notifications survive reboot but plugin code does not run automatically
|
||||
|
||||
**Investigation Goal**: Understand that "not visible" does not mean "not functioning" for alarms/notifications, but also understand iOS limitations on background execution.
|
||||
|
||||
---
|
||||
|
||||
### 0.2 App Launch Recovery - How It Should Work
|
||||
|
||||
App Launch Recovery is the mechanism by which the plugin detects and handles missed alarms/notifications when the app starts.
|
||||
|
||||
#### Recovery Scenarios
|
||||
|
||||
##### Cold Start
|
||||
|
||||
**What it is**: App is launched from a completely terminated state (process was killed or never started).
|
||||
|
||||
**Recovery Process**:
|
||||
1. Plugin's `load()` method is called
|
||||
2. Plugin initializes database/storage
|
||||
3. Plugin queries for missed alarms/notifications:
|
||||
- Find alarms with `scheduled_time < now` and `delivery_status != 'delivered'`
|
||||
- Find notifications that should have fired but didn't
|
||||
4. For each missed alarm/notification:
|
||||
- Generate a "missed alarm" event or notification
|
||||
- If repeating, reschedule the next occurrence
|
||||
- Update delivery status to "missed" or "delivered"
|
||||
5. Reschedule future alarms/notifications that are still valid
|
||||
6. Verify active alarms match stored alarms
|
||||
|
||||
**Investigation Goal**: Verify that the plugin detects missed alarms on cold start and handles them appropriately.
|
||||
|
||||
**Android Force Stop Detection**:
|
||||
- On cold start, query AlarmManager for active alarms
|
||||
- Query plugin DB schedules
|
||||
- If `(DB.count > 0 && AlarmManager.count == 0)`: **Force Stop detected**
|
||||
- Recovery: Mark all past schedules as missed, reschedule all future schedules, emit missed notifications
|
||||
|
||||
---
|
||||
|
||||
##### Warm Start
|
||||
|
||||
**What it is**: App is returning from background (app was paused but process still running).
|
||||
|
||||
**Recovery Process**:
|
||||
1. Plugin's `load()` method may be called (or app resumes)
|
||||
2. Plugin checks for missed alarms/notifications (same as cold start)
|
||||
3. Plugin verifies that active alarms are still scheduled correctly
|
||||
4. Plugin reschedules if any alarms were cancelled (shouldn't happen, but verify)
|
||||
|
||||
**Investigation Goal**: Verify that the plugin checks for missed alarms on warm start and verifies active alarms.
|
||||
|
||||
---
|
||||
|
||||
##### Force Stop Recovery (Android)
|
||||
|
||||
**What it is**: App was force-stopped and user manually opens it again.
|
||||
|
||||
**Recovery Process**:
|
||||
1. App launches (this is the only way to recover from force stop)
|
||||
2. Plugin's `load()` method is called
|
||||
3. Plugin detects that alarms were cancelled (all alarms have `scheduled_time < now` or are missing from AlarmManager)
|
||||
4. Plugin queries database for all enabled alarms
|
||||
5. For each alarm:
|
||||
- If `scheduled_time < now`: Mark as missed, generate missed alarm event, reschedule if repeating
|
||||
- If `scheduled_time >= now`: Reschedule the alarm
|
||||
6. Plugin reschedules all future alarms
|
||||
|
||||
**Investigation Goal**: Verify that the plugin can detect force stop scenario and fully recover all alarms.
|
||||
|
||||
**Key Difference**: Force stop recovery is more comprehensive than normal app launch recovery because ALL alarms were cancelled, not just missed ones.
|
||||
|
||||
---
|
||||
|
||||
### 0.3 What We're Investigating
|
||||
|
||||
For each scenario, we want to know:
|
||||
|
||||
1. **Does the alarm/notification fire?** (OS behavior)
|
||||
2. **Does the plugin detect missed alarms?** (Plugin behavior)
|
||||
3. **Does the plugin recover/reschedule?** (Plugin behavior)
|
||||
4. **What happens on next app launch?** (Recovery behavior)
|
||||
|
||||
**Expected Behaviors**:
|
||||
|
||||
| Scenario | Alarm Fires? | Plugin Detects Missed? | Plugin Recovers? |
|
||||
| -------- | ------------ | ---------------------- | ---------------- |
|
||||
| Swipe from recents | ✅ Yes (OS) | N/A (fired) | N/A |
|
||||
| Force stop | ❌ No (OS cancels) | ✅ Should detect | ✅ Should recover |
|
||||
| Device reboot (Android) | ❌ No (OS cancels) | ✅ Should detect | ✅ Should recover |
|
||||
| Device reboot (iOS) | ✅ Yes (OS persists) | ⚠️ May detect | ⚠️ May recover |
|
||||
| Cold start | N/A | ✅ Should detect | ✅ Should recover |
|
||||
| Warm start | N/A | ✅ Should detect | ✅ Should verify |
|
||||
|
||||
---
|
||||
|
||||
## 1. Android Findings
|
||||
|
||||
### 1.1 Boot Receiver Implementation
|
||||
|
||||
**Status**: ✅ **IMPLEMENTED**
|
||||
|
||||
**Location**: `android/src/main/java/com/timesafari/dailynotification/BootReceiver.kt`
|
||||
|
||||
**Findings**:
|
||||
- Boot receiver exists and handles `ACTION_BOOT_COMPLETED` (line 24)
|
||||
- Reschedules alarms from database (line 38+)
|
||||
- Loads enabled schedules from Room database (line 40)
|
||||
- Reschedules both "fetch" and "notify" schedules (lines 46-81)
|
||||
|
||||
**Gap Identified**:
|
||||
- **Missed Alarm Handling**: Boot receiver only reschedules FUTURE alarms
|
||||
- Line 64: `if (nextRunTime > System.currentTimeMillis())`
|
||||
- This means if an alarm was scheduled for before the reboot time, it won't be rescheduled
|
||||
- **No missed alarm detection or notification**
|
||||
|
||||
**Recommendation**: Add missed alarm detection in `rescheduleNotifications()` method
|
||||
|
||||
---
|
||||
|
||||
### 1.2 Missed Alarm Detection
|
||||
|
||||
**Status**: ⚠️ **PARTIAL**
|
||||
|
||||
**Location**: `android/src/main/java/com/timesafari/dailynotification/dao/NotificationContentDao.java`
|
||||
|
||||
**Findings**:
|
||||
- DAO has query for missed alarms: `getNotificationsReadyForDelivery()` (line 98)
|
||||
- Query: `SELECT * FROM notification_content WHERE scheduled_time <= :currentTime AND delivery_status != 'delivered'`
|
||||
- This can identify notifications that should have fired but haven't
|
||||
|
||||
**Gap Identified**:
|
||||
- **Not called on app launch**: The `DailyNotificationPlugin.load()` method (line 91) only initializes the database
|
||||
- No recovery logic in `load()` method
|
||||
- Query exists but may not be used for missed alarm detection
|
||||
|
||||
**Recommendation**: Add missed alarm detection in `load()` method or create separate recovery method
|
||||
|
||||
---
|
||||
|
||||
### 1.3 App Launch Recovery
|
||||
|
||||
**Status**: ❌ **NOT IMPLEMENTED**
|
||||
|
||||
**Location**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.kt`
|
||||
|
||||
**Expected Behavior** (as defined in Section 0.2):
|
||||
|
||||
**Cold Start Recovery**:
|
||||
1. Plugin `load()` method called
|
||||
2. Query database for missed alarms: `scheduled_time < now AND delivery_status != 'delivered'`
|
||||
3. For each missed alarm:
|
||||
- Generate missed alarm event/notification
|
||||
- Reschedule if repeating
|
||||
- Update delivery status
|
||||
4. Reschedule all future alarms from database
|
||||
5. Verify active alarms match stored alarms
|
||||
|
||||
**Warm Start Recovery**:
|
||||
1. Plugin checks for missed alarms (same as cold start)
|
||||
2. Verify active alarms are still scheduled
|
||||
3. Reschedule if any were cancelled
|
||||
|
||||
**Force Stop Recovery**:
|
||||
1. Detect that all alarms were cancelled (force stop scenario)
|
||||
2. Query database for ALL enabled alarms
|
||||
3. For each alarm:
|
||||
- If `scheduled_time < now`: Mark as missed, generate event, reschedule if repeating
|
||||
- If `scheduled_time >= now`: Reschedule immediately
|
||||
4. Fully restore alarm state
|
||||
|
||||
**Current Implementation**:
|
||||
- `load()` method (line 91) only initializes database
|
||||
- No recovery logic on app launch
|
||||
- No check for missed alarms
|
||||
- No rescheduling of future alarms
|
||||
- No distinction between cold/warm/force-stop scenarios
|
||||
|
||||
**Gap Identified**:
|
||||
- Plugin does not recover on app cold/warm start
|
||||
- Plugin does not recover from force stop
|
||||
- Only boot receiver handles recovery (and only for future alarms)
|
||||
- No missed alarm detection on app launch
|
||||
|
||||
**Recommendation**:
|
||||
1. Add recovery logic to `load()` method or create `ReactivationManager`
|
||||
2. Implement missed alarm detection using `getNotificationsReadyForDelivery()` query
|
||||
3. Implement force stop detection (all alarms cancelled)
|
||||
4. Implement rescheduling of future alarms from database
|
||||
|
||||
---
|
||||
|
||||
### 1.4 Persistence Completeness
|
||||
|
||||
**Status**: ✅ **IMPLEMENTED**
|
||||
|
||||
**Findings**:
|
||||
- Room database used for persistence
|
||||
- `Schedule` entity stores: id, kind, cron, clockTime, enabled, nextRunAt
|
||||
- `NotificationContentEntity` stores: id, title, body, scheduledTime, priority, etc.
|
||||
- `ContentCache` stores: fetched content with TTL
|
||||
|
||||
**All Required Fields Present**:
|
||||
- ✅ alarm_id (Schedule.id, NotificationContentEntity.id)
|
||||
- ✅ trigger_time (Schedule.nextRunAt, NotificationContentEntity.scheduledTime)
|
||||
- ✅ repeat_rule (Schedule.cron, Schedule.clockTime)
|
||||
- ✅ channel_id (NotificationContentEntity - implicit)
|
||||
- ✅ priority (NotificationContentEntity.priority)
|
||||
- ✅ title, body (NotificationContentEntity)
|
||||
- ✅ sound_enabled, vibration_enabled (NotificationContentEntity)
|
||||
- ✅ created_at, updated_at (NotificationContentEntity)
|
||||
- ✅ enabled (Schedule.enabled)
|
||||
|
||||
---
|
||||
|
||||
### 1.5 Force Stop Recovery
|
||||
|
||||
**Status**: ❌ **NOT IMPLEMENTED**
|
||||
|
||||
**Expected Behavior** (as defined in Section 0.1 and 0.2):
|
||||
|
||||
**Force Stop Scenario**:
|
||||
- User goes to Settings → Apps → [App] → Force Stop
|
||||
- All alarms are immediately cancelled by the OS
|
||||
- App cannot run until user manually opens it
|
||||
- When app is opened, it's a cold start scenario
|
||||
|
||||
**Force Stop Recovery**:
|
||||
1. Detect that alarms were cancelled (check AlarmManager for scheduled alarms)
|
||||
2. Compare with database: if database has alarms but AlarmManager has none → force stop occurred
|
||||
3. Query database for ALL enabled alarms
|
||||
4. For each alarm:
|
||||
- If `scheduled_time < now`: This alarm was missed during force stop
|
||||
- Generate missed alarm event/notification
|
||||
- Reschedule next occurrence if repeating
|
||||
- Update delivery status
|
||||
- If `scheduled_time >= now`: This alarm is still in the future
|
||||
- Reschedule immediately
|
||||
5. Fully restore alarm state
|
||||
|
||||
**Current Implementation**:
|
||||
- No specific force stop detection
|
||||
- No recovery logic for force stop scenario
|
||||
- App launch recovery (if implemented) would handle this, but app launch recovery is not implemented
|
||||
- Cannot distinguish between normal app launch and force stop recovery
|
||||
|
||||
**Gap Identified**:
|
||||
- Plugin cannot detect force stop scenario
|
||||
- Plugin cannot distinguish between normal app launch and force stop recovery
|
||||
- No special handling for force stop scenario
|
||||
- All alarms remain cancelled until user opens app, then plugin should recover them
|
||||
|
||||
**Recommendation**:
|
||||
1. Implement app launch recovery (which will handle force stop as a special case)
|
||||
2. Add force stop detection: compare AlarmManager scheduled alarms with database
|
||||
3. If force stop detected, recover ALL alarms (not just missed ones)
|
||||
|
||||
---
|
||||
|
||||
## 2. iOS Findings
|
||||
|
||||
### 2.1 Notification Persistence
|
||||
|
||||
**Status**: ✅ **IMPLEMENTED**
|
||||
|
||||
**Location**: `ios/Plugin/DailyNotificationStorage.swift`
|
||||
|
||||
**Findings**:
|
||||
- Plugin uses `DailyNotificationStorage` for separate persistence
|
||||
- Uses UserDefaults for quick access (line 40)
|
||||
- Uses CoreData for structured data (line 41)
|
||||
- Stores notifications separately from UNUserNotificationCenter
|
||||
|
||||
**Storage Components**:
|
||||
- UserDefaults: Settings, last fetch, BGTask tracking
|
||||
- CoreData: NotificationContent, Schedule entities
|
||||
- UNUserNotificationCenter: OS-managed notification scheduling
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Missed Notification Detection
|
||||
|
||||
**Status**: ⚠️ **PARTIAL**
|
||||
|
||||
**Location**: `ios/Plugin/DailyNotificationPlugin.swift`
|
||||
|
||||
**Findings**:
|
||||
- `checkForMissedBGTask()` method exists (line 421)
|
||||
- Checks for missed background tasks (BGTaskScheduler)
|
||||
- Reschedules missed BGTask if needed
|
||||
|
||||
**Gap Identified**:
|
||||
- Only checks for missed BGTask, not missed notifications
|
||||
- UNUserNotificationCenter handles notification persistence, but plugin doesn't check for missed notifications
|
||||
- No comparison between plugin storage and UNUserNotificationCenter pending notifications
|
||||
|
||||
**Recommendation**: Add missed notification detection by comparing plugin storage with UNUserNotificationCenter pending requests
|
||||
|
||||
---
|
||||
|
||||
### 2.3 App Launch Recovery
|
||||
|
||||
**Status**: ⚠️ **PARTIAL**
|
||||
|
||||
**Location**: `ios/Plugin/DailyNotificationPlugin.swift`
|
||||
|
||||
**Expected Behavior** (iOS Missed Notification Recovery Architecture):
|
||||
|
||||
**Required Steps for Missed Notification Detection**:
|
||||
1. Query plugin storage (CoreData) for all scheduled notifications
|
||||
2. Query `UNUserNotificationCenter.pendingNotificationRequests()` for future notifications
|
||||
3. Query `UNUserNotificationCenter.getDeliveredNotifications()` for already-fired notifications
|
||||
4. Find CoreData entries where:
|
||||
- `scheduled_time < now` (should have fired)
|
||||
- NOT in `deliveredNotifications` list (didn't fire)
|
||||
- NOT in `pendingNotificationRequests` list (not scheduled for future)
|
||||
5. Generate "missed notification" events for each detected miss
|
||||
6. Reschedule repeating notifications
|
||||
7. Verify that scheduled notifications in UNUserNotificationCenter align with CoreData schedules
|
||||
|
||||
**This must be placed in `load()` during cold start.**
|
||||
|
||||
**Current Implementation**:
|
||||
- `load()` method exists (line 42)
|
||||
- `setupBackgroundTasks()` called (line 318)
|
||||
- `checkForMissedBGTask()` called on setup (line 330)
|
||||
- Only checks for missed BGTask, not missed notifications
|
||||
- No recovery of notification state
|
||||
- No rescheduling of notifications from plugin storage
|
||||
- No comparison between UNUserNotificationCenter and CoreData
|
||||
|
||||
**Gap Identified**:
|
||||
- Only checks for missed BGTask, not missed notifications
|
||||
- No recovery of notification state
|
||||
- No rescheduling of notifications from plugin storage
|
||||
- No cross-checking between UNUserNotificationCenter and CoreData
|
||||
- **iOS cannot detect missed notifications** unless plugin compares storage vs `UNUserNotificationCenter.getDeliveredNotifications()` or infers from plugin timestamps
|
||||
|
||||
**Recommendation**:
|
||||
1. Add notification recovery logic in `load()` or `setupBackgroundTasks()`
|
||||
2. Implement three-way comparison: CoreData vs pending vs delivered notifications
|
||||
3. Add missed notification detection using the architecture above
|
||||
4. Note: iOS does NOT allow arbitrary code execution at notification fire time unless user interacts or Notification Service Extensions are used (not currently used)
|
||||
|
||||
---
|
||||
|
||||
### 2.4 Background Execution Limits
|
||||
|
||||
**Status**: ✅ **DOCUMENTED IN CODE**
|
||||
|
||||
**Findings**:
|
||||
- BGTaskScheduler used for background fetch
|
||||
- Time budget limitations understood (30 seconds typical)
|
||||
- System-controlled execution acknowledged
|
||||
- Rescheduling logic handles missed tasks
|
||||
|
||||
**Code Evidence**:
|
||||
- `checkForMissedBGTask()` handles missed BGTask (line 421)
|
||||
- 15-minute miss window used (line 448)
|
||||
- Reschedules if missed (line 462)
|
||||
|
||||
---
|
||||
|
||||
## 3. Cross-Platform Gaps Summary
|
||||
|
||||
| Gap | Android | iOS | Severity | Recommendation |
|
||||
| --- | ------- | --- | -------- | -------------- |
|
||||
| Missed alarm/notification detection | ⚠️ Partial | ⚠️ Partial | **High** | Implement on app launch |
|
||||
| App launch recovery | ❌ Missing | ⚠️ Partial | **High** | **MUST implement for both platforms** |
|
||||
| Force stop recovery | ❌ Missing | N/A | **Medium** | Android: Implement app launch recovery with force stop detection |
|
||||
| Boot recovery missed alarms | ⚠️ Only future | N/A | **Medium** | Android: Add missed alarm handling in boot receiver |
|
||||
| Cross-check mechanism (DB vs OS) | ❌ Missing | ⚠️ Partial | **High** | Android: AlarmManager vs DB; iOS: UNUserNotificationCenter vs CoreData |
|
||||
|
||||
**Critical Requirement**: App Launch Recovery **must be implemented on BOTH platforms**:
|
||||
- Plugin must execute recovery logic during `load()` OR equivalent
|
||||
- Distinguish cold vs warm start
|
||||
- Use timestamps in storage to verify last known state
|
||||
- Reconcile DB entries with OS scheduling APIs
|
||||
- Android: Cross-check AlarmManager scheduled alarms with DB
|
||||
- iOS: Cross-check UNUserNotificationCenter with CoreData schedules
|
||||
|
||||
---
|
||||
|
||||
## 4. Test Validation Outputs
|
||||
|
||||
For each scenario, the exploration should produce explicit outputs:
|
||||
|
||||
| Scenario | OS Expected | Plugin Expected | Observed Result | Pass/Fail | Notes |
|
||||
| -------- | ----------- | --------------- | --------------- | --------- | ----- |
|
||||
| Swipe from recents | Alarm fires | Alarm fires | ☐ | ☐ | |
|
||||
| Force stop | Alarm does NOT fire | Plugin detects on launch | ☐ | ☐ | |
|
||||
| Device reboot (Android) | Alarm does NOT fire | Plugin reschedules on boot | ☐ | ☐ | |
|
||||
| Device reboot (iOS) | Notification fires | Notification fires | ☐ | ☐ | |
|
||||
| Cold start | N/A | Missed alarms detected | ☐ | ☐ | |
|
||||
| Warm start | N/A | Missed alarms detected | ☐ | ☐ | |
|
||||
| Force stop recovery | N/A | All alarms recovered | ☐ | ☐ | |
|
||||
|
||||
**This creates alignment with the [Exploration Template](./plugin-behavior-exploration-template.md).**
|
||||
|
||||
---
|
||||
|
||||
## 5. Next Steps
|
||||
|
||||
1. **Verify findings through testing** using [Plugin Behavior Exploration Template](./plugin-behavior-exploration-template.md)
|
||||
2. **Test boot receiver** on actual device reboot
|
||||
3. **Test app launch recovery** on cold/warm start
|
||||
4. **Test force stop recovery** on Android (with cross-check mechanism)
|
||||
5. **Test missed notification detection** on iOS (with three-way comparison)
|
||||
6. **Inspect `UNUserNotificationCenter.getPendingNotificationRequests()` vs CoreData** to detect "lost" iOS notifications
|
||||
7. **Update Plugin Requirements** document with verified gaps
|
||||
8. **Generate Test Validation Outputs** table with actual test results
|
||||
|
||||
---
|
||||
|
||||
## 6. Code References for Implementation
|
||||
|
||||
### Android - Add Missed Alarm Detection with Force Stop Detection
|
||||
|
||||
**Location**: `DailyNotificationPlugin.kt` - `load()` method (line 91)
|
||||
|
||||
**Suggested Implementation** (with Force Stop Detection):
|
||||
```kotlin
|
||||
override fun load() {
|
||||
super.load()
|
||||
// ... existing initialization ...
|
||||
|
||||
// Check for missed alarms on app launch
|
||||
CoroutineScope(Dispatchers.IO).launch {
|
||||
detectAndHandleMissedAlarms()
|
||||
}
|
||||
}
|
||||
|
||||
private suspend fun detectAndHandleMissedAlarms() {
|
||||
val db = DailyNotificationDatabase.getDatabase(context)
|
||||
val currentTime = System.currentTimeMillis()
|
||||
|
||||
// Cross-check: Query AlarmManager for active alarms
|
||||
val alarmManager = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
|
||||
val activeAlarmCount = getActiveAlarmCount(alarmManager) // Helper method needed
|
||||
|
||||
// Query database for all enabled schedules
|
||||
val dbSchedules = db.scheduleDao().getEnabled()
|
||||
|
||||
// Force Stop Detection: If DB has schedules but AlarmManager has zero
|
||||
val forceStopDetected = dbSchedules.isNotEmpty() && activeAlarmCount == 0
|
||||
|
||||
if (forceStopDetected) {
|
||||
Log.i(TAG, "Force stop detected - all alarms were cancelled")
|
||||
// Recover ALL alarms (not just missed ones)
|
||||
recoverAllAlarmsAfterForceStop(db, dbSchedules, currentTime)
|
||||
} else {
|
||||
// Normal recovery: only check for missed alarms
|
||||
val missedNotifications = db.notificationContentDao()
|
||||
.getNotificationsReadyForDelivery(currentTime)
|
||||
|
||||
missedNotifications.forEach { notification ->
|
||||
// Generate missed alarm event/notification
|
||||
// Reschedule if repeating
|
||||
// Update delivery status
|
||||
}
|
||||
|
||||
// Reschedule future alarms from database
|
||||
rescheduleFutureAlarms(db, dbSchedules, currentTime)
|
||||
}
|
||||
}
|
||||
|
||||
private suspend fun recoverAllAlarmsAfterForceStop(
|
||||
db: DailyNotificationDatabase,
|
||||
schedules: List<Schedule>,
|
||||
currentTime: Long
|
||||
) {
|
||||
schedules.forEach { schedule ->
|
||||
val nextRunTime = calculateNextRunTime(schedule)
|
||||
if (nextRunTime < currentTime) {
|
||||
// Past alarm - mark as missed
|
||||
// Generate missed alarm notification
|
||||
// Reschedule if repeating
|
||||
} else {
|
||||
// Future alarm - reschedule immediately
|
||||
rescheduleAlarm(schedule, nextRunTime)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Android - Add Missed Alarm Handling in Boot Receiver
|
||||
|
||||
**Location**: `BootReceiver.kt` - `rescheduleNotifications()` method (line 38)
|
||||
|
||||
**Suggested Implementation**:
|
||||
```kotlin
|
||||
// After rescheduling future alarms, check for missed ones
|
||||
val missedNotifications = db.notificationContentDao()
|
||||
.getNotificationsReadyForDelivery(System.currentTimeMillis())
|
||||
|
||||
missedNotifications.forEach { notification ->
|
||||
// Generate missed alarm notification
|
||||
// Reschedule if repeating
|
||||
}
|
||||
```
|
||||
|
||||
### iOS - Add Missed Notification Detection
|
||||
|
||||
**Location**: `DailyNotificationPlugin.swift` - `setupBackgroundTasks()` or `load()` method
|
||||
|
||||
**Suggested Implementation** (Three-Way Comparison):
|
||||
```swift
|
||||
private func checkForMissedNotifications() async {
|
||||
// Step 1: Get pending notifications (future) from UNUserNotificationCenter
|
||||
let pendingRequests = await notificationCenter.pendingNotificationRequests()
|
||||
let pendingIds = Set(pendingRequests.map { $0.identifier })
|
||||
|
||||
// Step 2: Get delivered notifications (already fired) from UNUserNotificationCenter
|
||||
let deliveredNotifications = await notificationCenter.getDeliveredNotifications()
|
||||
let deliveredIds = Set(deliveredNotifications.map { $0.request.identifier })
|
||||
|
||||
// Step 3: Get notifications from plugin storage (CoreData)
|
||||
let storedNotifications = storage?.getAllNotifications() ?? []
|
||||
let currentTime = Date().timeIntervalSince1970
|
||||
|
||||
// Step 4: Find missed notifications
|
||||
// Missed = scheduled_time < now AND not in delivered AND not in pending
|
||||
for notification in storedNotifications {
|
||||
let scheduledTime = notification.scheduledTime
|
||||
let notificationId = notification.id
|
||||
|
||||
if scheduledTime < currentTime {
|
||||
// Should have fired by now
|
||||
if !deliveredIds.contains(notificationId) && !pendingIds.contains(notificationId) {
|
||||
// This notification was missed
|
||||
// Generate missed notification event
|
||||
// Reschedule if repeating
|
||||
// Update delivery status
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Step 5: Verify alignment - check if CoreData schedules match UNUserNotificationCenter
|
||||
// Reschedule any missing notifications from CoreData
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Plugin Behavior Exploration Template](./plugin-behavior-exploration-template.md) - Use this for testing
|
||||
- [Plugin Requirements & Implementation](./plugin-requirements-implementation.md) - Requirements based on findings
|
||||
- [Platform Capability Reference](./platform-capability-reference.md) - OS-level facts
|
||||
|
||||
---
|
||||
|
||||
## 7. Document Separation Directive
|
||||
|
||||
After improvements are complete, separate documents by purpose:
|
||||
|
||||
- **This file** → Exploration Findings (final) - Code inspection and test results
|
||||
- **Android Behavior** → Platform Reference (see [Platform Capability Reference](./platform-capability-reference.md))
|
||||
- **iOS Behavior** → Platform Reference (see [Platform Capability Reference](./platform-capability-reference.md))
|
||||
- **Plugin Requirements** → Independent document (see [Plugin Requirements & Implementation](./plugin-requirements-implementation.md))
|
||||
- **Future Implementation Directive** → Separate document (to be created)
|
||||
|
||||
This avoids future redundancy and maintains clear separation of concerns.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- These findings are from **code inspection only**
|
||||
- **Actual testing required** to verify behavior
|
||||
- Findings should be updated after testing with [Plugin Behavior Exploration Template](./plugin-behavior-exploration-template.md)
|
||||
- iOS missed notification detection requires three-way comparison: CoreData vs pending vs delivered
|
||||
- Android force stop detection requires cross-check: AlarmManager vs database
|
||||
|
||||
@@ -1,670 +0,0 @@
|
||||
# DIRECTIVE: Explore & Document Alarm / Schedule / Notification Behavior in Capacitor Plugin (Android & iOS)
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Active Directive - Exploration Phase
|
||||
|
||||
## 0. Scope & Objective
|
||||
|
||||
We want to **explore, test, and document** how the *current* Capacitor plugin handles:
|
||||
|
||||
- **Alarms / schedules / reminders**
|
||||
- **Local notifications**
|
||||
- **Persistence and recovery** across:
|
||||
- App kill / swipe from recents
|
||||
- OS process kill
|
||||
- Device reboot
|
||||
- **Force stop** (Android) / hard termination (iOS)
|
||||
- Cross-platform **semantic differences** between Android and iOS
|
||||
|
||||
The focus is **observation of current behavior**, not yet changing implementation.
|
||||
|
||||
We want a clear map of **what the plugin actually guarantees** on each platform.
|
||||
|
||||
---
|
||||
|
||||
## 1. Key Questions to Answer
|
||||
|
||||
For **each platform (Android, iOS)** and for **each "scheduled thing"** the plugin supports (alarms, reminders, scheduled notifications, repeating schedules, etc.):
|
||||
|
||||
### 1.1 How is it implemented under the hood?
|
||||
|
||||
- **Android**: AlarmManager? WorkManager? JobScheduler? Foreground service?
|
||||
- **iOS**: UNUserNotificationCenter? BGTaskScheduler? background fetch? timers in foreground?
|
||||
|
||||
### 1.2 What happens when the app is:
|
||||
|
||||
- Swiped away from recents?
|
||||
- Killed by OS (memory pressure)?
|
||||
- Device rebooted?
|
||||
- On Android: explicitly **Force Stopped** in system settings?
|
||||
- On iOS: explicitly swiped away, then device rebooted before next trigger?
|
||||
|
||||
### 1.3 What is persisted?
|
||||
|
||||
Are schedules/alarms stored in:
|
||||
|
||||
- SQLite / Room / shared preferences (Android)?
|
||||
- CoreData / UserDefaults / files (iOS)?
|
||||
- Or are they only in RAM / native scheduler?
|
||||
|
||||
### 1.4 What is re-created and when?
|
||||
|
||||
- On boot?
|
||||
- On app cold start?
|
||||
- On notification tap?
|
||||
- Not at all?
|
||||
|
||||
### 1.5 What does the plugin *promise* to the JS/TS layer?
|
||||
|
||||
- "Will always fire even after reboot"?
|
||||
- "Will fire as long as app hasn't been force-stopped"?
|
||||
- "Best-effort only"?
|
||||
|
||||
We are trying to align **plugin promises** with **real platform capabilities and limitations.**
|
||||
|
||||
---
|
||||
|
||||
## 2. Android Exploration
|
||||
|
||||
### 2.1 Code-Level Inspection
|
||||
|
||||
**Source Locations:**
|
||||
|
||||
- **Plugin Implementation**: `android/src/main/java/com/timesafari/dailynotification/` (Kotlin files may also be present)
|
||||
- **Manifest**: `android/src/main/AndroidManifest.xml`
|
||||
- **Test Applications**:
|
||||
- `test-apps/android-test-app/` - Primary Android test app
|
||||
- `test-apps/daily-notification-test/` - Additional test application
|
||||
|
||||
**Tasks:**
|
||||
|
||||
1. **Locate the Android implementation in the plugin:**
|
||||
- Primary path: `android/src/main/java/com/timesafari/dailynotification/`
|
||||
- Key files to examine:
|
||||
- `DailyNotificationPlugin.kt` - Main plugin class (see `scheduleDailyNotification()` at line 1302)
|
||||
- `DailyNotificationWorker.java` - WorkManager worker (see `doWork()` at line 59)
|
||||
- `DailyNotificationReceiver.java` - BroadcastReceiver for alarms (see `onReceive()` at line 51)
|
||||
- `NotifyReceiver.kt` - AlarmManager scheduling (see `scheduleExactNotification()` at line 92)
|
||||
- `BootReceiver.kt` - Boot recovery (see `onReceive()` at line 24)
|
||||
- `FetchWorker.kt` - WorkManager fetch scheduling (see `scheduleFetch()` at line 31)
|
||||
|
||||
2. **Identify the mechanisms used to schedule work:**
|
||||
- **AlarmManager**: Used via `NotifyReceiver.scheduleExactNotification()` (line 92)
|
||||
- `setAlarmClock()` for Android 5.0+ (line 219)
|
||||
- `setExactAndAllowWhileIdle()` for Android 6.0+ (line 223)
|
||||
- `setExact()` for older versions (line 231)
|
||||
- **WorkManager**: Used for background fetching and notification processing
|
||||
- `FetchWorker.scheduleFetch()` (line 31) - Uses `OneTimeWorkRequest`
|
||||
- `DailyNotificationWorker.doWork()` (line 59) - Processes notifications
|
||||
- **No JobScheduler**: Not used in current implementation
|
||||
- **No repeating alarms**: Uses one-time alarms with rescheduling
|
||||
|
||||
3. **Inspect how notifications are issued:**
|
||||
- **NotificationCompat**: Used in `DailyNotificationWorker.displayNotification()` and `NotifyReceiver.showNotification()` (line 482)
|
||||
- **setFullScreenIntent**: Not currently used (check `NotifyReceiver.showNotification()` at line 443)
|
||||
- **Notification channels**: Created in `NotifyReceiver.showNotification()` (lines 454-470)
|
||||
- Channel ID: `"timesafari.daily"` (see `DailyNotificationWorker.java` line 46)
|
||||
- Importance based on priority (HIGH/DEFAULT/LOW)
|
||||
- **ChannelManager**: Check for separate channel management class
|
||||
|
||||
4. **Check for permissions & receivers:**
|
||||
- Manifest: `android/src/main/AndroidManifest.xml`
|
||||
- Look for:
|
||||
- `RECEIVE_BOOT_COMPLETED` permission
|
||||
- `SCHEDULE_EXACT_ALARM` permission
|
||||
- Any `BroadcastReceiver` declarations for:
|
||||
- `BOOT_COMPLETED` / `LOCKED_BOOT_COMPLETED`
|
||||
- Custom alarm intent actions
|
||||
- Check test app manifests:
|
||||
- `test-apps/android-test-app/app/src/main/AndroidManifest.xml`
|
||||
- `test-apps/daily-notification-test/` (if applicable)
|
||||
|
||||
5. **Determine persistence strategy:**
|
||||
- Where are scheduled alarms stored?
|
||||
- SharedPreferences?
|
||||
- SQLite / Room?
|
||||
- Not at all (just in AlarmManager/work queue)?
|
||||
|
||||
6. **Check for reschedule-on-boot or reschedule-on-app-launch logic:**
|
||||
- **BootReceiver**: `android/src/main/java/com/timesafari/dailynotification/BootReceiver.kt`
|
||||
- `onReceive()` handles `ACTION_BOOT_COMPLETED` (line 24)
|
||||
- `rescheduleNotifications()` reloads from database and reschedules (line 38+)
|
||||
- Calls `NotifyReceiver.scheduleExactNotification()` for each schedule (line 74)
|
||||
- **Alternative**: `DailyNotificationRebootRecoveryManager.java` has `BootCompletedReceiver` inner class (line 278)
|
||||
- **App launch recovery**: Check `DailyNotificationPlugin.kt` for initialization logic that reschedules on app start
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Behavior Testing Matrix (Android)
|
||||
|
||||
**Test Applications:**
|
||||
|
||||
- **Primary**: `test-apps/android-test-app/` - Use this for comprehensive testing
|
||||
- **Secondary**: `test-apps/daily-notification-test/` - Additional test scenarios if needed
|
||||
|
||||
**Run these tests on a real device or emulator.**
|
||||
|
||||
For each scenario, record:
|
||||
|
||||
- Did the alarm / notification fire?
|
||||
- Did it fire on time?
|
||||
- From what state did the app wake up (cold, warm, already running)?
|
||||
- Any visible logs / errors?
|
||||
|
||||
**Scenarios:**
|
||||
|
||||
#### 2.2.1 Base Case
|
||||
|
||||
- Schedule an alarm/notification 2 minutes in the future.
|
||||
- Leave app in foreground or background.
|
||||
- Confirm it fires.
|
||||
|
||||
#### 2.2.2 Swipe from Recents
|
||||
|
||||
- Schedule alarm (2–5 minutes).
|
||||
- Swipe app away from recents.
|
||||
- Wait for trigger time.
|
||||
- Observe: does alarm still fire?
|
||||
|
||||
#### 2.2.3 OS Kill (simulate memory pressure)
|
||||
|
||||
- Mainly observational; may be tricky to force, but:
|
||||
- Open many other apps or use `adb shell am kill <package>` (not force-stop).
|
||||
- Confirm whether scheduled alarm still fires.
|
||||
|
||||
#### 2.2.4 Device Reboot
|
||||
|
||||
- Schedule alarm (e.g. 10 minutes in the future).
|
||||
- Reboot device.
|
||||
- Do **not** reopen app.
|
||||
- Wait past scheduled time:
|
||||
- Does plugin reschedule and fire automatically?
|
||||
- Or does nothing happen until user opens the app?
|
||||
|
||||
Then:
|
||||
|
||||
- After device reboot, manually open the app.
|
||||
- Does plugin detect missed alarms and:
|
||||
- Fire "missed" behavior?
|
||||
- Reschedule future alarms?
|
||||
- Or silently forget them?
|
||||
|
||||
#### 2.2.5 Android Force Stop
|
||||
|
||||
- Schedule alarm.
|
||||
- Go to Settings → Apps → [Your App] → Force stop.
|
||||
- Wait for trigger time.
|
||||
- Observe: it should **not** fire (OS-level rule).
|
||||
- Then open app again and see if plugin automatically:
|
||||
- Detects missed alarms and recovers, or
|
||||
- Treats them as lost.
|
||||
|
||||
**Goal:** build a clear empirical table of plugin behavior vs Android's known rules.
|
||||
|
||||
---
|
||||
|
||||
## 3. iOS Exploration
|
||||
|
||||
### 3.1 Code-Level Inspection
|
||||
|
||||
**Source Locations:**
|
||||
|
||||
- **Plugin Implementation**: `ios/Plugin/` - Swift plugin files
|
||||
- **Alternative Branch**: Check `ios-2` branch for additional iOS implementations or variations
|
||||
- **Test Applications**:
|
||||
- `test-apps/ios-test-app/` - Primary iOS test app
|
||||
- `test-apps/daily-notification-test/` - Additional test application (if iOS support exists)
|
||||
|
||||
**Tasks:**
|
||||
|
||||
1. **Locate the iOS implementation:**
|
||||
- Primary path: `ios/Plugin/`
|
||||
- Key files to examine:
|
||||
- `DailyNotificationPlugin.swift` - Main plugin class (see `scheduleUserNotification()` at line 506)
|
||||
- `DailyNotificationScheduler.swift` - Notification scheduling (see `scheduleNotification()` at line 133)
|
||||
- `DailyNotificationBackgroundTasks.swift` - BGTaskScheduler handlers
|
||||
- **Also check**: `ios-2` branch for alternative implementations or newer iOS code
|
||||
```bash
|
||||
git checkout ios-2
|
||||
# Compare ios/Plugin/DailyNotificationPlugin.swift
|
||||
```
|
||||
|
||||
2. **Identify the scheduling mechanism:**
|
||||
- **UNUserNotificationCenter**: Primary mechanism
|
||||
- `DailyNotificationScheduler.scheduleNotification()` uses `UNCalendarNotificationTrigger` (line 172)
|
||||
- `DailyNotificationPlugin.scheduleUserNotification()` uses `UNTimeIntervalNotificationTrigger` (line 514)
|
||||
- No `UNLocationNotificationTrigger` found
|
||||
- **BGTaskScheduler**: Used for background fetch
|
||||
- `DailyNotificationPlugin.scheduleBackgroundFetch()` (line 495)
|
||||
- Uses `BGAppRefreshTaskRequest` (line 496)
|
||||
- **No timers**: No plain Timer usage found (would die with app)
|
||||
|
||||
3. **Determine what's persisted:**
|
||||
- Does the plugin store alarms in:
|
||||
- `UserDefaults`?
|
||||
- Files / CoreData?
|
||||
- Or only within UNUserNotificationCenter's pending notification requests (no parallel app-side storage)?
|
||||
|
||||
4. **Check for re-scheduling behavior on app launch:**
|
||||
- On app start (cold or warm), does plugin:
|
||||
- Query `UNUserNotificationCenter` for pending notifications?
|
||||
- Compare against its own store?
|
||||
- Attempt to rebuild schedules?
|
||||
- Or does it rely solely on UNUserNotificationCenter to manage everything?
|
||||
|
||||
5. **Determine capabilities / limitations:**
|
||||
- Can the plugin run arbitrary code *when the notification fires*?
|
||||
- Only via notification actions / `didReceive response` callbacks.
|
||||
- Does it support repeating notifications (daily/weekly)?
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Behavior Testing Matrix (iOS)
|
||||
|
||||
**Test Applications:**
|
||||
|
||||
- **Primary**: `test-apps/ios-test-app/` - Use this for comprehensive testing
|
||||
- **Secondary**: `test-apps/daily-notification-test/` - Additional test scenarios if needed
|
||||
- **Note**: Compare behavior between main branch and `ios-2` branch implementations if they differ
|
||||
|
||||
As with Android, test:
|
||||
|
||||
#### 3.2.1 Base Case
|
||||
|
||||
- Schedule local notification 2–5 minutes in the future; leave app backgrounded.
|
||||
- Confirm it fires on time with app in background.
|
||||
|
||||
#### 3.2.2 Swipe App Away
|
||||
|
||||
- Schedule notification, then swipe app away from app switcher.
|
||||
- Confirm notification still fires (iOS local notification center should handle this).
|
||||
|
||||
#### 3.2.3 Device Reboot
|
||||
|
||||
- Schedule notification for a future time.
|
||||
- Reboot device.
|
||||
- Do **not** open app.
|
||||
- Test whether:
|
||||
- Notification still fires (iOS usually persists scheduled local notifications across reboot), or
|
||||
- Behavior depends on trigger type (time vs calendar, etc.).
|
||||
|
||||
#### 3.2.4 Hard Termination & Relaunch
|
||||
|
||||
- Schedule some repeating notification(s).
|
||||
- Terminate app via Xcode / app switcher.
|
||||
- Allow some triggers to occur.
|
||||
- Reopen app and inspect whether plugin:
|
||||
- Notices anything about missed events, or
|
||||
- Simply trusts that UNUserNotificationCenter handled user-visible parts.
|
||||
|
||||
**Goal:** map what your *plugin* adds on top of native behavior vs what is entirely delegated to the OS.
|
||||
|
||||
---
|
||||
|
||||
## 4. Cross-Platform Behavior & Promise Alignment
|
||||
|
||||
After exploration, produce a summary:
|
||||
|
||||
### 4.1 What the plugin actually guarantees to JS callers
|
||||
|
||||
- "Scheduled reminders will still fire after app swipe / kill"
|
||||
- "On Android, reminders may not survive device reboot unless app is opened"
|
||||
- "After Force Stop (Android), nothing runs until user opens app"
|
||||
- "On iOS, local notifications themselves persist across reboot, but no extra app code runs at fire time unless user interacts"
|
||||
|
||||
### 4.2 Where semantics differ
|
||||
|
||||
- Android may require explicit rescheduling on boot; iOS may not.
|
||||
- Android **force stop** is a hard wall; iOS has no exact equivalent in user-facing settings.
|
||||
- Plugin may currently:
|
||||
- Over-promise on reliability, or
|
||||
- Under-document platform limitations.
|
||||
|
||||
### 4.3 Where we need to add warnings / notes in the public API
|
||||
|
||||
- E.g. "This schedule is best-effort; on Android, device reboot may cancel it unless you open the app again," etc.
|
||||
|
||||
---
|
||||
|
||||
## 5. Deliverables from This Exploration
|
||||
|
||||
### 5.1 Doc: `ALARMS_BEHAVIOR_MATRIX.md`
|
||||
|
||||
A table of scenarios (per platform) vs observed behavior.
|
||||
|
||||
Includes:
|
||||
|
||||
- App state
|
||||
- OS event (reboot, force stop, etc.)
|
||||
- What fired, what didn't
|
||||
- Log snippets where useful
|
||||
|
||||
### 5.2 Doc: `PLUGIN_ALARM_LIMITATIONS.md`
|
||||
|
||||
Plain-language explanation of:
|
||||
|
||||
- Android hard limits (Force Stop, reboot behavior)
|
||||
- iOS behavior (local notifications vs app code execution)
|
||||
- Clear note on what the plugin promises.
|
||||
|
||||
### 5.3 Annotated code pointers
|
||||
|
||||
Commented locations in Android/iOS code where:
|
||||
|
||||
- Scheduling is performed
|
||||
- Persistence (if any) is implemented
|
||||
- Rescheduling (if any) is implemented
|
||||
|
||||
### 5.4 Open Questions / TODOs
|
||||
|
||||
Gaps uncovered:
|
||||
|
||||
- No reschedule-on-boot?
|
||||
- No persistence of schedules?
|
||||
- No handling of "missed" alarms on reactivation?
|
||||
- Potential next-step directives (separate document) to improve behavior.
|
||||
|
||||
---
|
||||
|
||||
## 6. One-Liner Summary
|
||||
|
||||
> This directive is to **investigate, not change**: we want a precise, tested understanding of what our Capacitor plugin *currently* does with alarms/schedules/notifications on Android and iOS, especially across kills, reboots, and force stops, and where that behavior does or does not match what we think we're promising to app developers.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Android Alarm Persistence Directive](./android-alarm-persistence-directive.md) - General Android alarm capabilities and limitations
|
||||
- [Boot Receiver Testing Guide](./boot-receiver-testing-guide.md) - Testing boot receiver behavior
|
||||
- [App Startup Recovery Solution](./app-startup-recovery-solution.md) - Recovery mechanisms on app launch
|
||||
- [Reboot Testing Procedure](./reboot-testing-procedure.md) - Step-by-step reboot testing
|
||||
|
||||
---
|
||||
|
||||
## Source Code Structure Reference
|
||||
|
||||
### Android Source Files
|
||||
|
||||
**Primary Plugin Code:**
|
||||
- `android/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.kt` (or `.java`)
|
||||
- `android/src/main/java/com/timesafari/dailynotification/DailyNotificationWorker.java`
|
||||
- `android/src/main/java/com/timesafari/dailynotification/DailyNotificationReceiver.java`
|
||||
- `android/src/main/java/com/timesafari/dailynotification/ChannelManager.java`
|
||||
- `android/src/main/AndroidManifest.xml`
|
||||
|
||||
**Test Applications:**
|
||||
- `test-apps/android-test-app/app/src/main/` - Test app source
|
||||
- `test-apps/android-test-app/app/src/main/assets/public/index.html` - Test UI
|
||||
- `test-apps/daily-notification-test/` - Additional test app (if present)
|
||||
|
||||
### iOS Source Files
|
||||
|
||||
**Primary Plugin Code:**
|
||||
- `ios/Plugin/DailyNotificationPlugin.swift` (or similar)
|
||||
- `ios/Plugin/` - All Swift plugin files
|
||||
- **Also check**: `ios-2` branch for alternative implementations
|
||||
|
||||
**Test Applications:**
|
||||
- `test-apps/ios-test-app/` - Test app source
|
||||
- `test-apps/daily-notification-test/` - Additional test app (if iOS support exists)
|
||||
|
||||
---
|
||||
|
||||
## Detailed Code References (File Locations, Functions, Line Numbers)
|
||||
|
||||
### Android Implementation Details
|
||||
|
||||
#### Alarm Scheduling
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/NotifyReceiver.kt`
|
||||
|
||||
- **Function**: `scheduleExactNotification()` - **Lines 92-247**
|
||||
- Schedules exact alarms using AlarmManager
|
||||
- Uses `setAlarmClock()` for Android 5.0+ (API 21+) - **Line 219**
|
||||
- Falls back to `setExactAndAllowWhileIdle()` for Android 6.0+ (API 23+) - **Line 223**
|
||||
- Falls back to `setExact()` for older versions - **Line 231**
|
||||
- Called from:
|
||||
- `DailyNotificationPlugin.kt` - `scheduleDailyNotification()` - **Line 1385**
|
||||
- `DailyNotificationPlugin.kt` - `scheduleDailyReminder()` - **Line 809**
|
||||
- `DailyNotificationPlugin.kt` - `scheduleDualNotification()` - **Line 1685**
|
||||
- `BootReceiver.kt` - `rescheduleNotifications()` - **Line 74**
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.kt`
|
||||
|
||||
- **Function**: `scheduleDailyNotification()` - **Lines 1302-1417**
|
||||
- Main plugin method for scheduling notifications
|
||||
- Checks exact alarm permission - **Line 1309**
|
||||
- Opens settings if permission not granted - **Lines 1314-1324**
|
||||
- Calls `NotifyReceiver.scheduleExactNotification()` - **Line 1385**
|
||||
- Schedules prefetch 2 minutes before notification - **Line 1395**
|
||||
|
||||
- **Function**: `scheduleDailyReminder()` - **Lines 777-833**
|
||||
- Schedules static reminders (no content dependency)
|
||||
- Calls `NotifyReceiver.scheduleExactNotification()` - **Line 809**
|
||||
|
||||
- **Function**: `canScheduleExactAlarms()` - **Lines 835-860**
|
||||
- Checks if exact alarm permission is granted (Android 12+)
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/PendingIntentManager.java`
|
||||
|
||||
- **Function**: `scheduleExactAlarm()` - **Lines 127-158**
|
||||
- Uses `setExactAndAllowWhileIdle()` - **Line 135**
|
||||
- Falls back to `setExact()` - **Line 141**
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationExactAlarmManager.java`
|
||||
|
||||
- **Function**: `scheduleExactAlarm()` - **Lines 186-201**
|
||||
- Uses `setExactAndAllowWhileIdle()` - **Line 189**
|
||||
- Falls back to `setExact()` - **Line 193**
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationScheduler.java`
|
||||
|
||||
- **Function**: `scheduleExactAlarm()` - **Lines 237-272**
|
||||
- Uses `setExactAndAllowWhileIdle()` - **Line 242**
|
||||
- Falls back to `setExact()` - **Line 251**
|
||||
|
||||
#### WorkManager Usage
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/FetchWorker.kt`
|
||||
|
||||
- **Function**: `scheduleFetch()` - **Lines 31-59**
|
||||
- Schedules WorkManager one-time work request
|
||||
- Uses `OneTimeWorkRequestBuilder` - **Line 36**
|
||||
- Enqueues with `WorkManager.getInstance().enqueueUniqueWork()` - **Lines 53-58**
|
||||
|
||||
- **Function**: `scheduleDelayedPrefetch()` - **Lines 62-131**
|
||||
- Schedules delayed prefetch work
|
||||
- Uses `setInitialDelay()` - **Line 104**
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationWorker.java`
|
||||
|
||||
- **Function**: `doWork()` - **Lines 59-915**
|
||||
- Main WorkManager worker execution
|
||||
- Handles notification display - **Line 91**
|
||||
- Calls `displayNotification()` - **Line 200+**
|
||||
|
||||
- **Function**: `displayNotification()` - **Lines 200-400+**
|
||||
- Displays notification using NotificationCompat
|
||||
- Ensures notification channel exists
|
||||
- Uses `NotificationCompat.Builder` - **Line 200+**
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationFetcher.java`
|
||||
|
||||
- **Function**: `scheduleFetch()` - **Lines 78-140**
|
||||
- Schedules WorkManager fetch work
|
||||
- Uses `OneTimeWorkRequest.Builder` - **Line 106**
|
||||
- Enqueues with `workManager.enqueueUniqueWork()` - **Lines 115-119**
|
||||
|
||||
#### Boot Recovery
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/BootReceiver.kt`
|
||||
|
||||
- **Class**: `BootReceiver` - **Lines 18-100+**
|
||||
- BroadcastReceiver for BOOT_COMPLETED
|
||||
- `onReceive()` - **Line 24** - Handles boot intent
|
||||
- `rescheduleNotifications()` - **Line 38+** - Reschedules all notifications from database
|
||||
- Calls `NotifyReceiver.scheduleExactNotification()` - **Line 74**
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationRebootRecoveryManager.java`
|
||||
|
||||
- **Class**: `BootCompletedReceiver` - **Lines 278-297**
|
||||
- Inner BroadcastReceiver for boot events
|
||||
- `onReceive()` - **Line 280** - Handles BOOT_COMPLETED action
|
||||
- Calls `handleSystemReboot()` - **Line 290**
|
||||
|
||||
#### Notification Display
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationReceiver.java`
|
||||
|
||||
- **Function**: `onReceive()` - **Lines 51-485**
|
||||
- Lightweight BroadcastReceiver triggered by AlarmManager
|
||||
- Enqueues WorkManager work for heavy operations - **Line 100+**
|
||||
- Extracts notification ID and action from intent
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/NotifyReceiver.kt`
|
||||
|
||||
- **Function**: `showNotification()` - **Lines 443-500**
|
||||
- Displays notification using NotificationCompat
|
||||
- Creates notification channel if needed - **Lines 454-470**
|
||||
- Uses `NotificationCompat.Builder` - **Line 482**
|
||||
|
||||
#### Persistence
|
||||
|
||||
**File**: `android/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.kt`
|
||||
|
||||
- Database operations use Room database:
|
||||
- `getDatabase()` - Returns DailyNotificationDatabase instance
|
||||
- Schedule storage in `scheduleDailyNotification()` - **Lines 1393-1410**
|
||||
- Schedule storage in `scheduleDailyReminder()` - **Lines 813-821**
|
||||
|
||||
#### Permissions & Manifest
|
||||
|
||||
**File**: `android/src/main/AndroidManifest.xml`
|
||||
|
||||
- **Note**: Plugin manifest is minimal; receivers declared in consuming app manifest
|
||||
- Check test app manifest: `test-apps/android-test-app/app/src/main/AndroidManifest.xml`
|
||||
- Look for `RECEIVE_BOOT_COMPLETED` permission
|
||||
- Look for `SCHEDULE_EXACT_ALARM` permission
|
||||
- Look for `BootReceiver` registration
|
||||
- Look for `DailyNotificationReceiver` registration
|
||||
|
||||
### iOS Implementation Details
|
||||
|
||||
#### Notification Scheduling
|
||||
|
||||
**File**: `ios/Plugin/DailyNotificationPlugin.swift`
|
||||
|
||||
- **Class**: `DailyNotificationPlugin` - **Lines 24-532**
|
||||
- Main Capacitor plugin class
|
||||
- Uses `UNUserNotificationCenter.current()` - **Line 26**
|
||||
- Uses `BGTaskScheduler.shared` - **Line 27**
|
||||
|
||||
- **Function**: `scheduleUserNotification()` - **Lines 506-529**
|
||||
- Schedules notification using UNUserNotificationCenter
|
||||
- Creates `UNMutableNotificationContent` - **Line 507**
|
||||
- Creates `UNTimeIntervalNotificationTrigger` - **Line 514**
|
||||
- Adds request via `notificationCenter.add()` - **Line 522**
|
||||
|
||||
- **Function**: `scheduleBackgroundFetch()` - **Lines 495-504**
|
||||
- Schedules BGTaskScheduler background fetch
|
||||
- Creates `BGAppRefreshTaskRequest` - **Line 496**
|
||||
- Submits via `backgroundTaskScheduler.submit()` - **Line 502**
|
||||
|
||||
**File**: `ios/Plugin/DailyNotificationScheduler.swift`
|
||||
|
||||
- **Class**: `DailyNotificationScheduler` - **Lines 20-236+**
|
||||
- Manages UNUserNotificationCenter scheduling
|
||||
|
||||
- **Function**: `scheduleNotification()` - **Lines 133-198**
|
||||
- Schedules notification with calendar trigger
|
||||
- Creates `UNCalendarNotificationTrigger` - **Lines 172-175**
|
||||
- Creates `UNNotificationRequest` - **Lines 178-182**
|
||||
- Adds via `notificationCenter.add()` - **Line 185**
|
||||
|
||||
- **Function**: `cancelNotification()` - **Lines 205-213**
|
||||
- Cancels notification by ID
|
||||
- Uses `notificationCenter.removePendingNotificationRequests()` - **Line 206**
|
||||
|
||||
#### Background Tasks
|
||||
|
||||
**File**: `ios/Plugin/DailyNotificationBackgroundTasks.swift`
|
||||
|
||||
- Background task handling for BGTaskScheduler
|
||||
- Register background task identifiers
|
||||
- Handle background fetch execution
|
||||
|
||||
#### Persistence
|
||||
|
||||
**File**: `ios/Plugin/DailyNotificationPlugin.swift**
|
||||
|
||||
- **Note**: Check for UserDefaults, CoreData, or file-based storage
|
||||
- Storage component: `var storage: DailyNotificationStorage?` - **Line 35**
|
||||
- Scheduler component: `var scheduler: DailyNotificationScheduler?` - **Line 36**
|
||||
|
||||
#### iOS-2 Branch
|
||||
|
||||
- **Note**: Check `ios-2` branch for alternative implementations:
|
||||
```bash
|
||||
git checkout ios-2
|
||||
# Compare ios/Plugin/ implementations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Tools & Commands
|
||||
|
||||
### Android Testing
|
||||
|
||||
```bash
|
||||
# Check scheduled alarms
|
||||
adb shell dumpsys alarm | grep -i timesafari
|
||||
|
||||
# Force kill (not force-stop) - adjust package name based on test app
|
||||
adb shell am kill com.timesafari.dailynotification
|
||||
# Or for test apps:
|
||||
# adb shell am kill com.timesafari.androidtestapp
|
||||
# adb shell am kill <package-name-from-test-app-manifest>
|
||||
|
||||
# View logs
|
||||
adb logcat | grep -i "DN\|DailyNotification"
|
||||
|
||||
# Check WorkManager tasks
|
||||
adb shell dumpsys jobscheduler | grep -i timesafari
|
||||
|
||||
# Build and install test app
|
||||
cd test-apps/android-test-app
|
||||
./gradlew installDebug
|
||||
```
|
||||
|
||||
### iOS Testing
|
||||
|
||||
```bash
|
||||
# View device logs (requires Xcode)
|
||||
xcrun simctl spawn booted log stream --predicate 'processImagePath contains "DailyNotification"'
|
||||
|
||||
# List pending notifications (requires app code)
|
||||
# Use UNUserNotificationCenter.getPendingNotificationRequests()
|
||||
|
||||
# Build test app (from test-apps/ios-test-app)
|
||||
# Use Xcode or:
|
||||
cd test-apps/ios-test-app
|
||||
# Follow build instructions in test app README
|
||||
|
||||
# Check ios-2 branch for alternative implementations
|
||||
git checkout ios-2
|
||||
# Compare ios/Plugin/ implementations between branches
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps After Exploration
|
||||
|
||||
Once this exploration is complete:
|
||||
|
||||
1. **Document findings** in the deliverables listed above
|
||||
2. **Identify gaps** between current behavior and desired behavior
|
||||
3. **Create implementation directives** to address gaps (if needed)
|
||||
4. **Update plugin documentation** to accurately reflect platform limitations
|
||||
5. **Update API documentation** with appropriate warnings and caveats
|
||||
|
||||
@@ -1,296 +0,0 @@
|
||||
# ✅ DIRECTIVE: Improvements to Alarm/Schedule/Notification Directives for Capacitor Plugin
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Active Improvement Directive
|
||||
|
||||
## 0. Goal of This Improvement Directive
|
||||
|
||||
Unify, refine, and strengthen the existing alarm-behavior directives so they:
|
||||
|
||||
1. **Eliminate duplication** between the Android Alarm Persistence Directive and the Plugin Exploration Directive.
|
||||
2. **Clarify scope and purpose** (one is exploration/investigation; the other is platform mechanics).
|
||||
3. **Produce a single cohesive standard** to guide future plugin improvements, testing, and documentation.
|
||||
4. **Streamline testing expectations** into executable, check-box-style matrices.
|
||||
5. **Map OS-level limitations directly to plugin-level behavior** so the JS/TS API contract is unambiguous.
|
||||
6. **Add missing iOS-specific limitations, guarantees, and required recovery patterns**.
|
||||
7. **Provide an upgrade path from exploration → design decisions → implementation directives**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Structural Improvements to Apply
|
||||
|
||||
### 1.1 Split responsibilities into three documents (clear roles)
|
||||
|
||||
Your current directives mix *exploration*, *reference*, and *design rules*.
|
||||
|
||||
Improve by creating three clearly separated docs:
|
||||
|
||||
#### **Document A — Platform Capability Reference (Android/iOS)**
|
||||
|
||||
* Pure OS-level facts (no plugin logic).
|
||||
* Use the Android Alarm Persistence Directive as the baseline.
|
||||
* Add an equivalent iOS capability matrix.
|
||||
* Keep strictly normative, minimal, stable.
|
||||
|
||||
#### **Document B — Plugin Behavior Exploration (Android/iOS)**
|
||||
|
||||
* Use the uploaded exploration directive as the baseline.
|
||||
* Remove platform-mechanics explanations (moved to Document A).
|
||||
* Replace vague descriptions with concrete, line-number-linked tasks.
|
||||
* Add "expected vs actual" checklists to each test item.
|
||||
|
||||
#### **Document C — Plugin Requirements & Improvements**
|
||||
|
||||
* Generated after exploration.
|
||||
* Defines the rules the plugin *must follow* to behave predictably.
|
||||
* Defines recovery strategy (boot, reboot, missed alarms, force stop behavior).
|
||||
* Defines JS API caveats and warnings.
|
||||
|
||||
**This file you're asking for now (improvement directive) becomes the origin of Document C.**
|
||||
|
||||
---
|
||||
|
||||
## 2. Improvements Needed to Existing Directives
|
||||
|
||||
### 2.1 Reduce duplication in Android section
|
||||
|
||||
The exploration directive currently repeats much of the alarm persistence directive.
|
||||
|
||||
**Improve by:**
|
||||
|
||||
* Referencing the Android alarm document instead of replicating content.
|
||||
* Summarizing Android limitations in 5–7 lines in the exploration document.
|
||||
* Keeping full explanation *only* in the Android alarm persistence reference file.
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Add missing iOS counterpart to Android's capability matrix
|
||||
|
||||
You have a complete matrix for Android, but not iOS.
|
||||
|
||||
Add a **parallel iOS matrix**, including:
|
||||
|
||||
* Notification survives swipe → yes
|
||||
* Notification survives reboot → yes (for calendar/time triggers)
|
||||
* App logic runs in background → no
|
||||
* Arbitrary code on trigger → no
|
||||
* Recovery required → only if plugin has its own DB
|
||||
|
||||
This fixes asymmetry in current directives.
|
||||
|
||||
---
|
||||
|
||||
### 2.3 Clarify when plugin behavior depends on OS behavior
|
||||
|
||||
The exploration directive needs clearer labeling:
|
||||
|
||||
**Label each behavior as:**
|
||||
|
||||
* **OS-guaranteed** (iOS will fire pending notifications even when the app is dead)
|
||||
* **Plugin-guaranteed** (plugin must reschedule alarms from DB)
|
||||
* **Not allowed** (Android force-stop)
|
||||
|
||||
This removes ambiguity for plugin developers.
|
||||
|
||||
---
|
||||
|
||||
### 2.4 Introduce "Observed Behavior Table" in the exploration doc
|
||||
|
||||
Currently tests describe how to test but do not include space for results.
|
||||
|
||||
Add a table like:
|
||||
|
||||
| Scenario | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ------------------ | --------------------------- | ------------------------------ | ------------- | ----- |
|
||||
| Swipe from recents | Fires | Fires | | |
|
||||
| Device reboot | Does NOT fire automatically | Plugin must reschedule at boot | | |
|
||||
|
||||
This allows the exploration document to be executable.
|
||||
|
||||
---
|
||||
|
||||
### 2.5 Add "JS/TS API Contract" section to both directives
|
||||
|
||||
A critical missing piece.
|
||||
|
||||
Define what JavaScript developers can assume:
|
||||
|
||||
Examples:
|
||||
|
||||
* "Notification will still fire if the app is swiped from recents."
|
||||
* "Notifications WILL NOT fire after Android Force Stop until the app is opened again."
|
||||
* "Reboot behavior depends on platform: iOS preserves, Android destroys."
|
||||
|
||||
This section makes plugin behavior developer-friendly and predictable.
|
||||
|
||||
---
|
||||
|
||||
### 2.6 Strengthen direction on persistence strategy
|
||||
|
||||
The exploration directive asks "what is persisted?" but does not specify what *should* be persisted.
|
||||
|
||||
Add:
|
||||
|
||||
#### **Required Persistence Items**
|
||||
|
||||
* alarm_id
|
||||
* trigger time
|
||||
* repeat rule
|
||||
* channel/priority
|
||||
* payload
|
||||
* time created, last modified
|
||||
|
||||
And:
|
||||
|
||||
#### **Required Recovery Points**
|
||||
|
||||
* Boot event
|
||||
* App cold start
|
||||
* App warm start
|
||||
* App returning from background fetch
|
||||
* User tapping notification
|
||||
|
||||
---
|
||||
|
||||
### 2.7 Add iOS Background Execution Limits section
|
||||
|
||||
Currently missing.
|
||||
|
||||
Add:
|
||||
|
||||
* No repeating background execution APIs except BGTaskScheduler
|
||||
* BGTaskScheduler requires minimum intervals
|
||||
* Plugin cannot rely on background execution to reconstruct alarms
|
||||
* Only notification center persists notifications
|
||||
|
||||
This is critical for plugin parity.
|
||||
|
||||
---
|
||||
|
||||
### 2.8 Integrate "missed alarm recovery" requirements
|
||||
|
||||
The exploration directive asks whether plugin detects missed alarms.
|
||||
The improvement directive must assert that it **must**.
|
||||
|
||||
Add requirement:
|
||||
|
||||
* If alarm time < now, and plugin is activated by reboot or user opening the app → plugin must generate a "missed alarm" event or notification.
|
||||
|
||||
---
|
||||
|
||||
## 3. Rewrite Testing Protocols into Standardized Formats
|
||||
|
||||
### Replace long paragraphs with clear test tables, e.g.:
|
||||
|
||||
#### Android Reboot Test
|
||||
|
||||
| Step | Action |
|
||||
| ---- | ------------------------------------------------ |
|
||||
| 1 | Schedule alarm for 10 minutes later |
|
||||
| 2 | Reboot device |
|
||||
| 3 | Do not open app |
|
||||
| 4 | Does alarm fire? (Expected: NO) |
|
||||
| 5 | Open app |
|
||||
| 6 | Does plugin detect missed alarm? (Expected: YES) |
|
||||
|
||||
Same for iOS, force-stop, etc.
|
||||
|
||||
---
|
||||
|
||||
## 4. Add Missing Directive Sections
|
||||
|
||||
### 4.1 Policy Section
|
||||
|
||||
Define:
|
||||
|
||||
* Unsupported features
|
||||
* Required permissions
|
||||
* Required manifest entries
|
||||
* Required notification channels
|
||||
|
||||
### 4.2 Versioning Requirements
|
||||
|
||||
Each change to alarm behavior is **breaking** and must have:
|
||||
|
||||
* MAJOR version bump
|
||||
* Migration guide
|
||||
|
||||
---
|
||||
|
||||
## 5. Final Improvement Directive (What to Produce Next)
|
||||
|
||||
Here is your actionable deliverable list:
|
||||
|
||||
### **Produce Three New Documents**
|
||||
|
||||
1. **Platform Reference Document**
|
||||
|
||||
* Android alarm rules
|
||||
* iOS notification rules
|
||||
* Both in tabular form
|
||||
* (Rewrites + merges the two uploaded directives)
|
||||
|
||||
2. **Exploration Results Template**
|
||||
|
||||
* Table format for results
|
||||
* Expected vs actual
|
||||
* Direct code references
|
||||
* Remove platform explanation duplication
|
||||
|
||||
3. **Plugin Requirements + Future Implementation Directive**
|
||||
|
||||
* Persistence spec
|
||||
* Recovery spec
|
||||
* JS/TS API contract
|
||||
* Parity rules
|
||||
* Android/iOS caveats
|
||||
* Required test harness
|
||||
|
||||
### **Implement Major Improvements**
|
||||
|
||||
* Strengthen separation of concerns
|
||||
* Add iOS parity
|
||||
* Integrate plugin-level persistence + recovery
|
||||
* Add test matrices
|
||||
* Add clear developer contracts
|
||||
* Add missed-alarm handling requirements
|
||||
* Add design rules for exact alarms and background restrictions
|
||||
|
||||
---
|
||||
|
||||
## 6. One-Sentence Summary
|
||||
|
||||
> **Rewrite the existing directives into three clear documents—platform reference, plugin exploration, and plugin implementation requirements—while adding iOS parity, recovery rules, persistence requirements, and standardized testing matrices, removing duplicated Android content, and specifying a clear JS/TS API contract.**
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Android Alarm Persistence Directive](./android-alarm-persistence-directive.md) - Source material for Document A
|
||||
- [Explore Alarm Behavior Directive](./explore-alarm-behavior-directive.md) - Source material for Document B
|
||||
- [Boot Receiver Testing Guide](./boot-receiver-testing-guide.md) - Testing procedures
|
||||
- [App Startup Recovery Solution](./app-startup-recovery-solution.md) - Recovery mechanisms
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Create Document A**: Platform Capability Reference (Android/iOS)
|
||||
2. **Create Document B**: Plugin Behavior Exploration Template
|
||||
3. **Create Document C**: Plugin Requirements & Implementation Directive
|
||||
4. **Execute exploration** using Document B
|
||||
5. **Update Document C** with findings from exploration
|
||||
6. **Implement improvements** based on Document C
|
||||
|
||||
---
|
||||
|
||||
## Status Tracking
|
||||
|
||||
- [ ] Document A created
|
||||
- [ ] Document B created
|
||||
- [ ] Document C created
|
||||
- [ ] Exploration executed
|
||||
- [ ] Findings documented
|
||||
- [ ] Improvements implemented
|
||||
|
||||
@@ -1,305 +0,0 @@
|
||||
# Platform Capability Reference: Android & iOS Alarm/Notification Behavior
|
||||
|
||||
**⚠️ DEPRECATED**: This document has been superseded by [01-platform-capability-reference.md](./alarms/01-platform-capability-reference.md) as part of the unified alarm documentation structure.
|
||||
|
||||
**See**: [Unified Alarm Directive](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md) for the new documentation structure.
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: **DEPRECATED** - Superseded by unified structure
|
||||
|
||||
## Purpose
|
||||
|
||||
This document provides **pure OS-level facts** about alarm and notification capabilities on Android and iOS. It contains no plugin-specific logic—only platform mechanics that affect plugin design.
|
||||
|
||||
This is a **reference document** to be consulted when designing plugin behavior, not an implementation guide.
|
||||
|
||||
---
|
||||
|
||||
## 1. Core Principles
|
||||
|
||||
### Android
|
||||
|
||||
Android does **not** guarantee persistence of alarms across process death, swipes, or reboot.
|
||||
|
||||
It is the app's responsibility to **persist alarm definitions** and **re-schedule them** under allowed system conditions.
|
||||
|
||||
### iOS
|
||||
|
||||
iOS **does** persist scheduled local notifications across app termination and device reboot, but:
|
||||
|
||||
* App code does **not** run when notifications fire (unless user interacts)
|
||||
* Background execution is severely limited
|
||||
* Plugin must persist its own state if it needs to track or recover missed notifications
|
||||
|
||||
---
|
||||
|
||||
## 2. Android Alarm Capability Matrix
|
||||
|
||||
| Scenario | Will Alarm Fire? | OS Behavior | App Responsibility |
|
||||
| --------------------------------------- | --------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| **Swipe from Recents** | ✅ Yes | AlarmManager resurrects the app process | None (OS handles) |
|
||||
| **App silently killed by OS** | ✅ Yes | AlarmManager still holds scheduled alarms | None (OS handles) |
|
||||
| **Device Reboot** | ❌ No (auto) / ✅ Yes (if you reschedule) | All alarms wiped on reboot | Must reschedule from persistent storage on boot |
|
||||
| **Doze Mode** | ⚠️ Only "exact" alarms | Inexact alarms deferred; exact alarms allowed | Must use `setExactAndAllowWhileIdle` |
|
||||
| **Force Stop** | ❌ Never | Android blocks all callbacks + receivers until next user launch | Cannot bypass; must detect on app restart |
|
||||
| **User reopens app** | ✅ You may reschedule & recover | App process restarted | Must detect missed alarms and reschedule future ones |
|
||||
| **PendingIntent from user interaction** | ✅ If triggered by user | User action unlocks the app | None (OS handles) |
|
||||
|
||||
### Android Allowed Behaviors
|
||||
|
||||
#### 2.1 Alarms survive UI kills (swipe from recents)
|
||||
|
||||
`AlarmManager.setExactAndAllowWhileIdle(...)` alarms **will fire** even after:
|
||||
|
||||
* App is swiped away
|
||||
* App process is killed by the OS
|
||||
|
||||
The OS recreates your app's process to deliver the `PendingIntent`.
|
||||
|
||||
**Required API**: `setExactAndAllowWhileIdle()` or `setAlarmClock()`
|
||||
|
||||
#### 2.2 Alarms can be preserved across device reboot
|
||||
|
||||
Android wipes all alarms on reboot, but **you may recreate them**.
|
||||
|
||||
**Required Components**:
|
||||
|
||||
1. Persist all alarms in storage (Room DB or SharedPreferences)
|
||||
2. Add a `BOOT_COMPLETED` / `LOCKED_BOOT_COMPLETED` broadcast receiver
|
||||
3. On boot, load all enabled alarms and reschedule them using AlarmManager
|
||||
|
||||
**Permissions required**: `RECEIVE_BOOT_COMPLETED`
|
||||
|
||||
**Conditions**: User must have launched your app at least once before reboot
|
||||
|
||||
#### 2.3 Alarms can fire full-screen notifications and wake the device
|
||||
|
||||
**Required API**: `setFullScreenIntent(...)`, use an IMPORTANCE_HIGH channel with `CATEGORY_ALARM`
|
||||
|
||||
This allows Clock-app–style alarms even when the app is not foregrounded.
|
||||
|
||||
#### 2.4 Alarms can be restored after app restart
|
||||
|
||||
If the user re-opens the app (direct user action), you may:
|
||||
|
||||
* Scan the persistent DB
|
||||
* Detect "missed" alarms
|
||||
* Reschedule future alarms
|
||||
* Fire "missed alarm" notifications
|
||||
* Reconstruct WorkManager/JobScheduler tasks wiped by OS
|
||||
|
||||
**Required**: Create a `ReactivationManager` that runs on every app launch
|
||||
|
||||
### Android Forbidden Behaviors
|
||||
|
||||
#### 3.1 You cannot survive "Force Stop"
|
||||
|
||||
**Settings → Apps → YourApp → Force Stop** triggers:
|
||||
|
||||
* Removal of all alarms
|
||||
* Removal of WorkManager tasks
|
||||
* Blocking of all broadcast receivers (including BOOT_COMPLETED)
|
||||
* Blocking of all JobScheduler jobs
|
||||
* Blocking of AlarmManager callbacks
|
||||
* Your app will NOT run until the user manually launches it again
|
||||
|
||||
**Directive**: Accept that FORCE STOP is a hard kill. No scheduling, alarms, jobs, or receivers may execute afterward.
|
||||
|
||||
#### 3.2 You cannot auto-resume after "Force Stop"
|
||||
|
||||
You may only resume tasks when:
|
||||
|
||||
* The user opens your app
|
||||
* The user taps a notification belonging to your app
|
||||
* The user interacts with a widget/deep link
|
||||
* Another app explicitly targets your component
|
||||
|
||||
**Directive**: Provide user-facing reactivation pathways (icon, widget, notification).
|
||||
|
||||
#### 3.3 Alarms cannot be preserved solely in RAM
|
||||
|
||||
Android can kill your app's RAM state at any time.
|
||||
|
||||
**Directive**: All alarm data must be persisted in durable storage.
|
||||
|
||||
#### 3.4 You cannot bypass Doze or battery optimization restrictions without permission
|
||||
|
||||
Doze may defer inexact alarms; exact alarms with `setExactAndAllowWhileIdle` are allowed.
|
||||
|
||||
**Required Permission**: `SCHEDULE_EXACT_ALARM` on Android 12+ (API 31+)
|
||||
|
||||
---
|
||||
|
||||
## 3. iOS Notification Capability Matrix
|
||||
|
||||
| Scenario | Will Notification Fire? | OS Behavior | App Responsibility |
|
||||
| --------------------------------------- | ----------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| **Swipe from App Switcher** | ✅ Yes | UNUserNotificationCenter persists and fires notifications | None (OS handles) |
|
||||
| **App Terminated by System** | ✅ Yes | UNUserNotificationCenter persists and fires notifications | None (OS handles) |
|
||||
| **Device Reboot** | ✅ Yes (for calendar/time triggers) | iOS persists scheduled local notifications across reboot | None for notifications; must persist own state if needed |
|
||||
| **App Force Quit (swipe away)** | ✅ Yes | UNUserNotificationCenter persists and fires notifications | None (OS handles) |
|
||||
| **Background Execution** | ❌ No arbitrary code | Only BGTaskScheduler with strict limits | Cannot rely on background execution for recovery |
|
||||
| **Notification Fires** | ✅ Yes | Notification displayed; app code does NOT run unless user interacts | Must handle missed notifications on next app launch |
|
||||
| **User Taps Notification** | ✅ Yes | App launched; code can run | Can detect and handle missed notifications |
|
||||
|
||||
### iOS Allowed Behaviors
|
||||
|
||||
#### 3.1 Notifications survive app termination
|
||||
|
||||
`UNUserNotificationCenter` scheduled notifications **will fire** even after:
|
||||
|
||||
* App is swiped away from app switcher
|
||||
* App is terminated by system
|
||||
* Device reboots (for calendar/time-based triggers)
|
||||
|
||||
**Required API**: `UNUserNotificationCenter.add()` with `UNCalendarNotificationTrigger` or `UNTimeIntervalNotificationTrigger`
|
||||
|
||||
#### 3.2 Notifications persist across device reboot
|
||||
|
||||
iOS **automatically** persists scheduled local notifications across reboot.
|
||||
|
||||
**No app code required** for basic notification persistence.
|
||||
|
||||
**Limitation**: Only calendar and time-based triggers persist. Location-based triggers do not.
|
||||
|
||||
#### 3.3 Background tasks for prefetching
|
||||
|
||||
**Required API**: `BGTaskScheduler` with `BGAppRefreshTaskRequest`
|
||||
|
||||
**Limitations**:
|
||||
|
||||
* Minimum interval between tasks (system-controlled, typically hours)
|
||||
* System decides when to execute (not guaranteed)
|
||||
* Cannot rely on background execution for alarm recovery
|
||||
* Must schedule next task immediately after current one completes
|
||||
|
||||
### iOS Forbidden Behaviors
|
||||
|
||||
#### 4.1 App code does not run when notification fires
|
||||
|
||||
When a scheduled notification fires:
|
||||
|
||||
* Notification is displayed to user
|
||||
* **No app code executes** unless user taps the notification
|
||||
* Cannot run arbitrary code at notification time
|
||||
|
||||
**Workaround**: Use notification actions or handle missed notifications on next app launch.
|
||||
|
||||
#### 4.2 No repeating background execution
|
||||
|
||||
iOS does not provide repeating background execution APIs except:
|
||||
|
||||
* `BGTaskScheduler` (system-controlled, not guaranteed)
|
||||
* Background fetch (deprecated, unreliable)
|
||||
|
||||
**Directive**: Plugin cannot rely on background execution to reconstruct alarms. Must persist state and recover on app launch.
|
||||
|
||||
#### 4.3 No arbitrary code on notification trigger
|
||||
|
||||
Unlike Android's `PendingIntent` which can execute code, iOS notifications only:
|
||||
|
||||
* Display to user
|
||||
* Launch app if user taps
|
||||
* Execute notification action handlers (if configured)
|
||||
|
||||
**Directive**: All recovery logic must run on app launch, not at notification time.
|
||||
|
||||
#### 4.4 Background execution limits
|
||||
|
||||
**BGTaskScheduler Limitations**:
|
||||
|
||||
* Minimum intervals between tasks (system-controlled)
|
||||
* System may defer or skip tasks
|
||||
* Tasks have time budgets (typically 30 seconds)
|
||||
* Cannot guarantee execution timing
|
||||
|
||||
**Directive**: Use BGTaskScheduler for prefetching only, not for critical scheduling.
|
||||
|
||||
---
|
||||
|
||||
## 4. Cross-Platform Comparison
|
||||
|
||||
| Feature | Android | iOS |
|
||||
| -------------------------------- | --------------------------------------- | --------------------------------------------- |
|
||||
| **Survives swipe/termination** | ✅ Yes (with exact alarms) | ✅ Yes (automatic) |
|
||||
| **Survives reboot** | ❌ No (must reschedule) | ✅ Yes (automatic for calendar/time triggers) |
|
||||
| **App code runs on trigger** | ✅ Yes (via PendingIntent) | ❌ No (only if user interacts) |
|
||||
| **Background execution** | ✅ WorkManager, JobScheduler | ⚠️ Limited (BGTaskScheduler only) |
|
||||
| **Force stop equivalent** | ✅ Force Stop (hard kill) | ❌ No user-facing equivalent |
|
||||
| **Boot recovery required** | ✅ Yes (must implement) | ❌ No (OS handles) |
|
||||
| **Missed alarm detection** | ✅ Must implement on app launch | ✅ Must implement on app launch |
|
||||
| **Exact timing** | ✅ Yes (with permission) | ⚠️ ±180s tolerance |
|
||||
| **Repeating notifications** | ✅ Must reschedule each occurrence | ✅ Can use `repeats: true` in trigger |
|
||||
|
||||
---
|
||||
|
||||
## 5. Required Platform APIs
|
||||
|
||||
### Android
|
||||
|
||||
**Alarm Scheduling**:
|
||||
* `AlarmManager.setExactAndAllowWhileIdle()` - Android 6.0+ (API 23+)
|
||||
* `AlarmManager.setAlarmClock()` - Android 5.0+ (API 21+)
|
||||
* `AlarmManager.setExact()` - Android 4.4+ (API 19+)
|
||||
|
||||
**Permissions**:
|
||||
* `RECEIVE_BOOT_COMPLETED` - Boot receiver
|
||||
* `SCHEDULE_EXACT_ALARM` - Android 12+ (API 31+)
|
||||
|
||||
**Background Work**:
|
||||
* `WorkManager` - Deferrable background work
|
||||
* `JobScheduler` - Alternative (API 21+)
|
||||
|
||||
### iOS
|
||||
|
||||
**Notification Scheduling**:
|
||||
* `UNUserNotificationCenter.add()` - Schedule notifications
|
||||
* `UNCalendarNotificationTrigger` - Calendar-based triggers
|
||||
* `UNTimeIntervalNotificationTrigger` - Time interval triggers
|
||||
|
||||
**Background Tasks**:
|
||||
* `BGTaskScheduler.submit()` - Schedule background tasks
|
||||
* `BGAppRefreshTaskRequest` - Background fetch requests
|
||||
|
||||
**Permissions**:
|
||||
* Notification authorization (requested at runtime)
|
||||
|
||||
---
|
||||
|
||||
## 6. Platform-Specific Constraints Summary
|
||||
|
||||
### Android Constraints
|
||||
|
||||
1. **Reboot**: All alarms wiped; must reschedule from persistent storage
|
||||
2. **Force Stop**: Hard kill; cannot bypass until user opens app
|
||||
3. **Doze**: Inexact alarms deferred; must use exact alarms
|
||||
4. **Exact Alarm Permission**: Required on Android 12+ for precise timing
|
||||
5. **Boot Receiver**: Must be registered and handle `BOOT_COMPLETED`
|
||||
|
||||
### iOS Constraints
|
||||
|
||||
1. **Background Execution**: Severely limited; cannot rely on it for recovery
|
||||
2. **Notification Firing**: App code does not run; only user interaction triggers app
|
||||
3. **Timing Tolerance**: ±180 seconds for calendar triggers
|
||||
4. **BGTaskScheduler**: System-controlled; not guaranteed execution
|
||||
5. **State Persistence**: Must persist own state if tracking missed notifications
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Plugin Behavior Exploration Template](./plugin-behavior-exploration-template.md) - Uses this reference
|
||||
- [Plugin Requirements & Implementation](./plugin-requirements-implementation.md) - Implementation based on this reference
|
||||
- [Android Alarm Persistence Directive](./android-alarm-persistence-directive.md) - Original Android reference
|
||||
- [Improve Alarm Directives](./improve-alarm-directives.md) - Improvement directive
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0** (November 2025): Initial platform capability reference
|
||||
- Android alarm matrix
|
||||
- iOS notification matrix
|
||||
- Cross-platform comparison
|
||||
|
||||
@@ -1,363 +0,0 @@
|
||||
# Plugin Behavior Exploration Template
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Active Exploration Template
|
||||
|
||||
## Purpose
|
||||
|
||||
This document provides an **executable template** for exploring and documenting the current plugin's alarm/schedule/notification behavior on Android and iOS.
|
||||
|
||||
**Use this template to**:
|
||||
1. Test plugin behavior across different scenarios
|
||||
2. Document expected vs actual results
|
||||
3. Identify gaps between current behavior and platform capabilities
|
||||
4. Generate findings for the Plugin Requirements document
|
||||
|
||||
**Reference**: See [Platform Capability Reference](./platform-capability-reference.md) for OS-level facts.
|
||||
|
||||
---
|
||||
|
||||
## 0. Quick Reference: Platform Capabilities
|
||||
|
||||
**Android**: See [Platform Capability Reference - Android Section](./platform-capability-reference.md#2-android-alarm-capability-matrix)
|
||||
|
||||
**iOS**: See [Platform Capability Reference - iOS Section](./platform-capability-reference.md#3-ios-notification-capability-matrix)
|
||||
|
||||
**Key Differences**:
|
||||
* Android: Alarms wiped on reboot; must reschedule
|
||||
* iOS: Notifications persist across reboot automatically
|
||||
* Android: App code runs when alarm fires
|
||||
* iOS: App code does NOT run when notification fires (unless user interacts)
|
||||
|
||||
---
|
||||
|
||||
## 1. Android Exploration
|
||||
|
||||
### 1.1 Code-Level Inspection Checklist
|
||||
|
||||
**Source Locations**:
|
||||
- Plugin: `android/src/main/java/com/timesafari/dailynotification/`
|
||||
- Test App: `test-apps/android-test-app/`
|
||||
- Manifest: `test-apps/android-test-app/app/src/main/AndroidManifest.xml`
|
||||
|
||||
| Task | File/Function | Line | Status | Notes |
|
||||
| ---- | ------------- | ---- | ------ | ----- |
|
||||
| Locate main plugin class | `DailyNotificationPlugin.kt` | 1302 | ☐ | `scheduleDailyNotification()` |
|
||||
| Identify alarm scheduling | `NotifyReceiver.kt` | 92 | ☐ | `scheduleExactNotification()` |
|
||||
| Check AlarmManager usage | `NotifyReceiver.kt` | 219, 223, 231 | ☐ | `setAlarmClock()`, `setExactAndAllowWhileIdle()`, `setExact()` |
|
||||
| Check WorkManager usage | `FetchWorker.kt` | 31 | ☐ | `scheduleFetch()` |
|
||||
| Check notification display | `DailyNotificationWorker.java` | 200+ | ☐ | `displayNotification()` |
|
||||
| Check boot receiver | `BootReceiver.kt` | 24 | ☐ | `onReceive()` handles `BOOT_COMPLETED` |
|
||||
| Check persistence | `DailyNotificationPlugin.kt` | 1393+ | ☐ | Room database storage |
|
||||
| Check exact alarm permission | `DailyNotificationPlugin.kt` | 1309 | ☐ | `canScheduleExactAlarms()` |
|
||||
| Check manifest permissions | `AndroidManifest.xml` | - | ☐ | `RECEIVE_BOOT_COMPLETED`, `SCHEDULE_EXACT_ALARM` |
|
||||
|
||||
### 1.2 Behavior Testing Matrix
|
||||
|
||||
#### Test 1: Base Case
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule alarm 2 minutes in future | - | Alarm scheduled | ☐ | |
|
||||
| 2 | Leave app in foreground/background | - | - | ☐ | |
|
||||
| 3 | Wait for trigger time | Alarm fires | Notification displayed | ☐ | |
|
||||
| 4 | Check logs | - | No errors | ☐ | |
|
||||
|
||||
**Code Reference**: `NotifyReceiver.scheduleExactNotification()` line 92
|
||||
|
||||
---
|
||||
|
||||
#### Test 2: Swipe from Recents
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule alarm 2-5 minutes in future | - | Alarm scheduled | ☐ | |
|
||||
| 2 | Swipe app away from recents | - | - | ☐ | |
|
||||
| 3 | Wait for trigger time | ✅ Alarm fires (OS resurrects process) | ✅ Notification displayed | ☐ | |
|
||||
| 4 | Check app state on wake | Cold start | App process recreated | ☐ | |
|
||||
| 5 | Check logs | - | No errors | ☐ | |
|
||||
|
||||
**Code Reference**: `NotifyReceiver.scheduleExactNotification()` uses `setAlarmClock()` line 219
|
||||
|
||||
**Platform Behavior**: OS-guaranteed (Android AlarmManager)
|
||||
|
||||
---
|
||||
|
||||
#### Test 3: OS Kill (Memory Pressure)
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule alarm 2-5 minutes in future | - | Alarm scheduled | ☐ | |
|
||||
| 2 | Force kill via `adb shell am kill <package>` | - | - | ☐ | |
|
||||
| 3 | Wait for trigger time | ✅ Alarm fires | ✅ Notification displayed | ☐ | |
|
||||
| 4 | Check logs | - | No errors | ☐ | |
|
||||
|
||||
**Platform Behavior**: OS-guaranteed (Android AlarmManager)
|
||||
|
||||
---
|
||||
|
||||
#### Test 4: Device Reboot
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule alarm 10 minutes in future | - | Alarm scheduled | ☐ | |
|
||||
| 2 | Reboot device | - | - | ☐ | |
|
||||
| 3 | Do NOT open app | ❌ Alarm does NOT fire | ❌ No notification | ☐ | |
|
||||
| 4 | Wait past scheduled time | ❌ No automatic firing | ❌ No notification | ☐ | |
|
||||
| 5 | Open app manually | - | Plugin detects missed alarm | ☐ | |
|
||||
| 6 | Check missed alarm handling | - | ✅ Missed alarm detected | ☐ | |
|
||||
| 7 | Check rescheduling | - | ✅ Future alarms rescheduled | ☐ | |
|
||||
|
||||
**Code Reference**:
|
||||
- Boot receiver: `BootReceiver.kt` line 24
|
||||
- Rescheduling: `BootReceiver.kt` line 38+
|
||||
|
||||
**Platform Behavior**: Plugin-guaranteed (must implement boot receiver)
|
||||
|
||||
**Expected Plugin Behavior**: Plugin must reschedule from database on boot
|
||||
|
||||
---
|
||||
|
||||
#### Test 5: Android Force Stop
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule alarm | - | Alarm scheduled | ☐ | |
|
||||
| 2 | Go to Settings → Apps → [App] → Force Stop | ❌ All alarms removed | ❌ All alarms removed | ☐ | |
|
||||
| 3 | Wait for trigger time | ❌ Alarm does NOT fire | ❌ No notification | ☐ | |
|
||||
| 4 | Open app again | - | Plugin detects missed alarm | ☐ | |
|
||||
| 5 | Check recovery | - | ✅ Missed alarm detected | ☐ | |
|
||||
| 6 | Check rescheduling | - | ✅ Future alarms rescheduled | ☐ | |
|
||||
|
||||
**Platform Behavior**: Not allowed (Android hard kill)
|
||||
|
||||
**Expected Plugin Behavior**: Plugin must detect and recover on app restart
|
||||
|
||||
---
|
||||
|
||||
#### Test 6: Exact Alarm Permission (Android 12+)
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Revoke exact alarm permission | - | - | ☐ | |
|
||||
| 2 | Attempt to schedule alarm | - | Plugin requests permission | ☐ | |
|
||||
| 3 | Check settings opened | - | ✅ Settings opened | ☐ | |
|
||||
| 4 | Grant permission | - | - | ☐ | |
|
||||
| 5 | Schedule alarm | - | ✅ Alarm scheduled | ☐ | |
|
||||
| 6 | Verify alarm fires | ✅ Alarm fires | ✅ Notification displayed | ☐ | |
|
||||
|
||||
**Code Reference**: `DailyNotificationPlugin.kt` line 1309, 1314-1324
|
||||
|
||||
---
|
||||
|
||||
### 1.3 Persistence Investigation
|
||||
|
||||
| Item | Expected | Actual | Code Reference | Notes |
|
||||
| ---- | -------- | ------ | -------------- | ----- |
|
||||
| Alarm ID stored | ✅ Yes | ☐ | `DailyNotificationPlugin.kt` line 1393+ | |
|
||||
| Trigger time stored | ✅ Yes | ☐ | Room database | |
|
||||
| Repeat rule stored | ✅ Yes | ☐ | Schedule entity | |
|
||||
| Channel/priority stored | ✅ Yes | ☐ | NotificationContentEntity | |
|
||||
| Payload stored | ✅ Yes | ☐ | ContentCache | |
|
||||
| Time created/modified | ✅ Yes | ☐ | Entity timestamps | |
|
||||
|
||||
**Storage Location**: Room database (`DailyNotificationDatabase`)
|
||||
|
||||
---
|
||||
|
||||
### 1.4 Recovery Points Investigation
|
||||
|
||||
| Recovery Point | Expected Behavior | Actual Behavior | Code Reference | Notes |
|
||||
| -------------- | ----------------- | --------------- | -------------- | ----- |
|
||||
| Boot event | ✅ Reschedule all alarms | ☐ | `BootReceiver.kt` line 24 | |
|
||||
| App cold start | ✅ Detect missed alarms | ☐ | Check plugin initialization | |
|
||||
| App warm start | ✅ Verify active alarms | ☐ | Check plugin initialization | |
|
||||
| Background fetch return | ⚠️ May reschedule | ☐ | `FetchWorker.kt` | |
|
||||
| User taps notification | ✅ Launch app | ☐ | Notification intent | |
|
||||
|
||||
---
|
||||
|
||||
## 2. iOS Exploration
|
||||
|
||||
### 2.1 Code-Level Inspection Checklist
|
||||
|
||||
**Source Locations**:
|
||||
- Plugin: `ios/Plugin/`
|
||||
- Test App: `test-apps/ios-test-app/`
|
||||
- Alternative: Check `ios-2` branch
|
||||
|
||||
| Task | File/Function | Line | Status | Notes |
|
||||
| ---- | ------------- | ---- | ------ | ----- |
|
||||
| Locate main plugin class | `DailyNotificationPlugin.swift` | 506 | ☐ | `scheduleUserNotification()` |
|
||||
| Identify notification scheduling | `DailyNotificationScheduler.swift` | 133 | ☐ | `scheduleNotification()` |
|
||||
| Check UNUserNotificationCenter usage | `DailyNotificationScheduler.swift` | 185 | ☐ | `notificationCenter.add()` |
|
||||
| Check trigger types | `DailyNotificationScheduler.swift` | 172 | ☐ | `UNCalendarNotificationTrigger` |
|
||||
| Check BGTaskScheduler usage | `DailyNotificationPlugin.swift` | 495 | ☐ | `scheduleBackgroundFetch()` |
|
||||
| Check persistence | `DailyNotificationPlugin.swift` | 35 | ☐ | `storage: DailyNotificationStorage?` |
|
||||
| Check app launch recovery | `DailyNotificationPlugin.swift` | 42 | ☐ | `load()` method |
|
||||
|
||||
### 2.2 Behavior Testing Matrix
|
||||
|
||||
#### Test 1: Base Case
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule notification 2-5 minutes in future | - | Notification scheduled | ☐ | |
|
||||
| 2 | Leave app backgrounded | - | - | ☐ | |
|
||||
| 3 | Wait for trigger time | ✅ Notification fires | ✅ Notification displayed | ☐ | |
|
||||
| 4 | Check logs | - | No errors | ☐ | |
|
||||
|
||||
**Code Reference**: `DailyNotificationScheduler.scheduleNotification()` line 133
|
||||
|
||||
---
|
||||
|
||||
#### Test 2: Swipe App Away
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule notification 2-5 minutes in future | - | Notification scheduled | ☐ | |
|
||||
| 2 | Swipe app away from app switcher | - | - | ☐ | |
|
||||
| 3 | Wait for trigger time | ✅ Notification fires (OS handles) | ✅ Notification displayed | ☐ | |
|
||||
| 4 | Check app state | App terminated | App not running | ☐ | |
|
||||
|
||||
**Platform Behavior**: OS-guaranteed (iOS UNUserNotificationCenter)
|
||||
|
||||
---
|
||||
|
||||
#### Test 3: Device Reboot
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule notification for future time | - | Notification scheduled | ☐ | |
|
||||
| 2 | Reboot device | - | - | ☐ | |
|
||||
| 3 | Do NOT open app | ✅ Notification fires (OS persists) | ✅ Notification displayed | ☐ | |
|
||||
| 4 | Check notification timing | ✅ On time (±180s tolerance) | ✅ On time | ☐ | |
|
||||
|
||||
**Platform Behavior**: OS-guaranteed (iOS persists calendar/time triggers)
|
||||
|
||||
**Note**: Only calendar and time-based triggers persist. Location triggers do not.
|
||||
|
||||
---
|
||||
|
||||
#### Test 4: Hard Termination & Relaunch
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule repeating notifications | - | Notifications scheduled | ☐ | |
|
||||
| 2 | Terminate app via Xcode/switcher | - | - | ☐ | |
|
||||
| 3 | Allow some triggers to occur | ✅ Notifications fire | ✅ Notifications displayed | ☐ | |
|
||||
| 4 | Reopen app | - | Plugin checks for missed events | ☐ | |
|
||||
| 5 | Check missed event detection | ⚠️ May detect | ☐ | Plugin-specific |
|
||||
| 6 | Check state recovery | ⚠️ May recover | ☐ | Plugin-specific |
|
||||
|
||||
**Platform Behavior**: OS-guaranteed for notifications; Plugin-guaranteed for missed event detection
|
||||
|
||||
---
|
||||
|
||||
#### Test 5: Background Execution Limits
|
||||
|
||||
| Step | Action | Expected (OS) | Expected (Plugin) | Actual Result | Notes |
|
||||
| ---- | ------ | ------------- | ------------------ | ------------- | ----- |
|
||||
| 1 | Schedule BGTaskScheduler task | - | Task scheduled | ☐ | |
|
||||
| 2 | Wait for system to execute | ⚠️ System-controlled | ⚠️ May not execute | ☐ | |
|
||||
| 3 | Check execution timing | ⚠️ Not guaranteed | ⚠️ Not guaranteed | ☐ | |
|
||||
| 4 | Check time budget | ⚠️ ~30 seconds | ⚠️ Limited time | ☐ | |
|
||||
|
||||
**Code Reference**: `DailyNotificationPlugin.scheduleBackgroundFetch()` line 495
|
||||
|
||||
**Platform Behavior**: System-controlled (not guaranteed)
|
||||
|
||||
---
|
||||
|
||||
### 2.3 Persistence Investigation
|
||||
|
||||
| Item | Expected | Actual | Code Reference | Notes |
|
||||
| ---- | -------- | ------ | -------------- | ----- |
|
||||
| Notification ID stored | ✅ Yes (in UNUserNotificationCenter) | ☐ | `UNNotificationRequest` | |
|
||||
| Plugin-side storage | ⚠️ May not exist | ☐ | `DailyNotificationStorage?` | |
|
||||
| Trigger time stored | ✅ Yes (in trigger) | ☐ | `UNCalendarNotificationTrigger` | |
|
||||
| Repeat rule stored | ✅ Yes (in trigger) | ☐ | `repeats: true/false` | |
|
||||
| Payload stored | ✅ Yes (in userInfo) | ☐ | `notificationContent.userInfo` | |
|
||||
|
||||
**Storage Location**:
|
||||
- Primary: UNUserNotificationCenter (OS-managed)
|
||||
- Secondary: Plugin storage (if implemented)
|
||||
|
||||
---
|
||||
|
||||
### 2.4 Recovery Points Investigation
|
||||
|
||||
| Recovery Point | Expected Behavior | Actual Behavior | Code Reference | Notes |
|
||||
| -------------- | ----------------- | --------------- | -------------- | ----- |
|
||||
| Boot event | ✅ Notifications fire automatically | ☐ | OS handles | |
|
||||
| App cold start | ⚠️ May detect missed notifications | ☐ | Check `load()` method | |
|
||||
| App warm start | ⚠️ May verify pending notifications | ☐ | Check plugin initialization | |
|
||||
| Background fetch | ⚠️ May reschedule | ☐ | `BGTaskScheduler` | |
|
||||
| User taps notification | ✅ App launched | ☐ | Notification action | |
|
||||
|
||||
---
|
||||
|
||||
## 3. Cross-Platform Comparison
|
||||
|
||||
### 3.1 Observed Behavior Summary
|
||||
|
||||
| Scenario | Android (Observed) | iOS (Observed) | Platform Difference |
|
||||
| -------- | ------------------ | -------------- | ------------------- |
|
||||
| Swipe/termination | ☐ | ☐ | Both should work |
|
||||
| Reboot | ☐ | ☐ | iOS auto, Android manual |
|
||||
| Force stop | ☐ | N/A | Android only |
|
||||
| App code on trigger | ☐ | ☐ | Android yes, iOS no |
|
||||
| Background execution | ☐ | ☐ | Android more flexible |
|
||||
|
||||
---
|
||||
|
||||
## 4. Findings & Gaps
|
||||
|
||||
### 4.1 Android Gaps
|
||||
|
||||
| Gap | Severity | Description | Recommendation |
|
||||
| --- | -------- | ----------- | -------------- |
|
||||
| Boot recovery | ☐ High/Medium/Low | Does plugin reschedule on boot? | Implement if missing |
|
||||
| Missed alarm detection | ☐ High/Medium/Low | Does plugin detect missed alarms? | Implement if missing |
|
||||
| Force stop recovery | ☐ High/Medium/Low | Does plugin recover after force stop? | Implement if missing |
|
||||
| Persistence completeness | ☐ High/Medium/Low | Are all required fields persisted? | Verify and add if missing |
|
||||
|
||||
### 4.2 iOS Gaps
|
||||
|
||||
| Gap | Severity | Description | Recommendation |
|
||||
| --- | -------- | ----------- | -------------- |
|
||||
| Missed notification detection | ☐ High/Medium/Low | Does plugin detect missed notifications? | Implement if missing |
|
||||
| Plugin-side persistence | ☐ High/Medium/Low | Does plugin persist state separately? | Consider if needed |
|
||||
| Background task reliability | ☐ High/Medium/Low | Can plugin rely on BGTaskScheduler? | Document limitations |
|
||||
|
||||
---
|
||||
|
||||
## 5. Deliverables from This Exploration
|
||||
|
||||
After completing this exploration, generate:
|
||||
|
||||
1. **ALARMS_BEHAVIOR_MATRIX.md** - Completed test results
|
||||
2. **PLUGIN_ALARM_LIMITATIONS.md** - Documented limitations and gaps
|
||||
3. **Annotated code pointers** - Code locations with findings
|
||||
4. **Open Questions / TODOs** - Unresolved issues
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Platform Capability Reference](./platform-capability-reference.md) - OS-level facts
|
||||
- [Plugin Requirements & Implementation](./plugin-requirements-implementation.md) - Requirements based on findings
|
||||
- [Improve Alarm Directives](./improve-alarm-directives.md) - Improvement directive
|
||||
|
||||
---
|
||||
|
||||
## Notes for Explorers
|
||||
|
||||
* Fill in checkboxes (☐) as you complete each test
|
||||
* Document actual results in "Actual Result" columns
|
||||
* Add notes for any unexpected behavior
|
||||
* Reference code locations when documenting findings
|
||||
* Update "Findings & Gaps" section as you discover issues
|
||||
* Use platform capability reference to understand expected OS behavior
|
||||
|
||||
@@ -1,552 +0,0 @@
|
||||
# Plugin Requirements & Implementation Directive
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: November 2025
|
||||
**Status**: Active Requirements - Implementation Guide
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the **rules the plugin must follow** to behave predictably across Android and iOS platforms. It specifies:
|
||||
|
||||
* Persistence requirements
|
||||
* Recovery strategies
|
||||
* JS/TS API contract and caveats
|
||||
* Missed alarm handling
|
||||
* Platform-specific requirements
|
||||
* Testing requirements
|
||||
|
||||
**This document should be updated** after exploration findings are documented.
|
||||
|
||||
**Reference**: See [Platform Capability Reference](./platform-capability-reference.md) for OS-level facts.
|
||||
|
||||
---
|
||||
|
||||
## 1. Core Requirements
|
||||
|
||||
### 1.1 Plugin Behavior Guarantees
|
||||
|
||||
The plugin **must** guarantee the following behaviors:
|
||||
|
||||
| Behavior | Android | iOS | Implementation Required |
|
||||
| -------- | ------- | --- | ----------------------- |
|
||||
| Notification fires after swipe/termination | ✅ Yes | ✅ Yes | OS-guaranteed (verify) |
|
||||
| Notification fires after reboot | ⚠️ Only if rescheduled | ✅ Yes | Android: Boot receiver required |
|
||||
| Missed alarm detection | ✅ Required | ✅ Required | Both: App launch recovery |
|
||||
| Force stop recovery | ✅ Required | N/A | Android: App restart recovery |
|
||||
| Exact timing | ✅ With permission | ⚠️ ±180s tolerance | Android: Permission check |
|
||||
|
||||
### 1.2 Plugin Behavior Limitations
|
||||
|
||||
The plugin **cannot** guarantee:
|
||||
|
||||
| Limitation | Platform | Reason |
|
||||
| ---------- | -------- | ------ |
|
||||
| Notification after Force Stop (Android) | Android | OS hard kill |
|
||||
| App code execution on iOS notification fire | iOS | OS limitation |
|
||||
| Background execution timing (iOS) | iOS | System-controlled |
|
||||
| Exact timing (iOS) | iOS | ±180s tolerance |
|
||||
|
||||
---
|
||||
|
||||
## 2. Persistence Requirements
|
||||
|
||||
### 2.1 Required Persistence Items
|
||||
|
||||
The plugin **must** persist the following for each scheduled alarm/notification:
|
||||
|
||||
| Field | Type | Required | Purpose |
|
||||
| ----- | ---- | -------- | ------- |
|
||||
| `alarm_id` | String | ✅ Yes | Unique identifier |
|
||||
| `trigger_time` | Long/TimeInterval | ✅ Yes | When to fire |
|
||||
| `repeat_rule` | String/Enum | ✅ Yes | NONE, DAILY, WEEKLY, CUSTOM |
|
||||
| `channel_id` | String | ✅ Yes | Notification channel (Android) |
|
||||
| `priority` | String/Int | ✅ Yes | Notification priority |
|
||||
| `title` | String | ✅ Yes | Notification title |
|
||||
| `body` | String | ✅ Yes | Notification body |
|
||||
| `sound_enabled` | Boolean | ✅ Yes | Sound preference |
|
||||
| `vibration_enabled` | Boolean | ✅ Yes | Vibration preference |
|
||||
| `payload` | String/JSON | ⚠️ Optional | Additional content |
|
||||
| `created_at` | Long/TimeInterval | ✅ Yes | Creation timestamp |
|
||||
| `updated_at` | Long/TimeInterval | ✅ Yes | Last update timestamp |
|
||||
| `enabled` | Boolean | ✅ Yes | Whether alarm is active |
|
||||
|
||||
### 2.2 Storage Implementation
|
||||
|
||||
**Android**:
|
||||
* **Primary**: Room database (`DailyNotificationDatabase`)
|
||||
* **Location**: `android/src/main/java/com/timesafari/dailynotification/`
|
||||
* **Entities**: `Schedule`, `NotificationContentEntity`, `ContentCache`
|
||||
|
||||
**iOS**:
|
||||
* **Primary**: UNUserNotificationCenter (OS-managed)
|
||||
* **Secondary**: Plugin storage (UserDefaults, CoreData, or files)
|
||||
* **Location**: `ios/Plugin/`
|
||||
* **Component**: `DailyNotificationStorage?`
|
||||
|
||||
### 2.3 Persistence Validation
|
||||
|
||||
The plugin **must**:
|
||||
* Validate persistence on every alarm schedule
|
||||
* Log persistence failures
|
||||
* Handle persistence errors gracefully
|
||||
* Provide recovery mechanism if persistence fails
|
||||
|
||||
---
|
||||
|
||||
## 3. Recovery Requirements
|
||||
|
||||
### 3.1 Required Recovery Points
|
||||
|
||||
The plugin **must** implement recovery at the following points:
|
||||
|
||||
#### 3.1.1 Boot Event (Android Only)
|
||||
|
||||
**Trigger**: `BOOT_COMPLETED` broadcast
|
||||
|
||||
**Required Actions**:
|
||||
1. Load all enabled alarms from persistent storage
|
||||
2. Reschedule each alarm using AlarmManager
|
||||
3. Detect missed alarms (trigger_time < now)
|
||||
4. Generate missed alarm events/notifications
|
||||
5. Log recovery actions
|
||||
|
||||
**Code Reference**: `BootReceiver.kt` line 24
|
||||
|
||||
**Implementation Status**: ☐ Implemented / ☐ Missing
|
||||
|
||||
---
|
||||
|
||||
#### 3.1.2 App Cold Start
|
||||
|
||||
**Trigger**: App launched from terminated state
|
||||
|
||||
**Required Actions**:
|
||||
1. Load all enabled alarms from persistent storage
|
||||
2. Verify active alarms match stored alarms
|
||||
3. Detect missed alarms (trigger_time < now)
|
||||
4. Reschedule future alarms
|
||||
5. Generate missed alarm events/notifications
|
||||
6. Log recovery actions
|
||||
|
||||
**Implementation Status**: ☐ Implemented / ☐ Missing
|
||||
|
||||
**Code Location**: Check plugin initialization (`DailyNotificationPlugin.load()` or equivalent)
|
||||
|
||||
---
|
||||
|
||||
#### 3.1.3 App Warm Start
|
||||
|
||||
**Trigger**: App returning from background
|
||||
|
||||
**Required Actions**:
|
||||
1. Verify active alarms are still scheduled
|
||||
2. Detect missed alarms (trigger_time < now)
|
||||
3. Reschedule if needed
|
||||
4. Log recovery actions
|
||||
|
||||
**Implementation Status**: ☐ Implemented / ☐ Missing
|
||||
|
||||
---
|
||||
|
||||
#### 3.1.4 User Taps Notification
|
||||
|
||||
**Trigger**: User interaction with notification
|
||||
|
||||
**Required Actions**:
|
||||
1. Launch app (OS handles)
|
||||
2. Detect if notification was missed
|
||||
3. Handle notification action
|
||||
4. Update alarm state if needed
|
||||
|
||||
**Implementation Status**: ☐ Implemented / ☐ Missing
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Missed Alarm Handling
|
||||
|
||||
The plugin **must** detect and handle missed alarms:
|
||||
|
||||
**Definition**: An alarm is "missed" if:
|
||||
* `trigger_time < now`
|
||||
* Alarm was not fired (or firing status unknown)
|
||||
* Alarm is still enabled
|
||||
|
||||
**Required Actions**:
|
||||
1. **Detect** missed alarms during recovery
|
||||
2. **Generate** missed alarm event/notification
|
||||
3. **Reschedule** future occurrences (if repeating)
|
||||
4. **Log** missed alarm for debugging
|
||||
5. **Update** alarm state (mark as missed or reschedule)
|
||||
|
||||
**Implementation Requirements**:
|
||||
* Must run on app launch (cold/warm start)
|
||||
* Must run on boot (Android)
|
||||
* Must not duplicate missed alarm notifications
|
||||
* Must handle timezone changes
|
||||
|
||||
**Code Location**: To be implemented in recovery logic
|
||||
|
||||
---
|
||||
|
||||
## 4. JS/TS API Contract
|
||||
|
||||
### 4.1 API Guarantees
|
||||
|
||||
The plugin **must** document and guarantee the following behaviors to JavaScript/TypeScript developers:
|
||||
|
||||
#### 4.1.1 `scheduleDailyNotification(options)`
|
||||
|
||||
**Guarantees**:
|
||||
* ✅ Notification will fire if app is swiped from recents
|
||||
* ✅ Notification will fire if app is terminated by OS
|
||||
* ⚠️ Notification will fire after reboot **only if**:
|
||||
* Android: Boot receiver is registered and working
|
||||
* iOS: Automatic (OS handles)
|
||||
* ❌ Notification will **NOT** fire after Android Force Stop until app is opened
|
||||
* ⚠️ iOS notifications have ±180s timing tolerance
|
||||
|
||||
**Caveats**:
|
||||
* Android requires `SCHEDULE_EXACT_ALARM` permission on Android 12+
|
||||
* Android requires `RECEIVE_BOOT_COMPLETED` permission for reboot recovery
|
||||
* iOS requires notification authorization
|
||||
|
||||
**Error Codes**:
|
||||
* `EXACT_ALARM_PERMISSION_REQUIRED` - Android 12+ exact alarm permission needed
|
||||
* `NOTIFICATIONS_DENIED` - Notification permission denied
|
||||
* `SCHEDULE_FAILED` - Scheduling failed (check logs)
|
||||
|
||||
---
|
||||
|
||||
#### 4.1.2 `scheduleDailyReminder(options)`
|
||||
|
||||
**Guarantees**:
|
||||
* Same as `scheduleDailyNotification()` above
|
||||
* Static reminder (no content dependency)
|
||||
* Fires even if content fetch fails
|
||||
|
||||
---
|
||||
|
||||
#### 4.1.3 `getNotificationStatus()`
|
||||
|
||||
**Guarantees**:
|
||||
* Returns current notification status
|
||||
* Includes pending notifications
|
||||
* Includes last notification time
|
||||
* May include missed alarm information
|
||||
|
||||
---
|
||||
|
||||
### 4.2 API Warnings
|
||||
|
||||
The plugin **must** document the following warnings:
|
||||
|
||||
**Android**:
|
||||
* "Notifications will not fire after device reboot unless the app is opened at least once"
|
||||
* "Force Stop will prevent all notifications until the app is manually opened"
|
||||
* "Exact alarm permission is required on Android 12+ for precise timing"
|
||||
|
||||
**iOS**:
|
||||
* "Notifications have ±180 seconds timing tolerance"
|
||||
* "App code does not run when notifications fire (unless user interacts)"
|
||||
* "Background execution is system-controlled and not guaranteed"
|
||||
|
||||
**Cross-Platform**:
|
||||
* "Missed alarms are detected on app launch, not at trigger time"
|
||||
* "Repeating alarms must be rescheduled for each occurrence"
|
||||
|
||||
---
|
||||
|
||||
### 4.3 API Error Handling
|
||||
|
||||
The plugin **must**:
|
||||
* Return clear error messages
|
||||
* Include error codes for programmatic handling
|
||||
* Open system settings when permission is needed
|
||||
* Provide actionable guidance in error messages
|
||||
|
||||
**Example Error Response**:
|
||||
```typescript
|
||||
{
|
||||
code: "EXACT_ALARM_PERMISSION_REQUIRED",
|
||||
message: "Exact alarm permission required. Please grant 'Alarms & reminders' permission in Settings, then try again.",
|
||||
action: "opened_settings" // or "permission_denied"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Platform-Specific Requirements
|
||||
|
||||
### 5.1 Android Requirements
|
||||
|
||||
#### 5.1.1 Permissions
|
||||
|
||||
**Required Permissions**:
|
||||
* `RECEIVE_BOOT_COMPLETED` - Boot receiver
|
||||
* `SCHEDULE_EXACT_ALARM` - Android 12+ (API 31+) for exact alarms
|
||||
* `POST_NOTIFICATIONS` - Android 13+ (API 33+) for notifications
|
||||
|
||||
**Permission Handling**:
|
||||
* Check permission before scheduling
|
||||
* Request permission if not granted
|
||||
* Open system settings if permission denied
|
||||
* Provide clear error messages
|
||||
|
||||
**Code Reference**: `DailyNotificationPlugin.kt` line 1309
|
||||
|
||||
---
|
||||
|
||||
#### 5.1.2 Manifest Entries
|
||||
|
||||
**Required Manifest Entries**:
|
||||
```xml
|
||||
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
|
||||
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
|
||||
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
|
||||
|
||||
<receiver
|
||||
android:name="com.timesafari.dailynotification.BootReceiver"
|
||||
android:enabled="true"
|
||||
android:exported="true">
|
||||
<intent-filter>
|
||||
<action android:name="android.intent.action.BOOT_COMPLETED" />
|
||||
<action android:name="android.intent.action.LOCKED_BOOT_COMPLETED" />
|
||||
</intent-filter>
|
||||
</receiver>
|
||||
|
||||
<receiver
|
||||
android:name="com.timesafari.dailynotification.DailyNotificationReceiver"
|
||||
android:enabled="true"
|
||||
android:exported="false">
|
||||
<intent-filter>
|
||||
<action android:name="com.timesafari.daily.NOTIFICATION" />
|
||||
</intent-filter>
|
||||
</receiver>
|
||||
```
|
||||
|
||||
**Location**: Test app manifest: `test-apps/android-test-app/app/src/main/AndroidManifest.xml`
|
||||
|
||||
---
|
||||
|
||||
#### 5.1.3 Notification Channels
|
||||
|
||||
**Required Channels**:
|
||||
* `timesafari.daily` - Primary notification channel
|
||||
* `daily_reminders` - Reminder notifications (if used)
|
||||
|
||||
**Channel Configuration**:
|
||||
* Importance: HIGH (for alarms), DEFAULT (for reminders)
|
||||
* Sound: Enabled by default
|
||||
* Vibration: Enabled by default
|
||||
* Show badge: Enabled
|
||||
|
||||
**Code Reference**: `ChannelManager.java` or `NotifyReceiver.kt` line 454
|
||||
|
||||
---
|
||||
|
||||
#### 5.1.4 Alarm Scheduling
|
||||
|
||||
**Required API Usage**:
|
||||
* `setAlarmClock()` for Android 5.0+ (preferred)
|
||||
* `setExactAndAllowWhileIdle()` for Android 6.0+ (fallback)
|
||||
* `setExact()` for older versions (fallback)
|
||||
|
||||
**Code Reference**: `NotifyReceiver.kt` line 219, 223, 231
|
||||
|
||||
---
|
||||
|
||||
### 5.2 iOS Requirements
|
||||
|
||||
#### 5.2.1 Permissions
|
||||
|
||||
**Required Permissions**:
|
||||
* Notification authorization (requested at runtime)
|
||||
|
||||
**Permission Handling**:
|
||||
* Request permission before scheduling
|
||||
* Handle authorization status
|
||||
* Provide clear error messages
|
||||
|
||||
---
|
||||
|
||||
#### 5.2.2 Background Tasks
|
||||
|
||||
**Required Background Task Identifiers**:
|
||||
* `com.timesafari.dailynotification.fetch` - Background fetch
|
||||
* `com.timesafari.dailynotification.notify` - Notification task (if used)
|
||||
|
||||
**Background Task Registration**:
|
||||
* Register in `Info.plist`:
|
||||
```xml
|
||||
<key>BGTaskSchedulerPermittedIdentifiers</key>
|
||||
<array>
|
||||
<string>com.timesafari.dailynotification.fetch</string>
|
||||
</array>
|
||||
```
|
||||
|
||||
**Code Reference**: `DailyNotificationPlugin.swift` line 31-32
|
||||
|
||||
---
|
||||
|
||||
#### 5.2.3 Notification Scheduling
|
||||
|
||||
**Required API Usage**:
|
||||
* `UNUserNotificationCenter.add()` - Schedule notifications
|
||||
* `UNCalendarNotificationTrigger` - Calendar-based triggers (preferred)
|
||||
* `UNTimeIntervalNotificationTrigger` - Time interval triggers
|
||||
|
||||
**Code Reference**: `DailyNotificationScheduler.swift` line 185
|
||||
|
||||
---
|
||||
|
||||
#### 5.2.4 Notification Categories
|
||||
|
||||
**Required Categories**:
|
||||
* `DAILY_NOTIFICATION` - Primary notification category
|
||||
|
||||
**Category Configuration**:
|
||||
* Actions: Configure as needed
|
||||
* Options: Custom sound, custom actions
|
||||
|
||||
**Code Reference**: `DailyNotificationScheduler.swift` line 62+
|
||||
|
||||
---
|
||||
|
||||
## 6. Testing Requirements
|
||||
|
||||
### 6.1 Required Test Scenarios
|
||||
|
||||
The plugin **must** be tested for:
|
||||
|
||||
**Android**:
|
||||
* [ ] Base case (alarm fires on time)
|
||||
* [ ] Swipe from recents
|
||||
* [ ] OS kill (memory pressure)
|
||||
* [ ] Device reboot (with and without app launch)
|
||||
* [ ] Force stop (with app restart)
|
||||
* [ ] Exact alarm permission (Android 12+)
|
||||
* [ ] Boot receiver functionality
|
||||
* [ ] Missed alarm detection
|
||||
|
||||
**iOS**:
|
||||
* [ ] Base case (notification fires on time)
|
||||
* [ ] Swipe app away
|
||||
* [ ] Device reboot (without app launch)
|
||||
* [ ] Hard termination and relaunch
|
||||
* [ ] Background execution limits
|
||||
* [ ] Missed notification detection
|
||||
|
||||
**Cross-Platform**:
|
||||
* [ ] Timezone changes
|
||||
* [ ] Clock adjustments
|
||||
* [ ] Multiple simultaneous alarms
|
||||
* [ ] Repeating alarms
|
||||
* [ ] Alarm cancellation
|
||||
|
||||
---
|
||||
|
||||
### 6.2 Test Harness Requirements
|
||||
|
||||
**Required Test Tools**:
|
||||
* Real devices (not just emulators)
|
||||
* ADB commands for Android testing
|
||||
* Xcode for iOS testing
|
||||
* Log monitoring tools
|
||||
|
||||
**Required Test Documentation**:
|
||||
* Test results matrix
|
||||
* Log snippets for failures
|
||||
* Screenshots/videos for UI issues
|
||||
* Performance metrics
|
||||
|
||||
---
|
||||
|
||||
## 7. Versioning Requirements
|
||||
|
||||
### 7.1 Breaking Changes
|
||||
|
||||
Any change to alarm behavior is **breaking** and requires:
|
||||
|
||||
* **MAJOR version bump** (semantic versioning)
|
||||
* **Migration guide** for existing users
|
||||
* **Deprecation warnings** (if applicable)
|
||||
* **Clear changelog entry**
|
||||
|
||||
### 7.2 Non-Breaking Changes
|
||||
|
||||
Non-breaking changes include:
|
||||
* Bug fixes
|
||||
* Performance improvements
|
||||
* Additional features (backward compatible)
|
||||
* Documentation updates
|
||||
|
||||
---
|
||||
|
||||
## 8. Implementation Checklist
|
||||
|
||||
### 8.1 Android Implementation
|
||||
|
||||
- [ ] Boot receiver registered in manifest
|
||||
- [ ] Boot receiver reschedules alarms from database
|
||||
- [ ] Exact alarm permission checked and requested
|
||||
- [ ] Notification channels created
|
||||
- [ ] Alarm scheduling uses correct API (`setAlarmClock` preferred)
|
||||
- [ ] Persistence implemented (Room database)
|
||||
- [ ] Missed alarm detection on app launch
|
||||
- [ ] Force stop recovery on app restart
|
||||
- [ ] Error handling and user guidance
|
||||
|
||||
### 8.2 iOS Implementation
|
||||
|
||||
- [ ] Notification authorization requested
|
||||
- [ ] Background tasks registered in Info.plist
|
||||
- [ ] Notification scheduling uses UNUserNotificationCenter
|
||||
- [ ] Calendar triggers used (not just time interval)
|
||||
- [ ] Plugin-side persistence (if needed for missed detection)
|
||||
- [ ] Missed notification detection on app launch
|
||||
- [ ] Background task limitations documented
|
||||
- [ ] Error handling and user guidance
|
||||
|
||||
### 8.3 Cross-Platform Implementation
|
||||
|
||||
- [ ] JS/TS API contract documented
|
||||
- [ ] Platform-specific caveats documented
|
||||
- [ ] Error codes standardized
|
||||
- [ ] Test scenarios covered
|
||||
- [ ] Migration guide (if breaking changes)
|
||||
|
||||
---
|
||||
|
||||
## 9. Open Questions / TODOs
|
||||
|
||||
**To be filled after exploration**:
|
||||
|
||||
| Question | Platform | Priority | Status |
|
||||
| -------- | -------- | -------- | ------ |
|
||||
| Does boot receiver work correctly? | Android | High | ☐ |
|
||||
| Is missed alarm detection implemented? | Both | High | ☐ |
|
||||
| Are all required fields persisted? | Both | Medium | ☐ |
|
||||
| Is force stop recovery implemented? | Android | High | ☐ |
|
||||
| Does iOS plugin persist state separately? | iOS | Medium | ☐ |
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Platform Capability Reference](./platform-capability-reference.md) - OS-level facts
|
||||
- [Plugin Behavior Exploration Template](./plugin-behavior-exploration-template.md) - Exploration template
|
||||
- [Improve Alarm Directives](./improve-alarm-directives.md) - Improvement directive
|
||||
- [Boot Receiver Testing Guide](./boot-receiver-testing-guide.md) - Testing procedures
|
||||
- [App Startup Recovery Solution](./app-startup-recovery-solution.md) - Recovery mechanisms
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0** (November 2025): Initial requirements document
|
||||
- Persistence requirements
|
||||
- Recovery requirements
|
||||
- JS/TS API contract
|
||||
- Platform-specific requirements
|
||||
- Testing requirements
|
||||
|
||||
12
package-lock.json
generated
12
package-lock.json
generated
@@ -100,6 +100,7 @@
|
||||
"integrity": "sha512-vMqyb7XCDMPvJFFOaT9kxtiRh42GwlZEg1/uIgtZshS5a/8OaduUfCi7kynKgc3Tw/6Uo2D+db9qBttghhmxwQ==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@ampproject/remapping": "^2.2.0",
|
||||
"@babel/code-frame": "^7.26.2",
|
||||
@@ -649,6 +650,7 @@
|
||||
"resolved": "https://registry.npmjs.org/@capacitor/core/-/core-6.2.1.tgz",
|
||||
"integrity": "sha512-urZwxa7hVE/BnA18oCFAdizXPse6fCKanQyEqpmz6cBJ2vObwMpyJDG5jBeoSsgocS9+Ax+9vb4ducWJn0y2qQ==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"tslib": "^2.1.0"
|
||||
}
|
||||
@@ -751,6 +753,7 @@
|
||||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
},
|
||||
@@ -774,6 +777,7 @@
|
||||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
@@ -2925,6 +2929,7 @@
|
||||
"integrity": "sha512-VlJEV0fOQ7BExOsHYAGrgbEiZoi8D+Bl2+f6V2RrXerRSylnp+ZBHmPvaIa8cz0Ajx7WO7Z5RqfgYg7ED1nRhA==",
|
||||
"dev": true,
|
||||
"license": "BSD-2-Clause",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@typescript-eslint/scope-manager": "5.62.0",
|
||||
"@typescript-eslint/types": "5.62.0",
|
||||
@@ -3128,6 +3133,7 @@
|
||||
"integrity": "sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"acorn": "bin/acorn"
|
||||
},
|
||||
@@ -3543,6 +3549,7 @@
|
||||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"caniuse-lite": "^1.0.30001688",
|
||||
"electron-to-chromium": "^1.5.73",
|
||||
@@ -4692,6 +4699,7 @@
|
||||
"deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@eslint-community/eslint-utils": "^4.2.0",
|
||||
"@eslint-community/regexpp": "^4.6.1",
|
||||
@@ -6249,6 +6257,7 @@
|
||||
"integrity": "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@jest/core": "^29.7.0",
|
||||
"@jest/types": "^29.6.3",
|
||||
@@ -7115,6 +7124,7 @@
|
||||
"integrity": "sha512-Cvc9WUhxSMEo4McES3P7oK3QaXldCfNWp7pl2NNeiIFlCoLr3kfq9kb1fxftiwk1FLV7CvpvDfonxtzUDeSOPg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"cssstyle": "^4.2.1",
|
||||
"data-urls": "^5.0.0",
|
||||
@@ -9574,6 +9584,7 @@
|
||||
"integrity": "sha512-GVsDdsbJzzy4S/v3dqWPJ7EfvZJfCHiDqe80IyrF59LYuP+e6U1LJoUqeuqRbwAWoMNoXivMNeNAOf5E22VA1w==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"rollup": "dist/bin/rollup"
|
||||
},
|
||||
@@ -10526,6 +10537,7 @@
|
||||
"integrity": "sha512-mI4WrpHsbCIcwT9cF4FZvr80QUeKvsUsUvKDoR+X/7XHQH98xYD8YHZg7ANtz2GtZt/CBq2QJ0thkGJMHfqc1w==",
|
||||
"dev": true,
|
||||
"license": "Apache-2.0",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"tsc": "bin/tsc",
|
||||
"tsserver": "bin/tsserver"
|
||||
|
||||
@@ -62,11 +62,6 @@
|
||||
<div id="pluginStatusContent" style="margin-top: 8px;">
|
||||
Loading plugin status...
|
||||
</div>
|
||||
<div id="notificationReceivedIndicator" style="margin-top: 8px; padding: 8px; background: rgba(0, 255, 0, 0.2); border-radius: 5px; display: none;">
|
||||
<strong>🔔 Notification Received!</strong><br>
|
||||
<span id="notificationReceivedTime"></span><br>
|
||||
<small>Check the top of your screen for the notification banner</small>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -237,8 +232,7 @@
|
||||
const notificationTimeReadable = notificationTime.toLocaleTimeString();
|
||||
status.innerHTML = '✅ Notification scheduled!<br>' +
|
||||
'📥 Prefetch: ' + prefetchTimeReadable + ' (' + prefetchTimeString + ')<br>' +
|
||||
'🔔 Notification: ' + notificationTimeReadable + ' (' + notificationTimeString + ')<br><br>' +
|
||||
'<small>💡 When the notification fires, look for a banner at the <strong>top of your screen</strong>.</small>';
|
||||
'🔔 Notification: ' + notificationTimeReadable + ' (' + notificationTimeString + ')';
|
||||
status.style.background = 'rgba(0, 255, 0, 0.3)'; // Green background
|
||||
// Refresh plugin status display
|
||||
setTimeout(() => loadPluginStatus(), 500);
|
||||
@@ -417,39 +411,6 @@
|
||||
}
|
||||
}
|
||||
|
||||
// Check for notification delivery periodically
|
||||
function checkNotificationDelivery() {
|
||||
if (!window.DailyNotification) return;
|
||||
|
||||
window.DailyNotification.getNotificationStatus()
|
||||
.then(result => {
|
||||
if (result.lastNotificationTime) {
|
||||
const lastTime = new Date(result.lastNotificationTime);
|
||||
const now = new Date();
|
||||
const timeDiff = now - lastTime;
|
||||
|
||||
// If notification was received in the last 2 minutes, show indicator
|
||||
if (timeDiff > 0 && timeDiff < 120000) {
|
||||
const indicator = document.getElementById('notificationReceivedIndicator');
|
||||
const timeSpan = document.getElementById('notificationReceivedTime');
|
||||
|
||||
if (indicator && timeSpan) {
|
||||
indicator.style.display = 'block';
|
||||
timeSpan.textContent = `Received at ${lastTime.toLocaleTimeString()}`;
|
||||
|
||||
// Hide after 30 seconds
|
||||
setTimeout(() => {
|
||||
indicator.style.display = 'none';
|
||||
}, 30000);
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
.catch(error => {
|
||||
// Silently fail - this is just for visual feedback
|
||||
});
|
||||
}
|
||||
|
||||
// Load plugin status automatically on page load
|
||||
window.addEventListener('load', () => {
|
||||
console.log('Page loaded, loading plugin status...');
|
||||
@@ -458,9 +419,6 @@
|
||||
loadPluginStatus();
|
||||
loadPermissionStatus();
|
||||
loadChannelStatus();
|
||||
|
||||
// Check for notification delivery every 5 seconds
|
||||
setInterval(checkNotificationDelivery, 5000);
|
||||
}, 500);
|
||||
});
|
||||
|
||||
|
||||
@@ -1,560 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
# Phase 1 Testing Script - Interactive Test Runner
|
||||
# Guides through all Phase 1 tests with clear prompts for UI interaction
|
||||
|
||||
set -e # Exit on error
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Configuration
|
||||
PACKAGE="com.timesafari.dailynotification"
|
||||
ACTIVITY="${PACKAGE}/.MainActivity"
|
||||
APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_ROOT="$(cd "${APP_DIR}/../.." && pwd)"
|
||||
|
||||
# Functions
|
||||
print_header() {
|
||||
echo ""
|
||||
echo -e "${BLUE}========================================${NC}"
|
||||
echo -e "${BLUE}$1${NC}"
|
||||
echo -e "${BLUE}========================================${NC}"
|
||||
echo ""
|
||||
}
|
||||
|
||||
print_step() {
|
||||
echo -e "${GREEN}→ Step $1:${NC} $2"
|
||||
}
|
||||
|
||||
print_wait() {
|
||||
echo -e "${YELLOW}⏳ $1${NC}"
|
||||
}
|
||||
|
||||
print_success() {
|
||||
echo -e "${GREEN}✅ $1${NC}"
|
||||
}
|
||||
|
||||
print_error() {
|
||||
echo -e "${RED}❌ $1${NC}"
|
||||
}
|
||||
|
||||
print_info() {
|
||||
echo -e "${BLUE}ℹ️ $1${NC}"
|
||||
}
|
||||
|
||||
wait_for_user() {
|
||||
echo ""
|
||||
read -p "Press Enter when ready to continue..."
|
||||
echo ""
|
||||
}
|
||||
|
||||
wait_for_ui_action() {
|
||||
echo ""
|
||||
echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo -e "${YELLOW}👆 UI ACTION REQUIRED${NC}"
|
||||
echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo -e "${BLUE}$1${NC}"
|
||||
echo ""
|
||||
read -p "Press Enter after completing the action above..."
|
||||
echo ""
|
||||
}
|
||||
|
||||
check_adb_connection() {
|
||||
if ! adb devices | grep -q "device$"; then
|
||||
print_error "No Android device/emulator connected"
|
||||
echo "Please connect a device or start an emulator, then run:"
|
||||
echo " adb devices"
|
||||
exit 1
|
||||
fi
|
||||
print_success "ADB device connected"
|
||||
}
|
||||
|
||||
check_emulator_ready() {
|
||||
print_info "Checking emulator status..."
|
||||
if ! adb shell getprop sys.boot_completed | grep -q "1"; then
|
||||
print_wait "Waiting for emulator to boot..."
|
||||
adb wait-for-device
|
||||
while [ "$(adb shell getprop sys.boot_completed)" != "1" ]; do
|
||||
sleep 2
|
||||
done
|
||||
fi
|
||||
print_success "Emulator is ready"
|
||||
}
|
||||
|
||||
build_app() {
|
||||
print_header "Building Test App"
|
||||
|
||||
cd "${APP_DIR}"
|
||||
|
||||
print_step "1" "Building debug APK..."
|
||||
if ./gradlew assembleDebug; then
|
||||
print_success "Build successful"
|
||||
else
|
||||
print_error "Build failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
APK_PATH="${APP_DIR}/app/build/outputs/apk/debug/app-debug.apk"
|
||||
if [ ! -f "${APK_PATH}" ]; then
|
||||
print_error "APK not found at ${APK_PATH}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
print_success "APK ready: ${APK_PATH}"
|
||||
}
|
||||
|
||||
install_app() {
|
||||
print_header "Installing App"
|
||||
|
||||
print_step "1" "Uninstalling existing app (if present)..."
|
||||
UNINSTALL_OUTPUT=$(adb uninstall "${PACKAGE}" 2>&1)
|
||||
UNINSTALL_EXIT=$?
|
||||
|
||||
if [ ${UNINSTALL_EXIT} -eq 0 ]; then
|
||||
print_success "Existing app uninstalled"
|
||||
elif echo "${UNINSTALL_OUTPUT}" | grep -q "DELETE_FAILED_INTERNAL_ERROR"; then
|
||||
print_info "No existing app to uninstall (continuing)"
|
||||
elif echo "${UNINSTALL_OUTPUT}" | grep -q "Failure"; then
|
||||
print_info "Uninstall failed (app may not exist) - continuing with install"
|
||||
else
|
||||
print_info "Uninstall result unclear - continuing with install"
|
||||
fi
|
||||
|
||||
print_step "2" "Installing new APK..."
|
||||
if adb install -r "${APP_DIR}/app/build/outputs/apk/debug/app-debug.apk"; then
|
||||
print_success "App installed successfully"
|
||||
else
|
||||
print_error "Installation failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
print_step "3" "Verifying installation..."
|
||||
if adb shell pm list packages | grep -q "${PACKAGE}"; then
|
||||
print_success "App verified in package list"
|
||||
else
|
||||
print_error "App not found in package list"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
clear_logs() {
|
||||
print_info "Clearing logcat buffer..."
|
||||
adb logcat -c
|
||||
print_success "Logs cleared"
|
||||
}
|
||||
|
||||
launch_app() {
|
||||
print_info "Launching app..."
|
||||
adb shell am start -n "${ACTIVITY}"
|
||||
sleep 3 # Give app time to load and check status
|
||||
print_success "App launched"
|
||||
}
|
||||
|
||||
check_plugin_configured() {
|
||||
print_info "Checking if plugin is already configured..."
|
||||
|
||||
# Wait a moment for app to fully load
|
||||
sleep 3
|
||||
|
||||
# Check if database exists (indicates plugin has been used)
|
||||
DB_EXISTS=$(adb shell run-as "${PACKAGE}" ls databases/ 2>/dev/null | grep -c "daily_notification" || echo "0")
|
||||
|
||||
# Check if SharedPreferences has configuration (more reliable)
|
||||
# The plugin stores config in SharedPreferences
|
||||
PREFS_EXISTS=$(adb shell run-as "${PACKAGE}" ls shared_prefs/ 2>/dev/null | grep -c "DailyNotification" || echo "0")
|
||||
|
||||
# Check recent logs for configuration activity
|
||||
RECENT_CONFIG=$(adb logcat -d -t 50 | grep -E "Plugin configured|configurePlugin|Configuration" | tail -3)
|
||||
|
||||
if [ "${DB_EXISTS}" -gt "0" ] || [ "${PREFS_EXISTS}" -gt "0" ]; then
|
||||
print_success "Plugin appears to be configured (database or preferences exist)"
|
||||
|
||||
# Show user what to check in UI
|
||||
print_info "Please verify in the app UI that you see:"
|
||||
echo " ⚙️ Plugin Settings: ✅ Configured"
|
||||
echo " 🔌 Native Fetcher: ✅ Configured"
|
||||
echo ""
|
||||
echo "If both show ✅, the plugin is configured and you can skip configuration."
|
||||
echo "If either shows ❌ or 'Not configured', you'll need to click 'Configure Plugin'."
|
||||
echo ""
|
||||
|
||||
return 0
|
||||
else
|
||||
print_info "Plugin not configured (no database or preferences found)"
|
||||
print_info "You will need to click 'Configure Plugin' in the app UI"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
ensure_plugin_configured() {
|
||||
if check_plugin_configured; then
|
||||
# Plugin might be configured, but let user verify
|
||||
wait_for_ui_action "Please check the Plugin Status section at the top of the app.
|
||||
|
||||
If you see:
|
||||
- ⚙️ Plugin Settings: ✅ Configured
|
||||
- 🔌 Native Fetcher: ✅ Configured
|
||||
|
||||
Then the plugin is already configured - just press Enter to continue.
|
||||
|
||||
If either shows ❌ or 'Not configured', click 'Configure Plugin' button first,
|
||||
wait for both to show ✅, then press Enter."
|
||||
|
||||
# Give a moment for any configuration that just happened
|
||||
sleep 2
|
||||
print_success "Continuing with tests (plugin configuration verified or skipped)"
|
||||
return 0
|
||||
else
|
||||
# Plugin definitely needs configuration
|
||||
print_info "Plugin needs configuration"
|
||||
wait_for_ui_action "Click the 'Configure Plugin' button in the app UI.
|
||||
|
||||
Wait for the status to update:
|
||||
- ⚙️ Plugin Settings: Should change to ✅ Configured
|
||||
- 🔌 Native Fetcher: Should change to ✅ Configured
|
||||
|
||||
Once both show ✅, press Enter to continue."
|
||||
|
||||
# Verify configuration completed
|
||||
sleep 2
|
||||
print_success "Plugin configuration completed (or verified)"
|
||||
fi
|
||||
}
|
||||
|
||||
kill_app() {
|
||||
print_info "Killing app process..."
|
||||
adb shell am kill "${PACKAGE}"
|
||||
sleep 2
|
||||
|
||||
# Verify process is killed
|
||||
if adb shell ps | grep -q "${PACKAGE}"; then
|
||||
print_wait "Process still running, using force-stop..."
|
||||
adb shell am force-stop "${PACKAGE}"
|
||||
sleep 1
|
||||
fi
|
||||
|
||||
if ! adb shell ps | grep -q "${PACKAGE}"; then
|
||||
print_success "App process terminated"
|
||||
else
|
||||
print_error "App process still running"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
check_recovery_logs() {
|
||||
print_info "Checking recovery logs..."
|
||||
echo ""
|
||||
adb logcat -d | grep -E "DNP-REACTIVATION" | tail -10
|
||||
echo ""
|
||||
}
|
||||
|
||||
check_alarm_status() {
|
||||
print_info "Checking AlarmManager status..."
|
||||
echo ""
|
||||
adb shell dumpsys alarm | grep -i timesafari | head -5
|
||||
echo ""
|
||||
}
|
||||
|
||||
get_current_time() {
|
||||
adb shell date +%s
|
||||
}
|
||||
|
||||
# Main test execution
|
||||
main() {
|
||||
print_header "Phase 1 Testing Script"
|
||||
echo "This script will guide you through all Phase 1 tests."
|
||||
echo "You'll be prompted when UI interaction is needed."
|
||||
echo ""
|
||||
wait_for_user
|
||||
|
||||
# Pre-flight checks
|
||||
print_header "Pre-Flight Checks"
|
||||
check_adb_connection
|
||||
check_emulator_ready
|
||||
|
||||
# Build and install
|
||||
build_app
|
||||
install_app
|
||||
|
||||
# Clear logs
|
||||
clear_logs
|
||||
|
||||
# ============================================
|
||||
# TEST 1: Cold Start Missed Detection
|
||||
# ============================================
|
||||
print_header "TEST 1: Cold Start Missed Detection"
|
||||
echo "Purpose: Verify missed notifications are detected and marked."
|
||||
echo ""
|
||||
wait_for_user
|
||||
|
||||
print_step "1" "Launch app and check plugin status"
|
||||
launch_app
|
||||
ensure_plugin_configured
|
||||
|
||||
wait_for_ui_action "In the app UI, click the 'Test Notification' button.
|
||||
|
||||
This will schedule a notification for 4 minutes in the future.
|
||||
(The test app automatically schedules for 4 minutes from now)"
|
||||
|
||||
print_step "2" "Verifying notification was scheduled..."
|
||||
sleep 2
|
||||
check_alarm_status
|
||||
|
||||
print_info "Checking logs for scheduling confirmation..."
|
||||
adb logcat -d | grep -E "DN|SCHEDULE|Stored notification content" | tail -5
|
||||
|
||||
wait_for_ui_action "Verify in the logs above that you see:
|
||||
- 'Stored notification content in database' (NEW - should appear now)
|
||||
- Alarm scheduled in AlarmManager
|
||||
|
||||
If you don't see 'Stored notification content', the fix may not be working."
|
||||
|
||||
wait_for_user
|
||||
|
||||
print_step "3" "Killing app process (simulates OS kill)..."
|
||||
kill_app
|
||||
|
||||
print_step "4" "Getting alarm scheduled time..."
|
||||
ALARM_INFO=$(adb shell dumpsys alarm | grep -i timesafari | grep "origWhen" | head -1)
|
||||
if [ -n "${ALARM_INFO}" ]; then
|
||||
# Extract alarm time (origWhen is in milliseconds)
|
||||
ALARM_TIME_MS=$(echo "${ALARM_INFO}" | grep -oE 'origWhen [0-9]+' | awk '{print $2}')
|
||||
if [ -n "${ALARM_TIME_MS}" ]; then
|
||||
CURRENT_TIME=$(get_current_time)
|
||||
ALARM_TIME_SEC=$((ALARM_TIME_MS / 1000))
|
||||
WAIT_SECONDS=$((ALARM_TIME_SEC - CURRENT_TIME + 60)) # Wait 1 minute past alarm
|
||||
|
||||
if [ ${WAIT_SECONDS} -gt 0 ] && [ ${WAIT_SECONDS} -lt 600 ]; then
|
||||
ALARM_READABLE=$(date -d "@${ALARM_TIME_SEC}" 2>/dev/null || echo "${ALARM_TIME_SEC}")
|
||||
CURRENT_READABLE=$(date -d "@${CURRENT_TIME}" 2>/dev/null || echo "${CURRENT_TIME}")
|
||||
print_info "Alarm scheduled for: ${ALARM_READABLE}"
|
||||
print_info "Current time: ${CURRENT_READABLE}"
|
||||
print_wait "Waiting ${WAIT_SECONDS} seconds for alarm time to pass..."
|
||||
sleep ${WAIT_SECONDS}
|
||||
elif [ ${WAIT_SECONDS} -le 0 ]; then
|
||||
print_info "Alarm time has already passed"
|
||||
print_wait "Waiting 2 minutes to ensure we're well past alarm time..."
|
||||
sleep 120
|
||||
else
|
||||
print_wait "Alarm is more than 10 minutes away. Waiting 5 minutes (you can adjust this)..."
|
||||
sleep 300
|
||||
fi
|
||||
else
|
||||
print_wait "Could not parse alarm time. Waiting 5 minutes..."
|
||||
sleep 300
|
||||
fi
|
||||
else
|
||||
print_wait "Could not find alarm in AlarmManager. Waiting 5 minutes..."
|
||||
sleep 300
|
||||
fi
|
||||
|
||||
print_step "5" "Launching app (cold start - triggers recovery)..."
|
||||
clear_logs
|
||||
launch_app
|
||||
|
||||
print_step "6" "Checking recovery logs..."
|
||||
sleep 3
|
||||
check_recovery_logs
|
||||
|
||||
print_info "Expected log output:"
|
||||
echo " DNP-REACTIVATION: Starting app launch recovery (Phase 1: cold start only)"
|
||||
echo " DNP-REACTIVATION: Cold start recovery: checking for missed notifications"
|
||||
echo " DNP-REACTIVATION: Marked missed notification: <id>"
|
||||
echo " DNP-REACTIVATION: Cold start recovery complete: missed=1, ..."
|
||||
echo ""
|
||||
|
||||
RECOVERY_RESULT=$(adb logcat -d | grep "Cold start recovery complete" | tail -1)
|
||||
if echo "${RECOVERY_RESULT}" | grep -q "missed=[1-9]"; then
|
||||
print_success "TEST 1 PASSED: Missed notification detected!"
|
||||
elif echo "${RECOVERY_RESULT}" | grep -q "missed=0"; then
|
||||
print_error "TEST 1 FAILED: No missed notifications detected (missed=0)"
|
||||
print_info "This might mean:"
|
||||
echo " - Notification was already delivered"
|
||||
echo " - NotificationContentEntity was not created"
|
||||
echo " - Alarm fired before app was killed"
|
||||
else
|
||||
print_error "TEST 1 INCONCLUSIVE: Could not find recovery result"
|
||||
fi
|
||||
|
||||
wait_for_user
|
||||
|
||||
# ============================================
|
||||
# TEST 2: Future Alarm Verification
|
||||
# ============================================
|
||||
print_header "TEST 2: Future Alarm Verification"
|
||||
echo "Purpose: Verify future alarms are verified/rescheduled if missing."
|
||||
echo ""
|
||||
echo "Note: The test app doesn't have a cancel button, so we'll test"
|
||||
echo " verification of existing alarms instead."
|
||||
echo ""
|
||||
wait_for_user
|
||||
|
||||
print_step "1" "Launch app"
|
||||
launch_app
|
||||
ensure_plugin_configured
|
||||
|
||||
wait_for_ui_action "In the app UI, click 'Test Notification' to schedule another notification.
|
||||
|
||||
This creates a second scheduled notification for testing verification."
|
||||
|
||||
print_step "2" "Verifying alarms are scheduled..."
|
||||
sleep 2
|
||||
check_alarm_status
|
||||
|
||||
ALARM_COUNT=$(adb shell dumpsys alarm | grep -c "timesafari" || echo "0")
|
||||
print_info "Found ${ALARM_COUNT} scheduled alarm(s)"
|
||||
|
||||
if [ "${ALARM_COUNT}" -gt "0" ]; then
|
||||
print_success "Alarms are scheduled in AlarmManager"
|
||||
else
|
||||
print_error "No alarms found in AlarmManager"
|
||||
wait_for_user
|
||||
fi
|
||||
|
||||
print_step "3" "Killing app and relaunching (triggers recovery)..."
|
||||
kill_app
|
||||
clear_logs
|
||||
launch_app
|
||||
|
||||
print_step "4" "Checking recovery logs for verification..."
|
||||
sleep 3
|
||||
check_recovery_logs
|
||||
|
||||
print_info "Expected log output (either):"
|
||||
echo " DNP-REACTIVATION: Verified scheduled alarm: <id> at <time>"
|
||||
echo " OR"
|
||||
echo " DNP-REACTIVATION: Rescheduled missing alarm: <id> at <time>"
|
||||
echo " DNP-REACTIVATION: Cold start recovery complete: ..., verified=1 or rescheduled=1, ..."
|
||||
echo ""
|
||||
|
||||
RECOVERY_RESULT=$(adb logcat -d | grep "Cold start recovery complete" | tail -1)
|
||||
|
||||
# Extract counts from recovery result
|
||||
RESCHEDULED_COUNT=$(echo "${RECOVERY_RESULT}" | grep -oE "rescheduled=[0-9]+" | grep -oE "[0-9]+" || echo "0")
|
||||
VERIFIED_COUNT=$(echo "${RECOVERY_RESULT}" | grep -oE "verified=[0-9]+" | grep -oE "[0-9]+" || echo "0")
|
||||
|
||||
if [ "${RESCHEDULED_COUNT}" -gt "0" ]; then
|
||||
print_success "TEST 2 PASSED: Missing future alarms were detected and rescheduled (rescheduled=${RESCHEDULED_COUNT})!"
|
||||
elif [ "${VERIFIED_COUNT}" -gt "0" ]; then
|
||||
print_success "TEST 2 PASSED: Future alarms verified in AlarmManager (verified=${VERIFIED_COUNT})!"
|
||||
elif [ "${RESCHEDULED_COUNT}" -eq "0" ] && [ "${VERIFIED_COUNT}" -eq "0" ]; then
|
||||
print_info "TEST 2: No verification/rescheduling needed"
|
||||
print_info "This is OK if:"
|
||||
echo " - All alarms were in the past (marked as missed)"
|
||||
echo " - All future alarms were already correctly scheduled"
|
||||
else
|
||||
print_error "TEST 2 INCONCLUSIVE: Could not find recovery result"
|
||||
print_info "Recovery result: ${RECOVERY_RESULT}"
|
||||
fi
|
||||
|
||||
print_step "5" "Verifying alarms are still scheduled in AlarmManager..."
|
||||
check_alarm_status
|
||||
|
||||
wait_for_user
|
||||
|
||||
# ============================================
|
||||
# TEST 3: Recovery Timeout
|
||||
# ============================================
|
||||
print_header "TEST 3: Recovery Timeout"
|
||||
echo "Purpose: Verify recovery times out gracefully."
|
||||
echo ""
|
||||
echo "Note: This test requires creating many schedules (100+)."
|
||||
echo "For now, we'll verify the timeout mechanism exists."
|
||||
echo ""
|
||||
wait_for_user
|
||||
|
||||
print_step "1" "Checking recovery timeout implementation..."
|
||||
if grep -q "RECOVERY_TIMEOUT_SECONDS = 2L" "${PROJECT_ROOT}/android/src/main/java/com/timesafari/dailynotification/ReactivationManager.kt"; then
|
||||
print_success "Timeout is set to 2 seconds"
|
||||
else
|
||||
print_error "Timeout not found in code"
|
||||
fi
|
||||
|
||||
if grep -q "withTimeout" "${PROJECT_ROOT}/android/src/main/java/com/timesafari/dailynotification/ReactivationManager.kt"; then
|
||||
print_success "Timeout protection is implemented"
|
||||
else
|
||||
print_error "Timeout protection not found"
|
||||
fi
|
||||
|
||||
print_info "TEST 3: Timeout mechanism verified in code"
|
||||
print_info "Full test (100+ schedules) can be done manually if needed"
|
||||
|
||||
wait_for_user
|
||||
|
||||
# ============================================
|
||||
# TEST 4: Invalid Data Handling
|
||||
# ============================================
|
||||
print_header "TEST 4: Invalid Data Handling"
|
||||
echo "Purpose: Verify invalid data doesn't crash recovery."
|
||||
echo ""
|
||||
echo "Note: This requires database access. We'll check if the app is debuggable."
|
||||
echo ""
|
||||
wait_for_user
|
||||
|
||||
print_step "1" "Checking if app is debuggable..."
|
||||
if adb shell dumpsys package "${PACKAGE}" | grep -q "debuggable=true"; then
|
||||
print_success "App is debuggable - can access database"
|
||||
|
||||
print_info "Invalid data handling is tested automatically during recovery."
|
||||
print_info "The ReactivationManager code includes checks for:"
|
||||
echo " - Empty notification IDs (skipped with warning)"
|
||||
echo " - Invalid schedule IDs (skipped with warning)"
|
||||
echo " - Database errors (logged, non-fatal)"
|
||||
echo ""
|
||||
print_info "To manually test invalid data:"
|
||||
echo " 1. Use: adb shell run-as ${PACKAGE} sqlite3 databases/daily_notification_plugin.db"
|
||||
echo " 2. Insert invalid notification: INSERT INTO notification_content (id, ...) VALUES ('', ...);"
|
||||
echo " 3. Launch app and check logs for 'Skipping invalid notification'"
|
||||
else
|
||||
print_info "App is not debuggable - cannot access database directly"
|
||||
print_info "TEST 4: Code review confirms invalid data handling exists"
|
||||
print_info " - ReactivationManager.kt checks for empty IDs"
|
||||
print_info " - Errors are logged but don't crash recovery"
|
||||
fi
|
||||
|
||||
wait_for_user
|
||||
|
||||
# ============================================
|
||||
# Summary
|
||||
# ============================================
|
||||
print_header "Testing Complete"
|
||||
|
||||
echo "Test Results Summary:"
|
||||
echo ""
|
||||
echo "TEST 1: Cold Start Missed Detection"
|
||||
echo " - ✅ PASSED if logs show 'missed=1'"
|
||||
echo " - ❌ FAILED if logs show 'missed=0' or no recovery logs"
|
||||
echo ""
|
||||
echo "TEST 2: Future Alarm Verification/Rescheduling"
|
||||
echo " - ✅ PASSED if logs show 'rescheduled=1' OR 'verified=1'"
|
||||
echo " - ℹ️ INFO if both are 0 (no future alarms to check)"
|
||||
echo ""
|
||||
echo "TEST 3: Recovery Timeout"
|
||||
echo " - Timeout mechanism verified in code"
|
||||
echo ""
|
||||
echo "TEST 4: Invalid Data Handling"
|
||||
echo " - Requires database access (debuggable app or root)"
|
||||
echo ""
|
||||
|
||||
print_info "All recovery logs:"
|
||||
echo ""
|
||||
adb logcat -d | grep "DNP-REACTIVATION" | tail -20
|
||||
echo ""
|
||||
|
||||
print_success "Phase 1 testing script complete!"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo " - Review logs above"
|
||||
echo " - Verify all tests passed"
|
||||
echo " - Check database if needed (debuggable app)"
|
||||
echo " - Update Doc B with test results"
|
||||
}
|
||||
|
||||
# Run main function
|
||||
main "$@"
|
||||
|
||||
@@ -1,530 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# ========================================
|
||||
# Phase 2 Testing Script – Force Stop Recovery
|
||||
# ========================================
|
||||
|
||||
# --- Config -------------------------------------------------------------------
|
||||
|
||||
APP_ID="com.timesafari.dailynotification"
|
||||
APK_PATH="./app/build/outputs/apk/debug/app-debug.apk"
|
||||
ADB_BIN="${ADB_BIN:-adb}"
|
||||
|
||||
# Log tags / patterns (matched to actual ReactivationManager logs)
|
||||
REACTIVATION_TAG="DNP-REACTIVATION"
|
||||
SCENARIO_KEY="Detected scenario: "
|
||||
FORCE_STOP_SCENARIO_VALUE="FORCE_STOP"
|
||||
COLD_START_SCENARIO_VALUE="COLD_START"
|
||||
NONE_SCENARIO_VALUE="NONE"
|
||||
BOOT_SCENARIO_VALUE="BOOT"
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Helpers
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
section() {
|
||||
echo
|
||||
echo "========================================"
|
||||
echo "$1"
|
||||
echo "========================================"
|
||||
echo
|
||||
}
|
||||
|
||||
substep() {
|
||||
echo "→ $1"
|
||||
}
|
||||
|
||||
info() {
|
||||
echo -e "ℹ️ $1"
|
||||
}
|
||||
|
||||
ok() {
|
||||
echo -e "✅ $1"
|
||||
}
|
||||
|
||||
warn() {
|
||||
echo -e "⚠️ $1"
|
||||
}
|
||||
|
||||
error() {
|
||||
echo -e "❌ $1"
|
||||
}
|
||||
|
||||
pause() {
|
||||
echo
|
||||
read -rp "Press Enter when ready to continue..."
|
||||
echo
|
||||
}
|
||||
|
||||
ui_prompt() {
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo "👆 UI ACTION REQUIRED"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo -e "$1"
|
||||
echo
|
||||
read -rp "Press Enter after completing the action above..."
|
||||
echo
|
||||
}
|
||||
|
||||
run_cmd() {
|
||||
# Wrapper so output is visible but failures stop the script
|
||||
# Usage: run_cmd "description" cmd...
|
||||
local desc="$1"; shift
|
||||
substep "$desc"
|
||||
echo " $*"
|
||||
if "$@"; then
|
||||
ok "$desc"
|
||||
else
|
||||
error "$desc failed"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
require_adb_device() {
|
||||
section "Pre-Flight Checks"
|
||||
|
||||
if ! $ADB_BIN devices | awk 'NR>1 && $2=="device"{found=1} END{exit !found}'; then
|
||||
error "No emulator/device in 'device' state. Start your emulator first."
|
||||
exit 1
|
||||
fi
|
||||
ok "ADB device connected"
|
||||
|
||||
info "Checking emulator status..."
|
||||
if ! $ADB_BIN shell getprop sys.boot_completed | grep -q "1"; then
|
||||
info "Waiting for emulator to boot..."
|
||||
$ADB_BIN wait-for-device
|
||||
while [ "$($ADB_BIN shell getprop sys.boot_completed)" != "1" ]; do
|
||||
sleep 2
|
||||
done
|
||||
fi
|
||||
ok "Emulator is ready"
|
||||
}
|
||||
|
||||
build_app() {
|
||||
section "Building Test App"
|
||||
|
||||
substep "Step 1: Building debug APK..."
|
||||
if ./gradlew :app:assembleDebug; then
|
||||
ok "Build successful"
|
||||
else
|
||||
error "Build failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ -f "$APK_PATH" ]]; then
|
||||
ok "APK ready: $APK_PATH"
|
||||
else
|
||||
error "APK not found at $APK_PATH"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
install_app() {
|
||||
section "Installing App"
|
||||
|
||||
substep "Step 1: Uninstalling existing app (if present)..."
|
||||
set +e
|
||||
uninstall_output="$($ADB_BIN uninstall "$APP_ID" 2>&1)"
|
||||
uninstall_status=$?
|
||||
set -e
|
||||
|
||||
if [[ $uninstall_status -ne 0 ]]; then
|
||||
if grep -q "DELETE_FAILED_INTERNAL_ERROR" <<<"$uninstall_output"; then
|
||||
info "No existing app to uninstall (continuing)"
|
||||
else
|
||||
warn "Uninstall returned non-zero status: $uninstall_output (continuing anyway)"
|
||||
fi
|
||||
else
|
||||
ok "Previous app uninstall succeeded"
|
||||
fi
|
||||
|
||||
substep "Step 2: Installing new APK..."
|
||||
if $ADB_BIN install -r "$APK_PATH"; then
|
||||
ok "App installed successfully"
|
||||
else
|
||||
error "App installation failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
substep "Step 3: Verifying installation..."
|
||||
if $ADB_BIN shell pm list packages | grep -q "$APP_ID"; then
|
||||
ok "App verified in package list"
|
||||
else
|
||||
error "App not found in package list"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
info "Clearing logcat buffer..."
|
||||
$ADB_BIN logcat -c
|
||||
ok "Logs cleared"
|
||||
}
|
||||
|
||||
launch_app() {
|
||||
info "Launching app..."
|
||||
$ADB_BIN shell am start -n "${APP_ID}/.MainActivity" >/dev/null 2>&1
|
||||
sleep 3 # Give app time to load
|
||||
ok "App launched"
|
||||
}
|
||||
|
||||
clear_logs() {
|
||||
info "Clearing logcat buffer..."
|
||||
$ADB_BIN logcat -c
|
||||
ok "Logs cleared"
|
||||
}
|
||||
|
||||
show_alarms() {
|
||||
info "Checking AlarmManager status..."
|
||||
echo
|
||||
$ADB_BIN shell dumpsys alarm | grep -A3 "$APP_ID" || true
|
||||
echo
|
||||
}
|
||||
|
||||
count_alarms() {
|
||||
# Returns count of alarms for our app
|
||||
$ADB_BIN shell dumpsys alarm | grep -c "$APP_ID" || echo "0"
|
||||
}
|
||||
|
||||
force_stop_app() {
|
||||
info "Force-stopping app..."
|
||||
$ADB_BIN shell am force-stop "$APP_ID"
|
||||
sleep 2
|
||||
ok "Force stop requested"
|
||||
}
|
||||
|
||||
get_recovery_logs() {
|
||||
# Collect recent reactivation logs
|
||||
$ADB_BIN logcat -d | grep "$REACTIVATION_TAG" || true
|
||||
}
|
||||
|
||||
extract_field_from_logs() {
|
||||
# Usage: extract_field_from_logs "<logs>" "<field_name>"
|
||||
local logs="$1"
|
||||
local field="$2"
|
||||
# Looks for patterns like "field=NUMBER" and returns NUMBER (or 0)
|
||||
local value
|
||||
value="$(grep -oE "${field}=[0-9]+" <<<"$logs" | tail -n1 | sed "s/${field}=//" || true)"
|
||||
if [[ -z "$value" ]]; then
|
||||
echo "0"
|
||||
else
|
||||
echo "$value"
|
||||
fi
|
||||
}
|
||||
|
||||
extract_scenario_from_logs() {
|
||||
local logs="$1"
|
||||
local scen
|
||||
# Looks for "Detected scenario: FORCE_STOP" format
|
||||
scen="$(grep -oE "${SCENARIO_KEY}[A-Z_]+" <<<"$logs" | tail -n1 | sed "s/${SCENARIO_KEY}//" || true)"
|
||||
echo "$scen"
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# TEST 1 – Force Stop with Cleared Alarms
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
test1_force_stop_cleared_alarms() {
|
||||
section "TEST 1: Force Stop – Alarms Cleared"
|
||||
|
||||
echo "Purpose: Verify force stop detection and alarm rescheduling when alarms are cleared."
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 1: Launch app & check plugin status"
|
||||
launch_app
|
||||
|
||||
ui_prompt "In the app UI, verify plugin status:\n\n ⚙️ Plugin Settings: ✅ Configured\n 🔌 Native Fetcher: ✅ Configured\n\nIf either shows ❌ or 'Not configured', click 'Configure Plugin', wait until both are ✅, then press Enter."
|
||||
|
||||
ui_prompt "Now schedule at least one future notification (e.g., click 'Test Notification' to schedule for a few minutes in the future)."
|
||||
|
||||
substep "Step 2: Verify alarms are scheduled"
|
||||
show_alarms
|
||||
local before_count
|
||||
before_count="$(count_alarms)"
|
||||
info "Alarm count before force stop: $before_count"
|
||||
|
||||
if [[ "$before_count" -eq 0 ]]; then
|
||||
warn "No alarms found before force stop; TEST 1 may not be meaningful."
|
||||
fi
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 3: Force stop app (should clear alarms on many devices)"
|
||||
force_stop_app
|
||||
|
||||
substep "Step 4: Check alarms after force stop"
|
||||
local after_count
|
||||
after_count="$(count_alarms)"
|
||||
info "Alarm count after force stop: $after_count"
|
||||
show_alarms
|
||||
|
||||
if [[ "$after_count" -gt 0 ]]; then
|
||||
warn "Alarms still present after force stop. This device/OS may not clear alarms on force stop."
|
||||
warn "TEST 1 will continue but may not fully validate FORCE_STOP scenario."
|
||||
fi
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 5: Launch app (triggers recovery) and capture logs"
|
||||
clear_logs
|
||||
launch_app
|
||||
sleep 5 # give recovery a moment to run
|
||||
|
||||
info "Collecting recovery logs..."
|
||||
local logs
|
||||
logs="$(get_recovery_logs)"
|
||||
echo "$logs"
|
||||
|
||||
local missed rescheduled verified errors scenario
|
||||
missed="$(extract_field_from_logs "$logs" "missed")"
|
||||
rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
|
||||
verified="$(extract_field_from_logs "$logs" "verified")"
|
||||
errors="$(extract_field_from_logs "$logs" "errors")"
|
||||
scenario="$(extract_scenario_from_logs "$logs")"
|
||||
|
||||
echo
|
||||
info "Parsed recovery summary:"
|
||||
echo " scenario = ${scenario:-<none>}"
|
||||
echo " missed = ${missed}"
|
||||
echo " rescheduled= ${rescheduled}"
|
||||
echo " verified = ${verified}"
|
||||
echo " errors = ${errors}"
|
||||
echo
|
||||
|
||||
if [[ "$errors" -gt 0 ]]; then
|
||||
error "Recovery reported errors>0 (errors=$errors)"
|
||||
fi
|
||||
|
||||
if [[ "$scenario" == "$FORCE_STOP_SCENARIO_VALUE" && "$rescheduled" -gt 0 ]]; then
|
||||
ok "TEST 1 PASSED: Force stop detected and alarms rescheduled (scenario=$scenario, rescheduled=$rescheduled)."
|
||||
elif [[ "$scenario" == "$FORCE_STOP_SCENARIO_VALUE" && "$rescheduled" -eq 0 ]]; then
|
||||
warn "TEST 1: scenario=FORCE_STOP but rescheduled=0. Check implementation or logs."
|
||||
elif [[ "$after_count" -gt 0 ]]; then
|
||||
info "TEST 1: Device/emulator kept alarms after force stop; FORCE_STOP scenario may not trigger here."
|
||||
if [[ "$rescheduled" -gt 0 ]]; then
|
||||
info "Recovery still worked (rescheduled=$rescheduled), but scenario was ${scenario:-COLD_START} instead of FORCE_STOP"
|
||||
fi
|
||||
else
|
||||
warn "TEST 1: Expected FORCE_STOP scenario not clearly detected. Review logs and scenario detection logic."
|
||||
info "Scenario detected: ${scenario:-<none>}, rescheduled=$rescheduled"
|
||||
fi
|
||||
|
||||
substep "Step 6: Verify alarms are rescheduled in AlarmManager"
|
||||
show_alarms
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# TEST 2 – Force Stop / Process Stop with Intact Alarms
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
test2_force_stop_intact_alarms() {
|
||||
section "TEST 2: Force Stop / Process Stop – Alarms Intact"
|
||||
|
||||
echo "Purpose: Ensure we do NOT run heavy force-stop recovery when alarms are intact."
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 1: Launch app & ensure plugin configured"
|
||||
launch_app
|
||||
|
||||
ui_prompt "In the app UI, verify plugin status:\n\n ⚙️ Plugin Settings: ✅ Configured\n 🔌 Native Fetcher: ✅ Configured\n\nIf needed, click 'Configure Plugin', then press Enter."
|
||||
|
||||
ui_prompt "Click 'Test Notification' to schedule another notification a few minutes in the future."
|
||||
|
||||
substep "Step 2: Verify alarms are scheduled"
|
||||
show_alarms
|
||||
local before
|
||||
before="$(count_alarms)"
|
||||
info "Alarm count before stop: $before"
|
||||
|
||||
if [[ "$before" -eq 0 ]]; then
|
||||
warn "No alarms found; TEST 2 may not be meaningful."
|
||||
fi
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 3: Simulate a 'soft' stop or process kill that does NOT clear alarms"
|
||||
info "Killing app process (non-destructive - may not clear alarms)..."
|
||||
$ADB_BIN shell am kill "$APP_ID" || true
|
||||
sleep 2
|
||||
ok "Kill signal sent (soft stop)"
|
||||
|
||||
substep "Step 4: Verify alarms are still scheduled"
|
||||
local after
|
||||
after="$(count_alarms)"
|
||||
info "Alarm count after soft stop: $after"
|
||||
show_alarms
|
||||
|
||||
if [[ "$after" -eq 0 ]]; then
|
||||
warn "Alarms appear cleared after soft stop; this environment may not distinguish TEST 2 well."
|
||||
fi
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 5: Launch app (triggers recovery) and capture logs"
|
||||
clear_logs
|
||||
launch_app
|
||||
sleep 5
|
||||
|
||||
info "Collecting recovery logs..."
|
||||
local logs
|
||||
logs="$(get_recovery_logs)"
|
||||
echo "$logs"
|
||||
|
||||
local missed rescheduled verified errors scenario
|
||||
missed="$(extract_field_from_logs "$logs" "missed")"
|
||||
rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
|
||||
verified="$(extract_field_from_logs "$logs" "verified")"
|
||||
errors="$(extract_field_from_logs "$logs" "errors")"
|
||||
scenario="$(extract_scenario_from_logs "$logs")"
|
||||
|
||||
echo
|
||||
info "Parsed recovery summary:"
|
||||
echo " scenario = ${scenario:-<none>}"
|
||||
echo " missed = ${missed}"
|
||||
echo " rescheduled= ${rescheduled}"
|
||||
echo " verified = ${verified}"
|
||||
echo " errors = ${errors}"
|
||||
echo
|
||||
|
||||
if [[ "$errors" -gt 0 ]]; then
|
||||
error "Recovery reported errors>0 (errors=$errors)"
|
||||
fi
|
||||
|
||||
if [[ "$scenario" != "$FORCE_STOP_SCENARIO_VALUE" && "$rescheduled" -eq 0 ]]; then
|
||||
ok "TEST 2 PASSED: No heavy force-stop recovery when alarms intact (scenario=$scenario, rescheduled=$rescheduled)."
|
||||
elif [[ "$scenario" == "$FORCE_STOP_SCENARIO_VALUE" ]]; then
|
||||
warn "TEST 2: scenario=FORCE_STOP detected but alarms were intact. Check scenario detection logic."
|
||||
else
|
||||
info "TEST 2: Some rescheduling occurred (rescheduled=$rescheduled). This might be OK if alarms were actually missing."
|
||||
fi
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# TEST 3 – First Launch / Empty DB Safeguard
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
test3_first_launch_no_schedules() {
|
||||
section "TEST 3: First Launch / No Schedules Safeguard"
|
||||
|
||||
echo "Purpose: Ensure force-stop recovery is NOT triggered when DB is empty or plugin isn't configured."
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 1: Uninstall app to clear DB/state"
|
||||
set +e
|
||||
$ADB_BIN uninstall "$APP_ID" >/dev/null 2>&1
|
||||
set -e
|
||||
ok "App uninstalled (state cleared)"
|
||||
|
||||
substep "Step 2: Reinstall app"
|
||||
if $ADB_BIN install -r "$APK_PATH"; then
|
||||
ok "App installed"
|
||||
else
|
||||
error "Reinstall failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
info "Clearing logcat..."
|
||||
$ADB_BIN logcat -c
|
||||
ok "Logs cleared"
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 3: Launch app WITHOUT scheduling anything"
|
||||
launch_app
|
||||
sleep 5
|
||||
|
||||
info "Collecting recovery logs..."
|
||||
local logs
|
||||
logs="$($ADB_BIN logcat -d | grep "$REACTIVATION_TAG" || true)"
|
||||
echo "$logs"
|
||||
|
||||
local scenario rescheduled missed
|
||||
scenario="$(extract_scenario_from_logs "$logs")"
|
||||
rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
|
||||
missed="$(extract_field_from_logs "$logs" "missed")"
|
||||
|
||||
echo
|
||||
info "Parsed recovery summary:"
|
||||
echo " scenario = ${scenario:-<none>}"
|
||||
echo " rescheduled= ${rescheduled}"
|
||||
echo " missed = ${missed}"
|
||||
echo
|
||||
|
||||
# Check for explicit "No schedules" or "skipping recovery" messages
|
||||
if echo "$logs" | grep -qiE "No schedules|skipping recovery|first launch"; then
|
||||
ok "TEST 3 PASSED: No recovery logs or explicit skip message when there are no schedules (safe behavior)."
|
||||
return
|
||||
fi
|
||||
|
||||
if [[ -z "$logs" ]]; then
|
||||
ok "TEST 3 PASSED: No recovery logs when there are no schedules (safe behavior)."
|
||||
return
|
||||
fi
|
||||
|
||||
# If you explicitly log a NONE scenario, check for that:
|
||||
if [[ "$scenario" == "$NONE_SCENARIO_VALUE" && "$rescheduled" -eq 0 ]]; then
|
||||
ok "TEST 3 PASSED: NONE scenario detected with no rescheduling."
|
||||
elif [[ "$scenario" == "$FORCE_STOP_SCENARIO_VALUE" ]]; then
|
||||
error "TEST 3 FAILED: FORCE_STOP scenario detected on first launch / empty DB. This should not happen."
|
||||
elif [[ "$rescheduled" -gt 0 ]]; then
|
||||
warn "TEST 3: rescheduled>0 on first launch / empty DB. Check that force-stop recovery isn't misfiring."
|
||||
else
|
||||
info "TEST 3: Logs present but no rescheduling; review scenario handling to ensure it's explicit about NONE / FIRST_LAUNCH."
|
||||
fi
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Main
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
main() {
|
||||
echo
|
||||
echo "========================================"
|
||||
echo "Phase 2 Testing Script – Force Stop Recovery"
|
||||
echo "========================================"
|
||||
echo
|
||||
echo "This script will guide you through all Phase 2 tests."
|
||||
echo "You'll be prompted when UI interaction is needed."
|
||||
echo
|
||||
|
||||
pause
|
||||
|
||||
require_adb_device
|
||||
build_app
|
||||
install_app
|
||||
|
||||
test1_force_stop_cleared_alarms
|
||||
pause
|
||||
|
||||
test2_force_stop_intact_alarms
|
||||
pause
|
||||
|
||||
test3_first_launch_no_schedules
|
||||
|
||||
section "Testing Complete"
|
||||
|
||||
echo "Test Results Summary (see logs above for details):"
|
||||
echo
|
||||
echo "TEST 1: Force Stop – Alarms Cleared"
|
||||
echo " - Check logs for scenario=$FORCE_STOP_SCENARIO_VALUE and rescheduled>0"
|
||||
echo
|
||||
echo "TEST 2: Force Stop / Process Stop – Alarms Intact"
|
||||
echo " - Check that heavy FORCE_STOP recovery did NOT run when alarms are still present"
|
||||
echo
|
||||
echo "TEST 3: First Launch / No Schedules"
|
||||
echo " - Check that no force-stop recovery runs, or that NONE scenario is logged with rescheduled=0"
|
||||
echo
|
||||
|
||||
ok "Phase 2 testing script complete!"
|
||||
echo
|
||||
echo "Next steps:"
|
||||
echo " - Review logs above"
|
||||
echo " - Capture snippets into PHASE2-EMULATOR-TESTING.md"
|
||||
echo " - Update PHASE2-VERIFICATION.md and unified directive status matrix"
|
||||
echo
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,578 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# ========================================
|
||||
# Phase 3 Testing Script – Boot Recovery
|
||||
# ========================================
|
||||
|
||||
# --- Config -------------------------------------------------------------------
|
||||
|
||||
APP_ID="com.timesafari.dailynotification"
|
||||
APK_PATH="./app/build/outputs/apk/debug/app-debug.apk"
|
||||
ADB_BIN="${ADB_BIN:-adb}"
|
||||
|
||||
# Log tags / patterns (matched to actual ReactivationManager logs)
|
||||
REACTIVATION_TAG="DNP-REACTIVATION"
|
||||
SCENARIO_KEY="Detected scenario: "
|
||||
BOOT_SCENARIO_VALUE="BOOT"
|
||||
NONE_SCENARIO_VALUE="NONE"
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Helpers
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
section() {
|
||||
echo
|
||||
echo "========================================"
|
||||
echo "$1"
|
||||
echo "========================================"
|
||||
echo
|
||||
}
|
||||
|
||||
substep() {
|
||||
echo "→ $1"
|
||||
}
|
||||
|
||||
info() {
|
||||
echo -e "ℹ️ $1"
|
||||
}
|
||||
|
||||
ok() {
|
||||
echo -e "✅ $1"
|
||||
}
|
||||
|
||||
warn() {
|
||||
echo -e "⚠️ $1"
|
||||
}
|
||||
|
||||
error() {
|
||||
echo -e "❌ $1"
|
||||
}
|
||||
|
||||
pause() {
|
||||
echo
|
||||
read -rp "Press Enter when ready to continue..."
|
||||
echo
|
||||
}
|
||||
|
||||
ui_prompt() {
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo "👆 UI ACTION REQUIRED"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo -e "$1"
|
||||
echo
|
||||
read -rp "Press Enter after completing the action above..."
|
||||
echo
|
||||
}
|
||||
|
||||
require_adb_device() {
|
||||
section "Pre-Flight Checks"
|
||||
|
||||
if ! $ADB_BIN devices | awk 'NR>1 && $2=="device"{found=1} END{exit !found}'; then
|
||||
error "No emulator/device in 'device' state. Start your emulator first."
|
||||
exit 1
|
||||
fi
|
||||
ok "ADB device connected"
|
||||
|
||||
info "Checking emulator status..."
|
||||
if ! $ADB_BIN shell getprop sys.boot_completed | grep -q "1"; then
|
||||
info "Waiting for emulator to boot..."
|
||||
$ADB_BIN wait-for-device
|
||||
while [ "$($ADB_BIN shell getprop sys.boot_completed)" != "1" ]; do
|
||||
sleep 2
|
||||
done
|
||||
fi
|
||||
ok "Emulator is ready"
|
||||
}
|
||||
|
||||
build_app() {
|
||||
section "Building Test App"
|
||||
|
||||
substep "Step 1: Building debug APK..."
|
||||
if ./gradlew :app:assembleDebug; then
|
||||
ok "Build successful"
|
||||
else
|
||||
error "Build failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ -f "$APK_PATH" ]]; then
|
||||
ok "APK ready: $APK_PATH"
|
||||
else
|
||||
error "APK not found at $APK_PATH"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
install_app() {
|
||||
section "Installing App"
|
||||
|
||||
substep "Step 1: Uninstalling existing app (if present)..."
|
||||
set +e
|
||||
uninstall_output="$($ADB_BIN uninstall "$APP_ID" 2>&1)"
|
||||
uninstall_status=$?
|
||||
set -e
|
||||
|
||||
if [[ $uninstall_status -ne 0 ]]; then
|
||||
if grep -q "DELETE_FAILED_INTERNAL_ERROR" <<<"$uninstall_output"; then
|
||||
info "No existing app to uninstall (continuing)"
|
||||
else
|
||||
warn "Uninstall returned non-zero status: $uninstall_output (continuing anyway)"
|
||||
fi
|
||||
else
|
||||
ok "Previous app uninstall succeeded"
|
||||
fi
|
||||
|
||||
substep "Step 2: Installing new APK..."
|
||||
if $ADB_BIN install -r "$APK_PATH"; then
|
||||
ok "App installed successfully"
|
||||
else
|
||||
error "App installation failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
substep "Step 3: Verifying installation..."
|
||||
if $ADB_BIN shell pm list packages | grep -q "$APP_ID"; then
|
||||
ok "App verified in package list"
|
||||
else
|
||||
error "App not found in package list"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
info "Clearing logcat buffer..."
|
||||
$ADB_BIN logcat -c
|
||||
ok "Logs cleared"
|
||||
}
|
||||
|
||||
launch_app() {
|
||||
info "Launching app..."
|
||||
$ADB_BIN shell am start -n "${APP_ID}/.MainActivity" >/dev/null 2>&1
|
||||
sleep 3 # Give app time to load
|
||||
ok "App launched"
|
||||
}
|
||||
|
||||
clear_logs() {
|
||||
info "Clearing logcat buffer..."
|
||||
$ADB_BIN logcat -c
|
||||
ok "Logs cleared"
|
||||
}
|
||||
|
||||
show_alarms() {
|
||||
info "Checking AlarmManager status..."
|
||||
echo
|
||||
$ADB_BIN shell dumpsys alarm | grep -A3 "$APP_ID" || true
|
||||
echo
|
||||
}
|
||||
|
||||
count_alarms() {
|
||||
# Returns count of alarms for our app
|
||||
$ADB_BIN shell dumpsys alarm | grep -c "$APP_ID" || echo "0"
|
||||
}
|
||||
|
||||
reboot_emulator() {
|
||||
info "Rebooting emulator..."
|
||||
$ADB_BIN reboot
|
||||
ok "Reboot initiated"
|
||||
|
||||
info "Waiting for emulator to come back online..."
|
||||
$ADB_BIN wait-for-device
|
||||
while [ "$($ADB_BIN shell getprop sys.boot_completed)" != "1" ]; do
|
||||
sleep 2
|
||||
done
|
||||
ok "Emulator boot completed"
|
||||
}
|
||||
|
||||
get_recovery_logs() {
|
||||
# Collect recent reactivation logs
|
||||
$ADB_BIN logcat -d | grep "$REACTIVATION_TAG" || true
|
||||
}
|
||||
|
||||
extract_field_from_logs() {
|
||||
# Usage: extract_field_from_logs "<logs>" "<field_name>"
|
||||
local logs="$1"
|
||||
local field="$2"
|
||||
# Looks for patterns like "field=NUMBER" and returns NUMBER (or 0)
|
||||
local value
|
||||
value="$(grep -oE "${field}=[0-9]+" <<<"$logs" | tail -n1 | sed "s/${field}=//" || true)"
|
||||
if [[ -z "$value" ]]; then
|
||||
echo "0"
|
||||
else
|
||||
echo "$value"
|
||||
fi
|
||||
}
|
||||
|
||||
extract_scenario_from_logs() {
|
||||
local logs="$1"
|
||||
local scen
|
||||
# Looks for "Detected scenario: BOOT" or "Starting boot recovery" format
|
||||
if echo "$logs" | grep -qi "Starting boot recovery\|boot recovery"; then
|
||||
echo "$BOOT_SCENARIO_VALUE"
|
||||
else
|
||||
scen="$(grep -oE "${SCENARIO_KEY}[A-Z_]+" <<<"$logs" | tail -n1 | sed "s/${SCENARIO_KEY}//" || true)"
|
||||
echo "$scen"
|
||||
fi
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# TEST 1 – Boot with Future Alarms
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
test1_boot_future_alarms() {
|
||||
section "TEST 1: Boot with Future Alarms"
|
||||
|
||||
echo "Purpose: Verify alarms are recreated on boot when schedules have future run times."
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 1: Launch app & check plugin status"
|
||||
launch_app
|
||||
|
||||
ui_prompt "In the app UI, verify plugin status:\n\n ⚙️ Plugin Settings: ✅ Configured\n 🔌 Native Fetcher: ✅ Configured\n\nIf either shows ❌ or 'Not configured', click 'Configure Plugin', wait until both are ✅, then press Enter."
|
||||
|
||||
ui_prompt "Now schedule at least one future notification (e.g., click 'Test Notification' to schedule for a few minutes in the future)."
|
||||
|
||||
substep "Step 2: Verify alarms are scheduled"
|
||||
show_alarms
|
||||
local before_count
|
||||
before_count="$(count_alarms)"
|
||||
info "Alarm count before reboot: $before_count"
|
||||
|
||||
if [[ "$before_count" -eq 0 ]]; then
|
||||
warn "No alarms found before reboot; TEST 1 may not be meaningful."
|
||||
fi
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 3: Reboot emulator"
|
||||
warn "The emulator will reboot now. This will take 30-60 seconds."
|
||||
pause
|
||||
reboot_emulator
|
||||
|
||||
substep "Step 4: Collect boot recovery logs"
|
||||
info "Collecting recovery logs from boot..."
|
||||
sleep 2 # Give recovery a moment to complete
|
||||
local logs
|
||||
logs="$(get_recovery_logs)"
|
||||
echo "$logs"
|
||||
|
||||
local missed rescheduled verified errors scenario
|
||||
missed="$(extract_field_from_logs "$logs" "missed")"
|
||||
rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
|
||||
verified="$(extract_field_from_logs "$logs" "verified")"
|
||||
errors="$(extract_field_from_logs "$logs" "errors")"
|
||||
scenario="$(extract_scenario_from_logs "$logs")"
|
||||
|
||||
echo
|
||||
info "Parsed recovery summary:"
|
||||
echo " scenario = ${scenario:-<none>}"
|
||||
echo " missed = ${missed}"
|
||||
echo " rescheduled= ${rescheduled}"
|
||||
echo " verified = ${verified}"
|
||||
echo " errors = ${errors}"
|
||||
echo
|
||||
|
||||
if [[ "$errors" -gt 0 ]]; then
|
||||
error "Recovery reported errors>0 (errors=$errors)"
|
||||
fi
|
||||
|
||||
substep "Step 5: Verify alarms were recreated"
|
||||
show_alarms
|
||||
local after_count
|
||||
after_count="$(count_alarms)"
|
||||
info "Alarm count after boot: $after_count"
|
||||
|
||||
if [[ "$scenario" == "$BOOT_SCENARIO_VALUE" && "$rescheduled" -gt 0 ]]; then
|
||||
ok "TEST 1 PASSED: Boot recovery detected and alarms rescheduled (scenario=$scenario, rescheduled=$rescheduled)."
|
||||
elif echo "$logs" | grep -qi "Starting boot recovery\|boot recovery"; then
|
||||
if [[ "$rescheduled" -gt 0 ]]; then
|
||||
ok "TEST 1 PASSED: Boot recovery ran and alarms rescheduled (rescheduled=$rescheduled)."
|
||||
else
|
||||
warn "TEST 1: Boot recovery ran but rescheduled=0. Check implementation or logs."
|
||||
fi
|
||||
else
|
||||
warn "TEST 1: Boot recovery not clearly detected. Review logs and boot receiver implementation."
|
||||
info "Scenario detected: ${scenario:-<none>}, rescheduled=$rescheduled"
|
||||
fi
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# TEST 2 – Boot with Past Alarms
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
test2_boot_past_alarms() {
|
||||
section "TEST 2: Boot with Past Alarms"
|
||||
|
||||
echo "Purpose: Verify missed alarms are detected and next occurrence is scheduled on boot."
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 1: Launch app & ensure plugin configured"
|
||||
launch_app
|
||||
|
||||
ui_prompt "In the app UI, verify plugin status:\n\n ⚙️ Plugin Settings: ✅ Configured\n 🔌 Native Fetcher: ✅ Configured\n\nIf needed, click 'Configure Plugin', then press Enter."
|
||||
|
||||
ui_prompt "Click 'Test Notification' to schedule a notification for 2 minutes in the future.\n\nAfter scheduling, we'll wait for the alarm time to pass, then reboot."
|
||||
|
||||
substep "Step 2: Wait for alarm time to pass"
|
||||
info "Waiting 3 minutes for scheduled alarm time to pass..."
|
||||
warn "You can manually advance system time if needed (requires root/emulator)"
|
||||
sleep 180 # Wait 3 minutes
|
||||
|
||||
substep "Step 3: Verify alarm time has passed"
|
||||
info "Alarm time should now be in the past"
|
||||
show_alarms
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 4: Reboot emulator"
|
||||
warn "The emulator will reboot now. This will take 30-60 seconds."
|
||||
pause
|
||||
reboot_emulator
|
||||
|
||||
substep "Step 5: Collect boot recovery logs"
|
||||
info "Collecting recovery logs from boot..."
|
||||
sleep 2
|
||||
local logs
|
||||
logs="$(get_recovery_logs)"
|
||||
echo "$logs"
|
||||
|
||||
local missed rescheduled verified errors scenario
|
||||
missed="$(extract_field_from_logs "$logs" "missed")"
|
||||
rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
|
||||
verified="$(extract_field_from_logs "$logs" "verified")"
|
||||
errors="$(extract_field_from_logs "$logs" "errors")"
|
||||
scenario="$(extract_scenario_from_logs "$logs")"
|
||||
|
||||
echo
|
||||
info "Parsed recovery summary:"
|
||||
echo " scenario = ${scenario:-<none>}"
|
||||
echo " missed = ${missed}"
|
||||
echo " rescheduled= ${rescheduled}"
|
||||
echo " verified = ${verified}"
|
||||
echo " errors = ${errors}"
|
||||
echo
|
||||
|
||||
if [[ "$errors" -gt 0 ]]; then
|
||||
error "Recovery reported errors>0 (errors=$errors)"
|
||||
fi
|
||||
|
||||
if [[ "$missed" -ge 1 && "$rescheduled" -ge 1 ]]; then
|
||||
ok "TEST 2 PASSED: Past alarms detected and next occurrence scheduled (missed=$missed, rescheduled=$rescheduled)."
|
||||
elif [[ "$missed" -ge 1 ]]; then
|
||||
warn "TEST 2: Past alarms detected (missed=$missed) but rescheduled=$rescheduled. Check reschedule logic."
|
||||
else
|
||||
warn "TEST 2: No missed alarms detected. Verify alarm time actually passed before reboot."
|
||||
fi
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# TEST 3 – Boot with No Schedules
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
test3_boot_no_schedules() {
|
||||
section "TEST 3: Boot with No Schedules"
|
||||
|
||||
echo "Purpose: Verify boot recovery handles empty database gracefully."
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 1: Uninstall app to clear DB/state"
|
||||
set +e
|
||||
$ADB_BIN uninstall "$APP_ID" >/dev/null 2>&1
|
||||
set -e
|
||||
ok "App uninstalled (state cleared)"
|
||||
|
||||
substep "Step 2: Reinstall app"
|
||||
if $ADB_BIN install -r "$APK_PATH"; then
|
||||
ok "App installed"
|
||||
else
|
||||
error "Reinstall failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
info "Clearing logcat..."
|
||||
$ADB_BIN logcat -c
|
||||
ok "Logs cleared"
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 3: Reboot emulator WITHOUT scheduling anything"
|
||||
warn "Do NOT schedule any notifications. The app should have no schedules in the database."
|
||||
warn "The emulator will reboot now. This will take 30-60 seconds."
|
||||
pause
|
||||
reboot_emulator
|
||||
|
||||
substep "Step 4: Collect boot recovery logs"
|
||||
info "Collecting recovery logs from boot..."
|
||||
sleep 2
|
||||
local logs
|
||||
logs="$($ADB_BIN logcat -d | grep "$REACTIVATION_TAG" || true)"
|
||||
echo "$logs"
|
||||
|
||||
local scenario rescheduled missed
|
||||
scenario="$(extract_scenario_from_logs "$logs")"
|
||||
rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
|
||||
missed="$(extract_field_from_logs "$logs" "missed")"
|
||||
|
||||
echo
|
||||
info "Parsed recovery summary:"
|
||||
echo " scenario = ${scenario:-<none>}"
|
||||
echo " rescheduled= ${rescheduled}"
|
||||
echo " missed = ${missed}"
|
||||
echo
|
||||
|
||||
if [[ -z "$logs" ]]; then
|
||||
ok "TEST 3 PASSED: No recovery logs when there are no schedules (safe behavior)."
|
||||
return
|
||||
fi
|
||||
|
||||
if echo "$logs" | grep -qiE "No schedules found|No schedules present"; then
|
||||
ok "TEST 3 PASSED: Explicit 'No schedules found' message logged with no rescheduling."
|
||||
elif [[ "$scenario" == "$NONE_SCENARIO_VALUE" && "$rescheduled" -eq 0 ]]; then
|
||||
ok "TEST 3 PASSED: NONE scenario detected with no rescheduling."
|
||||
elif [[ "$rescheduled" -gt 0 ]]; then
|
||||
warn "TEST 3: rescheduled>0 on first launch / empty DB. Check that boot recovery isn't misfiring."
|
||||
else
|
||||
info "TEST 3: Logs present but no rescheduling; review scenario handling to ensure it's explicit about NONE / NO_SCHEDULES."
|
||||
fi
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# TEST 4 – Silent Boot Recovery (App Never Opened)
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
test4_silent_boot_recovery() {
|
||||
section "TEST 4: Silent Boot Recovery (App Never Opened)"
|
||||
|
||||
echo "Purpose: Verify boot recovery occurs even when the app is never opened after reboot."
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 1: Launch app & ensure plugin configured"
|
||||
launch_app
|
||||
|
||||
ui_prompt "In the app UI, verify plugin status:\n\n ⚙️ Plugin Settings: ✅ Configured\n 🔌 Native Fetcher: ✅ Configured\n\nIf needed, click 'Configure Plugin', then press Enter."
|
||||
|
||||
ui_prompt "Click 'Test Notification' to schedule a notification for a few minutes in the future."
|
||||
|
||||
substep "Step 2: Verify alarms are scheduled"
|
||||
show_alarms
|
||||
local before_count
|
||||
before_count="$(count_alarms)"
|
||||
info "Alarm count before reboot: $before_count"
|
||||
|
||||
if [[ "$before_count" -eq 0 ]]; then
|
||||
warn "No alarms found; TEST 4 may not be meaningful."
|
||||
fi
|
||||
|
||||
pause
|
||||
|
||||
substep "Step 3: Reboot emulator (DO NOT open app after reboot)"
|
||||
warn "IMPORTANT: After reboot, DO NOT open the app. Boot recovery should run silently."
|
||||
warn "The emulator will reboot now. This will take 30-60 seconds."
|
||||
pause
|
||||
reboot_emulator
|
||||
|
||||
substep "Step 4: Collect boot recovery logs (without opening app)"
|
||||
info "Collecting recovery logs from boot (app was NOT opened)..."
|
||||
sleep 2
|
||||
local logs
|
||||
logs="$(get_recovery_logs)"
|
||||
echo "$logs"
|
||||
|
||||
local missed rescheduled verified errors scenario
|
||||
missed="$(extract_field_from_logs "$logs" "missed")"
|
||||
rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
|
||||
verified="$(extract_field_from_logs "$logs" "verified")"
|
||||
errors="$(extract_field_from_logs "$logs" "errors")"
|
||||
scenario="$(extract_scenario_from_logs "$logs")"
|
||||
|
||||
echo
|
||||
info "Parsed recovery summary:"
|
||||
echo " scenario = ${scenario:-<none>}"
|
||||
echo " missed = ${missed}"
|
||||
echo " rescheduled= ${rescheduled}"
|
||||
echo " verified = ${verified}"
|
||||
echo " errors = ${errors}"
|
||||
echo
|
||||
|
||||
substep "Step 5: Verify alarms were recreated (without opening app)"
|
||||
show_alarms
|
||||
local after_count
|
||||
after_count="$(count_alarms)"
|
||||
info "Alarm count after boot (app never opened): $after_count"
|
||||
|
||||
if [[ "$after_count" -gt 0 && "$rescheduled" -gt 0 ]]; then
|
||||
ok "TEST 4 PASSED: Boot recovery occurred silently and alarms were recreated (rescheduled=$rescheduled) without app launch."
|
||||
elif [[ "$rescheduled" -gt 0 ]]; then
|
||||
ok "TEST 4 PASSED: Boot recovery occurred silently (rescheduled=$rescheduled), but alarm count check unclear."
|
||||
elif echo "$logs" | grep -qi "Starting boot recovery\|boot recovery"; then
|
||||
warn "TEST 4: Boot recovery ran but alarms may not have been recreated. Check logs and implementation."
|
||||
else
|
||||
warn "TEST 4: Boot recovery not detected. Verify boot receiver is registered and has BOOT_COMPLETED permission."
|
||||
fi
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Main
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
main() {
|
||||
echo
|
||||
echo "========================================"
|
||||
echo "Phase 3 Testing Script – Boot Recovery"
|
||||
echo "========================================"
|
||||
echo
|
||||
echo "This script will guide you through all Phase 3 tests."
|
||||
echo "You'll be prompted when UI interaction is needed."
|
||||
echo
|
||||
echo "⚠️ WARNING: This script will reboot the emulator multiple times."
|
||||
echo " Each reboot takes 30-60 seconds."
|
||||
echo
|
||||
|
||||
pause
|
||||
|
||||
require_adb_device
|
||||
build_app
|
||||
install_app
|
||||
|
||||
test1_boot_future_alarms
|
||||
pause
|
||||
|
||||
test2_boot_past_alarms
|
||||
pause
|
||||
|
||||
test3_boot_no_schedules
|
||||
pause
|
||||
|
||||
test4_silent_boot_recovery
|
||||
|
||||
section "Testing Complete"
|
||||
|
||||
echo "Test Results Summary (see logs above for details):"
|
||||
echo
|
||||
echo "TEST 1: Boot with Future Alarms"
|
||||
echo " - Check logs for scenario=$BOOT_SCENARIO_VALUE and rescheduled>0"
|
||||
echo
|
||||
echo "TEST 2: Boot with Past Alarms"
|
||||
echo " - Check that missed>=1 and rescheduled>=1"
|
||||
echo
|
||||
echo "TEST 3: Boot with No Schedules"
|
||||
echo " - Check that no recovery runs, or NONE scenario is logged with rescheduled=0"
|
||||
echo
|
||||
echo "TEST 4: Silent Boot Recovery"
|
||||
echo " - Check that boot recovery occurred and alarms were recreated without app launch"
|
||||
echo
|
||||
|
||||
ok "Phase 3 testing script complete!"
|
||||
echo
|
||||
echo "Next steps:"
|
||||
echo " - Review logs above"
|
||||
echo " - Capture snippets into PHASE3-EMULATOR-TESTING.md"
|
||||
echo " - Update PHASE3-VERIFICATION.md and unified directive status matrix"
|
||||
echo
|
||||
}
|
||||
|
||||
main "$@"
|
||||
|
||||
@@ -31,20 +31,57 @@ npm install
|
||||
|
||||
**Note**: The `postinstall` script automatically fixes Capacitor configuration files after installation.
|
||||
|
||||
### Capacitor Sync (Android)
|
||||
## Building for Android and iOS
|
||||
|
||||
### Quick Build (Recommended)
|
||||
|
||||
Use the unified build script for both platforms:
|
||||
|
||||
```bash
|
||||
# Build and run both platforms on emulator/simulator
|
||||
./scripts/build.sh --run
|
||||
|
||||
# Build both platforms (no run)
|
||||
./scripts/build.sh
|
||||
|
||||
# Build Android only
|
||||
./scripts/build.sh --android
|
||||
|
||||
# Build iOS only
|
||||
./scripts/build.sh --ios
|
||||
|
||||
# Build and run Android on emulator
|
||||
./scripts/build.sh --run-android
|
||||
|
||||
# Build and run iOS on simulator
|
||||
./scripts/build.sh --run-ios
|
||||
```
|
||||
|
||||
**See**: `docs/BUILD_QUICK_REFERENCE.md` for detailed build instructions.
|
||||
|
||||
### Manual Build Steps
|
||||
|
||||
#### Capacitor Sync
|
||||
|
||||
**Important**: Use the wrapper script instead of `npx cap sync` directly to automatically fix plugin paths:
|
||||
|
||||
```sh
|
||||
# Sync both platforms
|
||||
npm run cap:sync
|
||||
|
||||
# Sync Android only
|
||||
npm run cap:sync:android
|
||||
|
||||
# Sync iOS only
|
||||
npm run cap:sync:ios
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Run `npx cap sync android`
|
||||
1. Run `npx cap sync` (or platform-specific sync)
|
||||
2. Automatically fix `capacitor.settings.gradle` (corrects plugin path from `android/` to `android/plugin/`)
|
||||
3. Ensure `capacitor.plugins.json` has the correct plugin registration
|
||||
|
||||
If you run `npx cap sync android` directly, you can manually fix afterward:
|
||||
If you run `npx cap sync` directly, you can manually fix afterward:
|
||||
```sh
|
||||
node scripts/fix-capacitor-plugins.js
|
||||
```
|
||||
|
||||
@@ -1,48 +1,195 @@
|
||||
# Build Process Quick Reference
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: October 17, 2025
|
||||
**Date**: October 17, 2025
|
||||
**Last Updated**: November 19, 2025
|
||||
|
||||
## ⚡ Quick Start
|
||||
|
||||
**Easiest way to build and run:**
|
||||
|
||||
```bash
|
||||
# Build and run both platforms
|
||||
./scripts/build.sh --run
|
||||
|
||||
# Or build only
|
||||
./scripts/build.sh
|
||||
```
|
||||
|
||||
This script handles everything automatically! See [Unified Build Script](#-unified-build-script-recommended) section for all options.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Critical Build Steps
|
||||
|
||||
### Prerequisites
|
||||
|
||||
**Required for All Platforms:**
|
||||
- Node.js 20.19.0+ or 22.12.0+
|
||||
- npm (comes with Node.js)
|
||||
- Plugin must be built (`npm run build` in plugin root directory)
|
||||
- The build script will automatically build the plugin if `dist/` doesn't exist
|
||||
|
||||
**For Android:**
|
||||
- Java JDK 22.12 or later
|
||||
- Android SDK (with `adb` in PATH)
|
||||
- Gradle (comes with Android project)
|
||||
|
||||
**For iOS:**
|
||||
- macOS with Xcode (xcodebuild must be in PATH)
|
||||
- CocoaPods (`pod --version` to check)
|
||||
- Can be installed via rbenv (script handles this automatically)
|
||||
- iOS deployment target: iOS 13.0+
|
||||
|
||||
**Plugin Requirements:**
|
||||
- Plugin podspec must exist at: `node_modules/@timesafari/daily-notification-plugin/ios/DailyNotificationPlugin.podspec`
|
||||
- Plugin must be installed: `npm install` (uses `file:../../` reference)
|
||||
- Plugin must be built: `npm run build` in plugin root (creates `dist/` directory)
|
||||
|
||||
### Initial Setup (One-Time)
|
||||
|
||||
```bash
|
||||
# 1. Build web assets
|
||||
# 1. Install dependencies (includes @capacitor/ios)
|
||||
npm install
|
||||
|
||||
# 2. Add iOS platform (if not already added)
|
||||
npx cap add ios
|
||||
|
||||
# 3. Install iOS dependencies
|
||||
cd ios/App
|
||||
pod install
|
||||
cd ../..
|
||||
```
|
||||
|
||||
### Build for Both Platforms
|
||||
|
||||
```bash
|
||||
# 1. Build web assets (required for both platforms)
|
||||
npm run build
|
||||
|
||||
# 2. Sync with native projects (automatically fixes plugin paths)
|
||||
# 2. Sync with native projects (syncs both Android and iOS)
|
||||
npm run cap:sync
|
||||
|
||||
# 3. Build and deploy Android
|
||||
# OR sync platforms individually:
|
||||
# npm run cap:sync:android # Android only
|
||||
# npm run cap:sync:ios # iOS only
|
||||
```
|
||||
|
||||
### Android Build
|
||||
|
||||
```bash
|
||||
# Build Android APK
|
||||
cd android
|
||||
./gradlew :app:assembleDebug
|
||||
|
||||
# Install on device/emulator
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
|
||||
# Launch app
|
||||
adb shell am start -n com.timesafari.dailynotification.test/.MainActivity
|
||||
```
|
||||
|
||||
### iOS Build
|
||||
|
||||
```bash
|
||||
# Open in Xcode
|
||||
cd ios/App
|
||||
open App.xcworkspace
|
||||
|
||||
# Or build from command line
|
||||
xcodebuild -workspace App.xcworkspace \
|
||||
-scheme App \
|
||||
-configuration Debug \
|
||||
-sdk iphonesimulator \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 15' \
|
||||
build
|
||||
|
||||
# Or use Capacitor CLI
|
||||
npx cap run ios
|
||||
```
|
||||
|
||||
## ⚠️ Why `npm run cap:sync` is Important
|
||||
|
||||
**Problem**: `npx cap sync` overwrites `capacitor.plugins.json` and `capacitor.settings.gradle` with incorrect paths.
|
||||
|
||||
**Solution**: The `cap:sync` script automatically:
|
||||
1. Runs `npx cap sync android`
|
||||
1. Runs `npx cap sync` (syncs both Android and iOS)
|
||||
2. Fixes `capacitor.settings.gradle` (corrects plugin path from `android/` to `android/plugin/`)
|
||||
3. Restores the DailyNotification plugin entry in `capacitor.plugins.json`
|
||||
|
||||
**Platform-specific sync:**
|
||||
- `npm run cap:sync:android` - Syncs Android only (includes fix script)
|
||||
- `npm run cap:sync:ios` - Syncs iOS only (no fix needed for iOS)
|
||||
|
||||
**Without the fix**: Plugin detection fails, build errors occur, "simplified dialog" appears.
|
||||
|
||||
## 🔍 Verification Checklist
|
||||
|
||||
After build, verify:
|
||||
### Android Verification
|
||||
|
||||
- [ ] `capacitor.plugins.json` contains DailyNotification entry
|
||||
After Android build, verify:
|
||||
|
||||
- [ ] `android/app/src/main/assets/capacitor.plugins.json` contains DailyNotification entry
|
||||
- [ ] System Status shows "Plugin: Available" (green)
|
||||
- [ ] Plugin Diagnostics shows all 4 plugins
|
||||
- [ ] Click events work on ActionCard components
|
||||
- [ ] No "simplified dialog" appears
|
||||
|
||||
## 🛠️ Automated Build Script
|
||||
### iOS Verification
|
||||
|
||||
Create `scripts/build-and-deploy.sh`:
|
||||
After iOS build, verify:
|
||||
|
||||
- [ ] iOS project exists at `ios/App/App.xcworkspace`
|
||||
- [ ] CocoaPods installed (`pod install` completed successfully)
|
||||
- [ ] Plugin framework linked in Xcode project
|
||||
- [ ] App builds without errors in Xcode
|
||||
- [ ] Plugin methods accessible from JavaScript
|
||||
- [ ] System Status shows "Plugin: Available" (green)
|
||||
|
||||
## 🛠️ Automated Build Scripts
|
||||
|
||||
### Unified Build Script (Recommended)
|
||||
|
||||
The project includes a comprehensive build script that handles both platforms:
|
||||
|
||||
```bash
|
||||
# Build both platforms
|
||||
./scripts/build.sh
|
||||
|
||||
# Build Android only
|
||||
./scripts/build.sh --android
|
||||
|
||||
# Build iOS only
|
||||
./scripts/build.sh --ios
|
||||
|
||||
# Build and run Android on emulator
|
||||
./scripts/build.sh --run-android
|
||||
|
||||
# Build and run iOS on simulator
|
||||
./scripts/build.sh --run-ios
|
||||
|
||||
# Build and run both platforms
|
||||
./scripts/build.sh --run
|
||||
|
||||
# Show help
|
||||
./scripts/build.sh --help
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- ✅ Automatically builds web assets
|
||||
- ✅ Syncs Capacitor with both platforms
|
||||
- ✅ Builds Android APK
|
||||
- ✅ Builds iOS app for simulator
|
||||
- ✅ Automatically finds and uses available emulator/simulator
|
||||
- ✅ Installs and launches apps when using `--run` flags
|
||||
- ✅ Color-coded output for easy reading
|
||||
- ✅ Comprehensive error handling
|
||||
|
||||
### Manual Build Scripts
|
||||
|
||||
#### Build for Android
|
||||
|
||||
Create `scripts/build-android.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
@@ -52,7 +199,7 @@ echo "🔨 Building web assets..."
|
||||
npm run build
|
||||
|
||||
echo "🔄 Syncing with native projects..."
|
||||
npm run cap:sync
|
||||
npm run cap:sync:android
|
||||
# This automatically syncs and fixes plugin paths
|
||||
|
||||
echo "🏗️ Building Android app..."
|
||||
@@ -63,7 +210,64 @@ echo "📱 Installing and launching..."
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
adb shell am start -n com.timesafari.dailynotification.test/.MainActivity
|
||||
|
||||
echo "✅ Build and deploy complete!"
|
||||
echo "✅ Android build and deploy complete!"
|
||||
```
|
||||
|
||||
### Build for iOS
|
||||
|
||||
Create `scripts/build-ios.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🔨 Building web assets..."
|
||||
npm run build
|
||||
|
||||
echo "🔄 Syncing with iOS..."
|
||||
npm run cap:sync:ios
|
||||
|
||||
echo "🍎 Building iOS app..."
|
||||
cd ios/App
|
||||
pod install
|
||||
xcodebuild -workspace App.xcworkspace \
|
||||
-scheme App \
|
||||
-configuration Debug \
|
||||
-sdk iphonesimulator \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 15' \
|
||||
build
|
||||
|
||||
echo "✅ iOS build complete!"
|
||||
echo "📱 Open Xcode to run on simulator: open App.xcworkspace"
|
||||
```
|
||||
|
||||
### Build for Both Platforms
|
||||
|
||||
Create `scripts/build-all.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🔨 Building web assets..."
|
||||
npm run build
|
||||
|
||||
echo "🔄 Syncing with all native projects..."
|
||||
npm run cap:sync
|
||||
|
||||
echo "🏗️ Building Android..."
|
||||
cd android && ./gradlew :app:assembleDebug && cd ..
|
||||
|
||||
echo "🍎 Building iOS..."
|
||||
cd ios/App && pod install && cd ../..
|
||||
xcodebuild -workspace ios/App/App.xcworkspace \
|
||||
-scheme App \
|
||||
-configuration Debug \
|
||||
-sdk iphonesimulator \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 15' \
|
||||
build
|
||||
|
||||
echo "✅ All platforms built successfully!"
|
||||
```
|
||||
|
||||
## 🐛 Common Issues
|
||||
@@ -74,9 +278,15 @@ echo "✅ Build and deploy complete!"
|
||||
| Plugin not detected | "Plugin: Not Available" (red) | Check plugin registry, rebuild |
|
||||
| Click events not working | Buttons don't respond | Check Vue 3 compatibility, router config |
|
||||
| Inconsistent status | Different status in different cards | Use consistent detection logic |
|
||||
| **No podspec found** | `[!] No podspec found for 'TimesafariDailyNotificationPlugin'` | Run `node scripts/fix-capacitor-plugins.js` to fix Podfile, then `pod install` |
|
||||
| **Plugin not built** | Vite build fails: "Failed to resolve entry" | Run `npm run build` in plugin root directory (`../../`) |
|
||||
| **CocoaPods not found** | `pod: command not found` | Install CocoaPods: `sudo gem install cocoapods` or via rbenv |
|
||||
| **Xcode not found** | `xcodebuild: command not found` | Install Xcode from App Store, run `xcode-select --install` |
|
||||
|
||||
## 📱 Testing Commands
|
||||
|
||||
### Android Testing
|
||||
|
||||
```bash
|
||||
# Check plugin registry
|
||||
cat android/app/src/main/assets/capacitor.plugins.json
|
||||
@@ -86,8 +296,38 @@ adb logcat | grep -i "dailynotification\|capacitor\|plugin"
|
||||
|
||||
# Check app installation
|
||||
adb shell pm list packages | grep dailynotification
|
||||
|
||||
# View app logs
|
||||
adb logcat -s DailyNotification
|
||||
```
|
||||
|
||||
### iOS Testing
|
||||
|
||||
```bash
|
||||
# Check if iOS project exists
|
||||
ls -la ios/App/App.xcworkspace
|
||||
|
||||
# Check CocoaPods installation
|
||||
cd ios/App && pod install && cd ../..
|
||||
|
||||
# Monitor iOS logs (simulator)
|
||||
xcrun simctl spawn booted log stream | grep -i "dailynotification\|capacitor\|plugin"
|
||||
|
||||
# Check plugin in Xcode
|
||||
# Open ios/App/App.xcworkspace in Xcode
|
||||
# Check: Project Navigator → Frameworks → DailyNotificationPlugin.framework
|
||||
|
||||
# View device logs (physical device)
|
||||
# Xcode → Window → Devices and Simulators → Select device → Open Console
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Use `npm run cap:sync` instead of `npx cap sync android` directly - it automatically fixes the configuration files!
|
||||
## 📝 Important Notes
|
||||
|
||||
**Remember**:
|
||||
- Use `npm run cap:sync` to sync both platforms (automatically fixes Android configuration files)
|
||||
- Use `npm run cap:sync:android` for Android-only sync (includes fix script)
|
||||
- Use `npm run cap:sync:ios` for iOS-only sync
|
||||
- Always run `npm run build` before syncing to ensure latest web assets are copied
|
||||
- For iOS: Run `pod install` in `ios/App/` after first sync or when dependencies change
|
||||
|
||||
13
test-apps/daily-notification-test/ios/.gitignore
vendored
Normal file
13
test-apps/daily-notification-test/ios/.gitignore
vendored
Normal file
@@ -0,0 +1,13 @@
|
||||
App/build
|
||||
App/Pods
|
||||
App/output
|
||||
App/App/public
|
||||
DerivedData
|
||||
xcuserdata
|
||||
|
||||
# Cordova plugins for Capacitor
|
||||
capacitor-cordova-ios-plugins
|
||||
|
||||
# Generated Config files
|
||||
App/App/capacitor.config.json
|
||||
App/App/config.xml
|
||||
@@ -0,0 +1,408 @@
|
||||
// !$*UTF8*$!
|
||||
{
|
||||
archiveVersion = 1;
|
||||
classes = {
|
||||
};
|
||||
objectVersion = 48;
|
||||
objects = {
|
||||
|
||||
/* Begin PBXBuildFile section */
|
||||
2FAD9763203C412B000D30F8 /* config.xml in Resources */ = {isa = PBXBuildFile; fileRef = 2FAD9762203C412B000D30F8 /* config.xml */; };
|
||||
50379B232058CBB4000EE86E /* capacitor.config.json in Resources */ = {isa = PBXBuildFile; fileRef = 50379B222058CBB4000EE86E /* capacitor.config.json */; };
|
||||
504EC3081FED79650016851F /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 504EC3071FED79650016851F /* AppDelegate.swift */; };
|
||||
504EC30D1FED79650016851F /* Main.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 504EC30B1FED79650016851F /* Main.storyboard */; };
|
||||
504EC30F1FED79650016851F /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 504EC30E1FED79650016851F /* Assets.xcassets */; };
|
||||
504EC3121FED79650016851F /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 504EC3101FED79650016851F /* LaunchScreen.storyboard */; };
|
||||
50B271D11FEDC1A000F3C39B /* public in Resources */ = {isa = PBXBuildFile; fileRef = 50B271D01FEDC1A000F3C39B /* public */; };
|
||||
A084ECDBA7D38E1E42DFC39D /* Pods_App.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = AF277DCFFFF123FFC6DF26C7 /* Pods_App.framework */; };
|
||||
/* End PBXBuildFile section */
|
||||
|
||||
/* Begin PBXFileReference section */
|
||||
2FAD9762203C412B000D30F8 /* config.xml */ = {isa = PBXFileReference; lastKnownFileType = text.xml; path = config.xml; sourceTree = "<group>"; };
|
||||
50379B222058CBB4000EE86E /* capacitor.config.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; path = capacitor.config.json; sourceTree = "<group>"; };
|
||||
504EC3041FED79650016851F /* App.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = App.app; sourceTree = BUILT_PRODUCTS_DIR; };
|
||||
504EC3071FED79650016851F /* AppDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AppDelegate.swift; sourceTree = "<group>"; };
|
||||
504EC30C1FED79650016851F /* Base */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; name = Base; path = Base.lproj/Main.storyboard; sourceTree = "<group>"; };
|
||||
504EC30E1FED79650016851F /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
|
||||
504EC3111FED79650016851F /* Base */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; name = Base; path = Base.lproj/LaunchScreen.storyboard; sourceTree = "<group>"; };
|
||||
504EC3131FED79650016851F /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
|
||||
50B271D01FEDC1A000F3C39B /* public */ = {isa = PBXFileReference; lastKnownFileType = folder; path = public; sourceTree = "<group>"; };
|
||||
AF277DCFFFF123FFC6DF26C7 /* Pods_App.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_App.framework; sourceTree = BUILT_PRODUCTS_DIR; };
|
||||
AF51FD2D460BCFE21FA515B2 /* Pods-App.release.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-App.release.xcconfig"; path = "Pods/Target Support Files/Pods-App/Pods-App.release.xcconfig"; sourceTree = "<group>"; };
|
||||
FC68EB0AF532CFC21C3344DD /* Pods-App.debug.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-App.debug.xcconfig"; path = "Pods/Target Support Files/Pods-App/Pods-App.debug.xcconfig"; sourceTree = "<group>"; };
|
||||
/* End PBXFileReference section */
|
||||
|
||||
/* Begin PBXFrameworksBuildPhase section */
|
||||
504EC3011FED79650016851F /* Frameworks */ = {
|
||||
isa = PBXFrameworksBuildPhase;
|
||||
buildActionMask = 2147483647;
|
||||
files = (
|
||||
A084ECDBA7D38E1E42DFC39D /* Pods_App.framework in Frameworks */,
|
||||
);
|
||||
runOnlyForDeploymentPostprocessing = 0;
|
||||
};
|
||||
/* End PBXFrameworksBuildPhase section */
|
||||
|
||||
/* Begin PBXGroup section */
|
||||
27E2DDA53C4D2A4D1A88CE4A /* Frameworks */ = {
|
||||
isa = PBXGroup;
|
||||
children = (
|
||||
AF277DCFFFF123FFC6DF26C7 /* Pods_App.framework */,
|
||||
);
|
||||
name = Frameworks;
|
||||
sourceTree = "<group>";
|
||||
};
|
||||
504EC2FB1FED79650016851F = {
|
||||
isa = PBXGroup;
|
||||
children = (
|
||||
504EC3061FED79650016851F /* App */,
|
||||
504EC3051FED79650016851F /* Products */,
|
||||
7F8756D8B27F46E3366F6CEA /* Pods */,
|
||||
27E2DDA53C4D2A4D1A88CE4A /* Frameworks */,
|
||||
);
|
||||
sourceTree = "<group>";
|
||||
};
|
||||
504EC3051FED79650016851F /* Products */ = {
|
||||
isa = PBXGroup;
|
||||
children = (
|
||||
504EC3041FED79650016851F /* App.app */,
|
||||
);
|
||||
name = Products;
|
||||
sourceTree = "<group>";
|
||||
};
|
||||
504EC3061FED79650016851F /* App */ = {
|
||||
isa = PBXGroup;
|
||||
children = (
|
||||
50379B222058CBB4000EE86E /* capacitor.config.json */,
|
||||
504EC3071FED79650016851F /* AppDelegate.swift */,
|
||||
504EC30B1FED79650016851F /* Main.storyboard */,
|
||||
504EC30E1FED79650016851F /* Assets.xcassets */,
|
||||
504EC3101FED79650016851F /* LaunchScreen.storyboard */,
|
||||
504EC3131FED79650016851F /* Info.plist */,
|
||||
2FAD9762203C412B000D30F8 /* config.xml */,
|
||||
50B271D01FEDC1A000F3C39B /* public */,
|
||||
);
|
||||
path = App;
|
||||
sourceTree = "<group>";
|
||||
};
|
||||
7F8756D8B27F46E3366F6CEA /* Pods */ = {
|
||||
isa = PBXGroup;
|
||||
children = (
|
||||
FC68EB0AF532CFC21C3344DD /* Pods-App.debug.xcconfig */,
|
||||
AF51FD2D460BCFE21FA515B2 /* Pods-App.release.xcconfig */,
|
||||
);
|
||||
name = Pods;
|
||||
sourceTree = "<group>";
|
||||
};
|
||||
/* End PBXGroup section */
|
||||
|
||||
/* Begin PBXNativeTarget section */
|
||||
504EC3031FED79650016851F /* App */ = {
|
||||
isa = PBXNativeTarget;
|
||||
buildConfigurationList = 504EC3161FED79650016851F /* Build configuration list for PBXNativeTarget "App" */;
|
||||
buildPhases = (
|
||||
6634F4EFEBD30273BCE97C65 /* [CP] Check Pods Manifest.lock */,
|
||||
504EC3001FED79650016851F /* Sources */,
|
||||
504EC3011FED79650016851F /* Frameworks */,
|
||||
504EC3021FED79650016851F /* Resources */,
|
||||
9592DBEFFC6D2A0C8D5DEB22 /* [CP] Embed Pods Frameworks */,
|
||||
);
|
||||
buildRules = (
|
||||
);
|
||||
dependencies = (
|
||||
);
|
||||
name = App;
|
||||
productName = App;
|
||||
productReference = 504EC3041FED79650016851F /* App.app */;
|
||||
productType = "com.apple.product-type.application";
|
||||
};
|
||||
/* End PBXNativeTarget section */
|
||||
|
||||
/* Begin PBXProject section */
|
||||
504EC2FC1FED79650016851F /* Project object */ = {
|
||||
isa = PBXProject;
|
||||
attributes = {
|
||||
LastSwiftUpdateCheck = 0920;
|
||||
LastUpgradeCheck = 0920;
|
||||
TargetAttributes = {
|
||||
504EC3031FED79650016851F = {
|
||||
CreatedOnToolsVersion = 9.2;
|
||||
LastSwiftMigration = 1100;
|
||||
ProvisioningStyle = Automatic;
|
||||
};
|
||||
};
|
||||
};
|
||||
buildConfigurationList = 504EC2FF1FED79650016851F /* Build configuration list for PBXProject "App" */;
|
||||
compatibilityVersion = "Xcode 8.0";
|
||||
developmentRegion = en;
|
||||
hasScannedForEncodings = 0;
|
||||
knownRegions = (
|
||||
en,
|
||||
Base,
|
||||
);
|
||||
mainGroup = 504EC2FB1FED79650016851F;
|
||||
packageReferences = (
|
||||
);
|
||||
productRefGroup = 504EC3051FED79650016851F /* Products */;
|
||||
projectDirPath = "";
|
||||
projectRoot = "";
|
||||
targets = (
|
||||
504EC3031FED79650016851F /* App */,
|
||||
);
|
||||
};
|
||||
/* End PBXProject section */
|
||||
|
||||
/* Begin PBXResourcesBuildPhase section */
|
||||
504EC3021FED79650016851F /* Resources */ = {
|
||||
isa = PBXResourcesBuildPhase;
|
||||
buildActionMask = 2147483647;
|
||||
files = (
|
||||
504EC3121FED79650016851F /* LaunchScreen.storyboard in Resources */,
|
||||
50B271D11FEDC1A000F3C39B /* public in Resources */,
|
||||
504EC30F1FED79650016851F /* Assets.xcassets in Resources */,
|
||||
50379B232058CBB4000EE86E /* capacitor.config.json in Resources */,
|
||||
504EC30D1FED79650016851F /* Main.storyboard in Resources */,
|
||||
2FAD9763203C412B000D30F8 /* config.xml in Resources */,
|
||||
);
|
||||
runOnlyForDeploymentPostprocessing = 0;
|
||||
};
|
||||
/* End PBXResourcesBuildPhase section */
|
||||
|
||||
/* Begin PBXShellScriptBuildPhase section */
|
||||
6634F4EFEBD30273BCE97C65 /* [CP] Check Pods Manifest.lock */ = {
|
||||
isa = PBXShellScriptBuildPhase;
|
||||
buildActionMask = 2147483647;
|
||||
files = (
|
||||
);
|
||||
inputPaths = (
|
||||
"${PODS_PODFILE_DIR_PATH}/Podfile.lock",
|
||||
"${PODS_ROOT}/Manifest.lock",
|
||||
);
|
||||
name = "[CP] Check Pods Manifest.lock";
|
||||
outputPaths = (
|
||||
"$(DERIVED_FILE_DIR)/Pods-App-checkManifestLockResult.txt",
|
||||
);
|
||||
runOnlyForDeploymentPostprocessing = 0;
|
||||
shellPath = /bin/sh;
|
||||
shellScript = "diff \"${PODS_PODFILE_DIR_PATH}/Podfile.lock\" \"${PODS_ROOT}/Manifest.lock\" > /dev/null\nif [ $? != 0 ] ; then\n # print error to STDERR\n echo \"error: The sandbox is not in sync with the Podfile.lock. Run 'pod install' or update your CocoaPods installation.\" >&2\n exit 1\nfi\n# This output is used by Xcode 'outputs' to avoid re-running this script phase.\necho \"SUCCESS\" > \"${SCRIPT_OUTPUT_FILE_0}\"\n";
|
||||
showEnvVarsInLog = 0;
|
||||
};
|
||||
9592DBEFFC6D2A0C8D5DEB22 /* [CP] Embed Pods Frameworks */ = {
|
||||
isa = PBXShellScriptBuildPhase;
|
||||
buildActionMask = 2147483647;
|
||||
files = (
|
||||
);
|
||||
inputPaths = (
|
||||
);
|
||||
name = "[CP] Embed Pods Frameworks";
|
||||
outputPaths = (
|
||||
);
|
||||
runOnlyForDeploymentPostprocessing = 0;
|
||||
shellPath = /bin/sh;
|
||||
shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-App/Pods-App-frameworks.sh\"\n";
|
||||
showEnvVarsInLog = 0;
|
||||
};
|
||||
/* End PBXShellScriptBuildPhase section */
|
||||
|
||||
/* Begin PBXSourcesBuildPhase section */
|
||||
504EC3001FED79650016851F /* Sources */ = {
|
||||
isa = PBXSourcesBuildPhase;
|
||||
buildActionMask = 2147483647;
|
||||
files = (
|
||||
504EC3081FED79650016851F /* AppDelegate.swift in Sources */,
|
||||
);
|
||||
runOnlyForDeploymentPostprocessing = 0;
|
||||
};
|
||||
/* End PBXSourcesBuildPhase section */
|
||||
|
||||
/* Begin PBXVariantGroup section */
|
||||
504EC30B1FED79650016851F /* Main.storyboard */ = {
|
||||
isa = PBXVariantGroup;
|
||||
children = (
|
||||
504EC30C1FED79650016851F /* Base */,
|
||||
);
|
||||
name = Main.storyboard;
|
||||
sourceTree = "<group>";
|
||||
};
|
||||
504EC3101FED79650016851F /* LaunchScreen.storyboard */ = {
|
||||
isa = PBXVariantGroup;
|
||||
children = (
|
||||
504EC3111FED79650016851F /* Base */,
|
||||
);
|
||||
name = LaunchScreen.storyboard;
|
||||
sourceTree = "<group>";
|
||||
};
|
||||
/* End PBXVariantGroup section */
|
||||
|
||||
/* Begin XCBuildConfiguration section */
|
||||
504EC3141FED79650016851F /* Debug */ = {
|
||||
isa = XCBuildConfiguration;
|
||||
buildSettings = {
|
||||
ALWAYS_SEARCH_USER_PATHS = NO;
|
||||
CLANG_ANALYZER_NONNULL = YES;
|
||||
CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
|
||||
CLANG_CXX_LANGUAGE_STANDARD = "gnu++14";
|
||||
CLANG_CXX_LIBRARY = "libc++";
|
||||
CLANG_ENABLE_MODULES = YES;
|
||||
CLANG_ENABLE_OBJC_ARC = YES;
|
||||
CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
|
||||
CLANG_WARN_BOOL_CONVERSION = YES;
|
||||
CLANG_WARN_COMMA = YES;
|
||||
CLANG_WARN_CONSTANT_CONVERSION = YES;
|
||||
CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
|
||||
CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
|
||||
CLANG_WARN_EMPTY_BODY = YES;
|
||||
CLANG_WARN_ENUM_CONVERSION = YES;
|
||||
CLANG_WARN_INFINITE_RECURSION = YES;
|
||||
CLANG_WARN_INT_CONVERSION = YES;
|
||||
CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
|
||||
CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
|
||||
CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
|
||||
CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
|
||||
CLANG_WARN_STRICT_PROTOTYPES = YES;
|
||||
CLANG_WARN_SUSPICIOUS_MOVE = YES;
|
||||
CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
|
||||
CLANG_WARN_UNREACHABLE_CODE = YES;
|
||||
CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
|
||||
CODE_SIGN_IDENTITY = "iPhone Developer";
|
||||
COPY_PHASE_STRIP = NO;
|
||||
DEBUG_INFORMATION_FORMAT = dwarf;
|
||||
ENABLE_STRICT_OBJC_MSGSEND = YES;
|
||||
ENABLE_TESTABILITY = YES;
|
||||
GCC_C_LANGUAGE_STANDARD = gnu11;
|
||||
GCC_DYNAMIC_NO_PIC = NO;
|
||||
GCC_NO_COMMON_BLOCKS = YES;
|
||||
GCC_OPTIMIZATION_LEVEL = 0;
|
||||
GCC_PREPROCESSOR_DEFINITIONS = (
|
||||
"DEBUG=1",
|
||||
"$(inherited)",
|
||||
);
|
||||
GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
|
||||
GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
|
||||
GCC_WARN_UNDECLARED_SELECTOR = YES;
|
||||
GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
|
||||
GCC_WARN_UNUSED_FUNCTION = YES;
|
||||
GCC_WARN_UNUSED_VARIABLE = YES;
|
||||
IPHONEOS_DEPLOYMENT_TARGET = 13.0;
|
||||
MTL_ENABLE_DEBUG_INFO = YES;
|
||||
ONLY_ACTIVE_ARCH = YES;
|
||||
SDKROOT = iphoneos;
|
||||
SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
|
||||
SWIFT_OPTIMIZATION_LEVEL = "-Onone";
|
||||
};
|
||||
name = Debug;
|
||||
};
|
||||
504EC3151FED79650016851F /* Release */ = {
|
||||
isa = XCBuildConfiguration;
|
||||
buildSettings = {
|
||||
ALWAYS_SEARCH_USER_PATHS = NO;
|
||||
CLANG_ANALYZER_NONNULL = YES;
|
||||
CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
|
||||
CLANG_CXX_LANGUAGE_STANDARD = "gnu++14";
|
||||
CLANG_CXX_LIBRARY = "libc++";
|
||||
CLANG_ENABLE_MODULES = YES;
|
||||
CLANG_ENABLE_OBJC_ARC = YES;
|
||||
CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
|
||||
CLANG_WARN_BOOL_CONVERSION = YES;
|
||||
CLANG_WARN_COMMA = YES;
|
||||
CLANG_WARN_CONSTANT_CONVERSION = YES;
|
||||
CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
|
||||
CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
|
||||
CLANG_WARN_EMPTY_BODY = YES;
|
||||
CLANG_WARN_ENUM_CONVERSION = YES;
|
||||
CLANG_WARN_INFINITE_RECURSION = YES;
|
||||
CLANG_WARN_INT_CONVERSION = YES;
|
||||
CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
|
||||
CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
|
||||
CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
|
||||
CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
|
||||
CLANG_WARN_STRICT_PROTOTYPES = YES;
|
||||
CLANG_WARN_SUSPICIOUS_MOVE = YES;
|
||||
CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
|
||||
CLANG_WARN_UNREACHABLE_CODE = YES;
|
||||
CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
|
||||
CODE_SIGN_IDENTITY = "iPhone Developer";
|
||||
COPY_PHASE_STRIP = NO;
|
||||
DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
|
||||
ENABLE_NS_ASSERTIONS = NO;
|
||||
ENABLE_STRICT_OBJC_MSGSEND = YES;
|
||||
GCC_C_LANGUAGE_STANDARD = gnu11;
|
||||
GCC_NO_COMMON_BLOCKS = YES;
|
||||
GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
|
||||
GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
|
||||
GCC_WARN_UNDECLARED_SELECTOR = YES;
|
||||
GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
|
||||
GCC_WARN_UNUSED_FUNCTION = YES;
|
||||
GCC_WARN_UNUSED_VARIABLE = YES;
|
||||
IPHONEOS_DEPLOYMENT_TARGET = 13.0;
|
||||
MTL_ENABLE_DEBUG_INFO = NO;
|
||||
SDKROOT = iphoneos;
|
||||
SWIFT_OPTIMIZATION_LEVEL = "-Owholemodule";
|
||||
VALIDATE_PRODUCT = YES;
|
||||
};
|
||||
name = Release;
|
||||
};
|
||||
504EC3171FED79650016851F /* Debug */ = {
|
||||
isa = XCBuildConfiguration;
|
||||
baseConfigurationReference = FC68EB0AF532CFC21C3344DD /* Pods-App.debug.xcconfig */;
|
||||
buildSettings = {
|
||||
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
|
||||
CODE_SIGN_STYLE = Automatic;
|
||||
CURRENT_PROJECT_VERSION = 1;
|
||||
INFOPLIST_FILE = App/Info.plist;
|
||||
IPHONEOS_DEPLOYMENT_TARGET = 13.0;
|
||||
LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks";
|
||||
MARKETING_VERSION = 1.0;
|
||||
OTHER_SWIFT_FLAGS = "$(inherited) \"-D\" \"COCOAPODS\" \"-DDEBUG\"";
|
||||
PRODUCT_BUNDLE_IDENTIFIER = com.timesafari.dailynotification.test;
|
||||
PRODUCT_NAME = "$(TARGET_NAME)";
|
||||
SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
|
||||
SWIFT_VERSION = 5.0;
|
||||
TARGETED_DEVICE_FAMILY = "1,2";
|
||||
};
|
||||
name = Debug;
|
||||
};
|
||||
504EC3181FED79650016851F /* Release */ = {
|
||||
isa = XCBuildConfiguration;
|
||||
baseConfigurationReference = AF51FD2D460BCFE21FA515B2 /* Pods-App.release.xcconfig */;
|
||||
buildSettings = {
|
||||
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
|
||||
CODE_SIGN_STYLE = Automatic;
|
||||
CURRENT_PROJECT_VERSION = 1;
|
||||
INFOPLIST_FILE = App/Info.plist;
|
||||
IPHONEOS_DEPLOYMENT_TARGET = 13.0;
|
||||
LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks";
|
||||
MARKETING_VERSION = 1.0;
|
||||
PRODUCT_BUNDLE_IDENTIFIER = com.timesafari.dailynotification.test;
|
||||
PRODUCT_NAME = "$(TARGET_NAME)";
|
||||
SWIFT_ACTIVE_COMPILATION_CONDITIONS = "";
|
||||
SWIFT_VERSION = 5.0;
|
||||
TARGETED_DEVICE_FAMILY = "1,2";
|
||||
};
|
||||
name = Release;
|
||||
};
|
||||
/* End XCBuildConfiguration section */
|
||||
|
||||
/* Begin XCConfigurationList section */
|
||||
504EC2FF1FED79650016851F /* Build configuration list for PBXProject "App" */ = {
|
||||
isa = XCConfigurationList;
|
||||
buildConfigurations = (
|
||||
504EC3141FED79650016851F /* Debug */,
|
||||
504EC3151FED79650016851F /* Release */,
|
||||
);
|
||||
defaultConfigurationIsVisible = 0;
|
||||
defaultConfigurationName = Release;
|
||||
};
|
||||
504EC3161FED79650016851F /* Build configuration list for PBXNativeTarget "App" */ = {
|
||||
isa = XCConfigurationList;
|
||||
buildConfigurations = (
|
||||
504EC3171FED79650016851F /* Debug */,
|
||||
504EC3181FED79650016851F /* Release */,
|
||||
);
|
||||
defaultConfigurationIsVisible = 0;
|
||||
defaultConfigurationName = Release;
|
||||
};
|
||||
/* End XCConfigurationList section */
|
||||
};
|
||||
rootObject = 504EC2FC1FED79650016851F /* Project object */;
|
||||
}
|
||||
10
test-apps/daily-notification-test/ios/App/App.xcworkspace/contents.xcworkspacedata
generated
Normal file
10
test-apps/daily-notification-test/ios/App/App.xcworkspace/contents.xcworkspacedata
generated
Normal file
@@ -0,0 +1,10 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<Workspace
|
||||
version = "1.0">
|
||||
<FileRef
|
||||
location = "group:App.xcodeproj">
|
||||
</FileRef>
|
||||
<FileRef
|
||||
location = "group:Pods/Pods.xcodeproj">
|
||||
</FileRef>
|
||||
</Workspace>
|
||||
@@ -0,0 +1,8 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>IDEDidComputeMac32BitWarning</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</plist>
|
||||
@@ -0,0 +1,49 @@
|
||||
import UIKit
|
||||
import Capacitor
|
||||
|
||||
@UIApplicationMain
|
||||
class AppDelegate: UIResponder, UIApplicationDelegate {
|
||||
|
||||
var window: UIWindow?
|
||||
|
||||
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
|
||||
// Override point for customization after application launch.
|
||||
return true
|
||||
}
|
||||
|
||||
func applicationWillResignActive(_ application: UIApplication) {
|
||||
// Sent when the application is about to move from active to inactive state. This can occur for certain types of temporary interruptions (such as an incoming phone call or SMS message) or when the user quits the application and it begins the transition to the background state.
|
||||
// Use this method to pause ongoing tasks, disable timers, and invalidate graphics rendering callbacks. Games should use this method to pause the game.
|
||||
}
|
||||
|
||||
func applicationDidEnterBackground(_ application: UIApplication) {
|
||||
// Use this method to release shared resources, save user data, invalidate timers, and store enough application state information to restore your application to its current state in case it is terminated later.
|
||||
// If your application supports background execution, this method is called instead of applicationWillTerminate: when the user quits.
|
||||
}
|
||||
|
||||
func applicationWillEnterForeground(_ application: UIApplication) {
|
||||
// Called as part of the transition from the background to the active state; here you can undo many of the changes made on entering the background.
|
||||
}
|
||||
|
||||
func applicationDidBecomeActive(_ application: UIApplication) {
|
||||
// Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.
|
||||
}
|
||||
|
||||
func applicationWillTerminate(_ application: UIApplication) {
|
||||
// Called when the application is about to terminate. Save data if appropriate. See also applicationDidEnterBackground:.
|
||||
}
|
||||
|
||||
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
|
||||
// Called when the app was launched with a url. Feel free to add additional processing here,
|
||||
// but if you want the App API to support tracking app url opens, make sure to keep this call
|
||||
return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
|
||||
}
|
||||
|
||||
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
|
||||
// Called when the app was launched with an activity, including Universal Links.
|
||||
// Feel free to add additional processing here, but if you want the App API to support
|
||||
// tracking app url opens, make sure to keep this call
|
||||
return ApplicationDelegateProxy.shared.application(application, continue: userActivity, restorationHandler: restorationHandler)
|
||||
}
|
||||
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 108 KiB |
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"images" : [
|
||||
{
|
||||
"filename" : "AppIcon-512@2x.png",
|
||||
"idiom" : "universal",
|
||||
"platform" : "ios",
|
||||
"size" : "1024x1024"
|
||||
}
|
||||
],
|
||||
"info" : {
|
||||
"author" : "xcode",
|
||||
"version" : 1
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"info" : {
|
||||
"version" : 1,
|
||||
"author" : "xcode"
|
||||
}
|
||||
}
|
||||
23
test-apps/daily-notification-test/ios/App/App/Assets.xcassets/Splash.imageset/Contents.json
vendored
Normal file
23
test-apps/daily-notification-test/ios/App/App/Assets.xcassets/Splash.imageset/Contents.json
vendored
Normal file
@@ -0,0 +1,23 @@
|
||||
{
|
||||
"images" : [
|
||||
{
|
||||
"idiom" : "universal",
|
||||
"filename" : "splash-2732x2732-2.png",
|
||||
"scale" : "1x"
|
||||
},
|
||||
{
|
||||
"idiom" : "universal",
|
||||
"filename" : "splash-2732x2732-1.png",
|
||||
"scale" : "2x"
|
||||
},
|
||||
{
|
||||
"idiom" : "universal",
|
||||
"filename" : "splash-2732x2732.png",
|
||||
"scale" : "3x"
|
||||
}
|
||||
],
|
||||
"info" : {
|
||||
"version" : 1,
|
||||
"author" : "xcode"
|
||||
}
|
||||
}
|
||||
BIN
test-apps/daily-notification-test/ios/App/App/Assets.xcassets/Splash.imageset/splash-2732x2732-1.png
vendored
Normal file
BIN
test-apps/daily-notification-test/ios/App/App/Assets.xcassets/Splash.imageset/splash-2732x2732-1.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
BIN
test-apps/daily-notification-test/ios/App/App/Assets.xcassets/Splash.imageset/splash-2732x2732-2.png
vendored
Normal file
BIN
test-apps/daily-notification-test/ios/App/App/Assets.xcassets/Splash.imageset/splash-2732x2732-2.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
BIN
test-apps/daily-notification-test/ios/App/App/Assets.xcassets/Splash.imageset/splash-2732x2732.png
vendored
Normal file
BIN
test-apps/daily-notification-test/ios/App/App/Assets.xcassets/Splash.imageset/splash-2732x2732.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
@@ -0,0 +1,32 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="17132" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" launchScreen="YES" useTraitCollections="YES" useSafeAreas="YES" colorMatched="YES" initialViewController="01J-lp-oVM">
|
||||
<device id="retina4_7" orientation="portrait" appearance="light"/>
|
||||
<dependencies>
|
||||
<deployment identifier="iOS"/>
|
||||
<plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="17105"/>
|
||||
<capability name="System colors in document resources" minToolsVersion="11.0"/>
|
||||
<capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
|
||||
</dependencies>
|
||||
<scenes>
|
||||
<!--View Controller-->
|
||||
<scene sceneID="EHf-IW-A2E">
|
||||
<objects>
|
||||
<viewController id="01J-lp-oVM" sceneMemberID="viewController">
|
||||
<imageView key="view" userInteractionEnabled="NO" contentMode="scaleAspectFill" horizontalHuggingPriority="251" verticalHuggingPriority="251" image="Splash" id="snD-IY-ifK">
|
||||
<rect key="frame" x="0.0" y="0.0" width="375" height="667"/>
|
||||
<autoresizingMask key="autoresizingMask"/>
|
||||
<color key="backgroundColor" systemColor="systemBackgroundColor"/>
|
||||
</imageView>
|
||||
</viewController>
|
||||
<placeholder placeholderIdentifier="IBFirstResponder" id="iYj-Kq-Ea1" userLabel="First Responder" sceneMemberID="firstResponder"/>
|
||||
</objects>
|
||||
<point key="canvasLocation" x="53" y="375"/>
|
||||
</scene>
|
||||
</scenes>
|
||||
<resources>
|
||||
<image name="Splash" width="1366" height="1366"/>
|
||||
<systemColor name="systemBackgroundColor">
|
||||
<color white="1" alpha="1" colorSpace="custom" customColorSpace="genericGamma22GrayColorSpace"/>
|
||||
</systemColor>
|
||||
</resources>
|
||||
</document>
|
||||
@@ -0,0 +1,19 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="14111" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" useTraitCollections="YES" colorMatched="YES" initialViewController="BYZ-38-t0r">
|
||||
<device id="retina4_7" orientation="portrait">
|
||||
<adaptation id="fullscreen"/>
|
||||
</device>
|
||||
<dependencies>
|
||||
<deployment identifier="iOS"/>
|
||||
<plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="14088"/>
|
||||
</dependencies>
|
||||
<scenes>
|
||||
<!--Bridge View Controller-->
|
||||
<scene sceneID="tne-QT-ifu">
|
||||
<objects>
|
||||
<viewController id="BYZ-38-t0r" customClass="CAPBridgeViewController" customModule="Capacitor" sceneMemberID="viewController"/>
|
||||
<placeholder placeholderIdentifier="IBFirstResponder" id="dkx-z0-nzr" sceneMemberID="firstResponder"/>
|
||||
</objects>
|
||||
</scene>
|
||||
</scenes>
|
||||
</document>
|
||||
62
test-apps/daily-notification-test/ios/App/App/Info.plist
Normal file
62
test-apps/daily-notification-test/ios/App/App/Info.plist
Normal file
@@ -0,0 +1,62 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>CFBundleDevelopmentRegion</key>
|
||||
<string>en</string>
|
||||
<key>CFBundleDisplayName</key>
|
||||
<string>Daily Notification Test</string>
|
||||
<key>CFBundleExecutable</key>
|
||||
<string>$(EXECUTABLE_NAME)</string>
|
||||
<key>CFBundleIdentifier</key>
|
||||
<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
|
||||
<key>CFBundleInfoDictionaryVersion</key>
|
||||
<string>6.0</string>
|
||||
<key>CFBundleName</key>
|
||||
<string>$(PRODUCT_NAME)</string>
|
||||
<key>CFBundlePackageType</key>
|
||||
<string>APPL</string>
|
||||
<key>CFBundleShortVersionString</key>
|
||||
<string>$(MARKETING_VERSION)</string>
|
||||
<key>CFBundleVersion</key>
|
||||
<string>$(CURRENT_PROJECT_VERSION)</string>
|
||||
<key>LSRequiresIPhoneOS</key>
|
||||
<true/>
|
||||
<key>UILaunchStoryboardName</key>
|
||||
<string>LaunchScreen</string>
|
||||
<key>UIMainStoryboardFile</key>
|
||||
<string>Main</string>
|
||||
<key>UIRequiredDeviceCapabilities</key>
|
||||
<array>
|
||||
<string>armv7</string>
|
||||
</array>
|
||||
<key>UISupportedInterfaceOrientations</key>
|
||||
<array>
|
||||
<string>UIInterfaceOrientationPortrait</string>
|
||||
<string>UIInterfaceOrientationLandscapeLeft</string>
|
||||
<string>UIInterfaceOrientationLandscapeRight</string>
|
||||
</array>
|
||||
<key>UISupportedInterfaceOrientations~ipad</key>
|
||||
<array>
|
||||
<string>UIInterfaceOrientationPortrait</string>
|
||||
<string>UIInterfaceOrientationPortraitUpsideDown</string>
|
||||
<string>UIInterfaceOrientationLandscapeLeft</string>
|
||||
<string>UIInterfaceOrientationLandscapeRight</string>
|
||||
</array>
|
||||
<key>UIViewControllerBasedStatusBarAppearance</key>
|
||||
<true/>
|
||||
<key>BGTaskSchedulerPermittedIdentifiers</key>
|
||||
<array>
|
||||
<string>com.timesafari.dailynotification.fetch</string>
|
||||
<string>com.timesafari.dailynotification.notify</string>
|
||||
</array>
|
||||
<key>UIBackgroundModes</key>
|
||||
<array>
|
||||
<string>background-fetch</string>
|
||||
<string>background-processing</string>
|
||||
<string>remote-notification</string>
|
||||
</array>
|
||||
<key>NSUserNotificationsUsageDescription</key>
|
||||
<string>This app uses notifications to deliver daily updates and reminders.</string>
|
||||
</dict>
|
||||
</plist>
|
||||
24
test-apps/daily-notification-test/ios/App/Podfile
Normal file
24
test-apps/daily-notification-test/ios/App/Podfile
Normal file
@@ -0,0 +1,24 @@
|
||||
require_relative '../../../../node_modules/@capacitor/ios/scripts/pods_helpers'
|
||||
|
||||
platform :ios, '13.0'
|
||||
use_frameworks!
|
||||
|
||||
# workaround to avoid Xcode caching of Pods that requires
|
||||
# Product -> Clean Build Folder after new Cordova plugins installed
|
||||
# Requires CocoaPods 1.6 or newer
|
||||
install! 'cocoapods', :disable_input_output_paths => true
|
||||
|
||||
def capacitor_pods
|
||||
pod 'Capacitor', :path => '../../../../node_modules/@capacitor/ios'
|
||||
pod 'CapacitorCordova', :path => '../../../../node_modules/@capacitor/ios'
|
||||
pod 'DailyNotificationPlugin', :path => '../../node_modules/@timesafari/daily-notification-plugin/ios'
|
||||
end
|
||||
|
||||
target 'App' do
|
||||
capacitor_pods
|
||||
# Add your Pods here
|
||||
end
|
||||
|
||||
post_install do |installer|
|
||||
assertDeploymentTarget(installer)
|
||||
end
|
||||
@@ -45,7 +45,7 @@
|
||||
},
|
||||
"../..": {
|
||||
"name": "@timesafari/daily-notification-plugin",
|
||||
"version": "1.0.0",
|
||||
"version": "1.0.11",
|
||||
"license": "MIT",
|
||||
"workspaces": [
|
||||
"packages/*"
|
||||
|
||||
@@ -13,11 +13,14 @@
|
||||
"build-only": "vite build",
|
||||
"type-check": "vue-tsc --build",
|
||||
"lint": "eslint . --fix",
|
||||
"cap:sync": "npx cap sync android && node scripts/fix-capacitor-plugins.js",
|
||||
"cap:sync": "npx cap sync && node scripts/fix-capacitor-plugins.js",
|
||||
"cap:sync:android": "npx cap sync android && node scripts/fix-capacitor-plugins.js",
|
||||
"cap:sync:ios": "npx cap sync ios",
|
||||
"postinstall": "node scripts/fix-capacitor-plugins.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"@capacitor/android": "^6.2.1",
|
||||
"@capacitor/ios": "^6.2.1",
|
||||
"@capacitor/cli": "^6.2.1",
|
||||
"@capacitor/core": "^6.2.1",
|
||||
"@timesafari/daily-notification-plugin": "file:../../",
|
||||
|
||||
569
test-apps/daily-notification-test/scripts/build.sh
Executable file
569
test-apps/daily-notification-test/scripts/build.sh
Executable file
@@ -0,0 +1,569 @@
|
||||
#!/bin/bash
|
||||
|
||||
# Build script for daily-notification-test Capacitor app
|
||||
# Supports both Android and iOS with emulator/simulator deployment
|
||||
#
|
||||
# Requirements:
|
||||
# - Node.js 20.19.0+ or 22.12.0+
|
||||
# - npm
|
||||
# - Plugin must be built (script will auto-build if needed)
|
||||
# - For Android: Java JDK 22.12+, Android SDK (adb)
|
||||
# - For iOS: Xcode, CocoaPods (pod)
|
||||
#
|
||||
# Usage:
|
||||
# ./scripts/build.sh # Build both platforms
|
||||
# ./scripts/build.sh --android # Build Android only
|
||||
# ./scripts/build.sh --ios # Build iOS only
|
||||
# ./scripts/build.sh --run # Build and run both
|
||||
# ./scripts/build.sh --help # Show help
|
||||
|
||||
set -e
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Script directory
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
|
||||
# Logging functions
|
||||
log_info() {
|
||||
echo -e "${GREEN}[INFO]${NC} $1"
|
||||
}
|
||||
|
||||
log_warn() {
|
||||
echo -e "${YELLOW}[WARN]${NC} $1"
|
||||
}
|
||||
|
||||
log_error() {
|
||||
echo -e "${RED}[ERROR]${NC} $1"
|
||||
}
|
||||
|
||||
log_step() {
|
||||
echo -e "${BLUE}[STEP]${NC} $1"
|
||||
}
|
||||
|
||||
# Validation functions
|
||||
check_command() {
|
||||
if ! command -v $1 &> /dev/null; then
|
||||
log_error "$1 is not installed. Please install it first."
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Get pod command (handles rbenv)
|
||||
get_pod_command() {
|
||||
if command -v pod &> /dev/null; then
|
||||
echo "pod"
|
||||
elif [ -f "$HOME/.rbenv/shims/pod" ]; then
|
||||
echo "$HOME/.rbenv/shims/pod"
|
||||
else
|
||||
log_error "CocoaPods (pod) not found. Please install CocoaPods first."
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Check requirements
|
||||
check_requirements() {
|
||||
log_step "Checking build requirements..."
|
||||
|
||||
local missing_requirements=false
|
||||
|
||||
# Check Node.js
|
||||
if ! command -v node &> /dev/null; then
|
||||
log_error "Node.js is not installed. Please install Node.js 20.19.0+ or 22.12.0+"
|
||||
missing_requirements=true
|
||||
else
|
||||
log_info "✅ Node.js: $(node --version)"
|
||||
fi
|
||||
|
||||
# Check npm
|
||||
if ! command -v npm &> /dev/null; then
|
||||
log_error "npm is not installed"
|
||||
missing_requirements=true
|
||||
else
|
||||
log_info "✅ npm: $(npm --version)"
|
||||
fi
|
||||
|
||||
# Check plugin is built
|
||||
PLUGIN_ROOT="$(cd "$PROJECT_DIR/../.." && pwd)"
|
||||
if [ ! -d "$PLUGIN_ROOT/dist" ]; then
|
||||
log_warn "Plugin not built. Building plugin now..."
|
||||
cd "$PLUGIN_ROOT"
|
||||
if npm run build; then
|
||||
log_info "✅ Plugin built successfully"
|
||||
else
|
||||
log_error "Failed to build plugin. Please run 'npm run build' in the plugin root directory."
|
||||
missing_requirements=true
|
||||
fi
|
||||
cd "$PROJECT_DIR"
|
||||
else
|
||||
log_info "✅ Plugin built (dist/ exists)"
|
||||
fi
|
||||
|
||||
# Check Android requirements if building Android
|
||||
if [ "$BUILD_ALL" = true ] || [ "$BUILD_ANDROID" = true ]; then
|
||||
if ! command -v adb &> /dev/null; then
|
||||
log_warn "Android SDK not found (adb not in PATH). Android build will be skipped."
|
||||
else
|
||||
log_info "✅ Android SDK: $(adb version | head -1)"
|
||||
fi
|
||||
|
||||
if ! command -v java &> /dev/null; then
|
||||
log_warn "Java not found. Android build may fail."
|
||||
else
|
||||
log_info "✅ Java: $(java -version 2>&1 | head -1)"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check iOS requirements if building iOS
|
||||
if [ "$BUILD_ALL" = true ] || [ "$BUILD_IOS" = true ]; then
|
||||
if ! command -v xcodebuild &> /dev/null; then
|
||||
log_warn "Xcode not found (xcodebuild not in PATH). iOS build will be skipped."
|
||||
else
|
||||
log_info "✅ Xcode: $(xcodebuild -version | head -1)"
|
||||
fi
|
||||
|
||||
POD_CMD=$(get_pod_command 2>/dev/null || echo "")
|
||||
if [ -z "$POD_CMD" ]; then
|
||||
log_warn "CocoaPods not found. iOS build will be skipped."
|
||||
else
|
||||
log_info "✅ CocoaPods: $($POD_CMD --version 2>/dev/null || echo 'found')"
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$missing_requirements" = true ]; then
|
||||
log_error "Missing required dependencies. Please install them and try again."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
log_info "All requirements satisfied"
|
||||
}
|
||||
|
||||
# Parse arguments
|
||||
BUILD_ANDROID=false
|
||||
BUILD_IOS=false
|
||||
BUILD_ALL=true
|
||||
RUN_ANDROID=false
|
||||
RUN_IOS=false
|
||||
RUN_ALL=false
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case $1 in
|
||||
--android)
|
||||
BUILD_ANDROID=true
|
||||
BUILD_ALL=false
|
||||
shift
|
||||
;;
|
||||
--ios)
|
||||
BUILD_IOS=true
|
||||
BUILD_ALL=false
|
||||
shift
|
||||
;;
|
||||
--run-android)
|
||||
RUN_ANDROID=true
|
||||
BUILD_ANDROID=true
|
||||
BUILD_ALL=false
|
||||
shift
|
||||
;;
|
||||
--run-ios)
|
||||
RUN_IOS=true
|
||||
BUILD_IOS=true
|
||||
BUILD_ALL=false
|
||||
shift
|
||||
;;
|
||||
--run)
|
||||
RUN_ALL=true
|
||||
BUILD_ALL=true
|
||||
shift
|
||||
;;
|
||||
--help|-h)
|
||||
echo "Usage: $0 [OPTIONS]"
|
||||
echo ""
|
||||
echo "Options:"
|
||||
echo " --android Build Android only"
|
||||
echo " --ios Build iOS only"
|
||||
echo " --run-android Build and run Android on emulator"
|
||||
echo " --run-ios Build and run iOS on simulator"
|
||||
echo " --run Build and run both platforms"
|
||||
echo " --help, -h Show this help message"
|
||||
echo ""
|
||||
echo "Default: Build both platforms (no run)"
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
log_error "Unknown option: $1"
|
||||
echo "Use --help for usage information"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Change to project directory
|
||||
cd "$PROJECT_DIR"
|
||||
|
||||
log_info "Building daily-notification-test app"
|
||||
log_info "Project directory: $PROJECT_DIR"
|
||||
|
||||
# Check requirements
|
||||
check_requirements
|
||||
|
||||
# Step 1: Build web assets
|
||||
log_step "Building web assets..."
|
||||
if ! npm run build; then
|
||||
log_error "Web build failed"
|
||||
exit 1
|
||||
fi
|
||||
log_info "Web assets built successfully"
|
||||
|
||||
# Step 2: Sync Capacitor
|
||||
log_step "Syncing Capacitor with native projects..."
|
||||
if ! npm run cap:sync; then
|
||||
log_error "Capacitor sync failed"
|
||||
exit 1
|
||||
fi
|
||||
log_info "Capacitor sync completed"
|
||||
|
||||
# Step 2.5: Ensure fix script ran (it should have via cap:sync, but verify for iOS)
|
||||
if [ "$BUILD_ALL" = true ] || [ "$BUILD_IOS" = true ]; then
|
||||
if [ -d "$PROJECT_DIR/ios" ]; then
|
||||
log_step "Verifying iOS Podfile configuration..."
|
||||
if node "$PROJECT_DIR/scripts/fix-capacitor-plugins.js" 2>/dev/null; then
|
||||
log_info "iOS Podfile verified"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Android build
|
||||
if [ "$BUILD_ALL" = true ] || [ "$BUILD_ANDROID" = true ]; then
|
||||
log_step "Building Android app..."
|
||||
|
||||
# Check for Android SDK
|
||||
if ! command -v adb &> /dev/null; then
|
||||
log_warn "adb not found. Android SDK may not be installed."
|
||||
log_warn "Skipping Android build. Install Android SDK to build Android."
|
||||
else
|
||||
cd "$PROJECT_DIR/android"
|
||||
|
||||
# Build APK
|
||||
if ./gradlew :app:assembleDebug; then
|
||||
log_info "Android APK built successfully"
|
||||
|
||||
APK_PATH="$PROJECT_DIR/android/app/build/outputs/apk/debug/app-debug.apk"
|
||||
|
||||
if [ -f "$APK_PATH" ]; then
|
||||
log_info "APK location: $APK_PATH"
|
||||
|
||||
# Run on emulator if requested
|
||||
if [ "$RUN_ALL" = true ] || [ "$RUN_ANDROID" = true ]; then
|
||||
log_step "Installing and launching Android app..."
|
||||
|
||||
# Check for running emulator
|
||||
if ! adb devices | grep -q "device$"; then
|
||||
log_warn "No Android emulator/device found"
|
||||
log_info "Please start an Android emulator and try again"
|
||||
log_info "Or use: adb devices to check connected devices"
|
||||
else
|
||||
# Install APK
|
||||
if adb install -r "$APK_PATH"; then
|
||||
log_info "APK installed successfully"
|
||||
|
||||
# Launch app
|
||||
if adb shell am start -n com.timesafari.dailynotification.test/.MainActivity; then
|
||||
log_info "✅ Android app launched successfully!"
|
||||
else
|
||||
log_warn "Failed to launch app (may already be running)"
|
||||
fi
|
||||
else
|
||||
log_warn "APK installation failed (may already be installed)"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
else
|
||||
log_error "APK not found at expected location: $APK_PATH"
|
||||
fi
|
||||
else
|
||||
log_error "Android build failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
cd "$PROJECT_DIR"
|
||||
fi
|
||||
fi
|
||||
|
||||
# iOS build
|
||||
if [ "$BUILD_ALL" = true ] || [ "$BUILD_IOS" = true ]; then
|
||||
log_step "Building iOS app..."
|
||||
|
||||
# Check for Xcode
|
||||
if ! command -v xcodebuild &> /dev/null; then
|
||||
log_warn "xcodebuild not found. Xcode may not be installed."
|
||||
log_warn "Skipping iOS build. Install Xcode to build iOS."
|
||||
else
|
||||
IOS_DIR="$PROJECT_DIR/ios/App"
|
||||
|
||||
if [ ! -d "$IOS_DIR" ]; then
|
||||
log_warn "iOS directory not found. Adding iOS platform..."
|
||||
cd "$PROJECT_DIR"
|
||||
npx cap add ios
|
||||
fi
|
||||
|
||||
cd "$IOS_DIR"
|
||||
|
||||
# Install CocoaPods dependencies
|
||||
log_step "Installing CocoaPods dependencies..."
|
||||
POD_CMD=$(get_pod_command)
|
||||
|
||||
# Check if Podfile exists and has correct plugin reference
|
||||
if [ -f "$IOS_DIR/Podfile" ]; then
|
||||
# Run fix script to ensure Podfile is correct
|
||||
log_step "Verifying Podfile configuration..."
|
||||
if node "$PROJECT_DIR/scripts/fix-capacitor-plugins.js" 2>/dev/null; then
|
||||
log_info "Podfile verified"
|
||||
fi
|
||||
fi
|
||||
|
||||
if $POD_CMD install; then
|
||||
log_info "CocoaPods dependencies installed"
|
||||
else
|
||||
log_error "CocoaPods install failed"
|
||||
log_info "Troubleshooting:"
|
||||
log_info "1. Check that plugin podspec exists: ls -la $PLUGIN_ROOT/ios/DailyNotificationPlugin.podspec"
|
||||
log_info "2. Verify Podfile references: pod 'DailyNotificationPlugin', :path => '../../node_modules/@timesafari/daily-notification-plugin/ios'"
|
||||
log_info "3. Run fix script: node scripts/fix-capacitor-plugins.js"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Find workspace
|
||||
WORKSPACE="$IOS_DIR/App.xcworkspace"
|
||||
if [ ! -d "$WORKSPACE" ]; then
|
||||
WORKSPACE="$IOS_DIR/App.xcodeproj"
|
||||
fi
|
||||
|
||||
if [ ! -d "$WORKSPACE" ]; then
|
||||
log_error "Xcode workspace/project not found at $IOS_DIR"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Get simulator
|
||||
log_step "Finding available iOS simulator..."
|
||||
|
||||
# Method 1: Use xcodebuild to get available destinations (most reliable)
|
||||
# This gives us the exact format xcodebuild expects
|
||||
DESTINATION_STRING=$(xcodebuild -workspace "$WORKSPACE" -scheme App -showdestinations 2>/dev/null | \
|
||||
grep "iOS Simulator" | \
|
||||
grep -i "iphone" | \
|
||||
grep -v "iPhone Air" | \
|
||||
head -1)
|
||||
|
||||
if [ -n "$DESTINATION_STRING" ]; then
|
||||
# Extract name from destination string
|
||||
# Format: "platform=iOS Simulator,id=...,name=iPhone 17 Pro,OS=26.0.1"
|
||||
SIMULATOR=$(echo "$DESTINATION_STRING" | \
|
||||
sed -n 's/.*name=\([^,]*\).*/\1/p' | \
|
||||
sed 's/[[:space:]]*$//')
|
||||
log_info "Found simulator via xcodebuild: $SIMULATOR"
|
||||
fi
|
||||
|
||||
# Method 2: Fallback to simctl if xcodebuild didn't work
|
||||
if [ -z "$SIMULATOR" ] || [ "$SIMULATOR" = "Shutdown" ] || [ "$SIMULATOR" = "Booted" ]; then
|
||||
# Use simctl list in JSON format for more reliable parsing
|
||||
# This avoids parsing status words like "Shutdown"
|
||||
SIMULATOR_JSON=$(xcrun simctl list devices available --json 2>/dev/null)
|
||||
|
||||
if [ -n "$SIMULATOR_JSON" ]; then
|
||||
# Extract first iPhone device name using jq if available, or grep/sed
|
||||
if command -v jq &> /dev/null; then
|
||||
SIMULATOR=$(echo "$SIMULATOR_JSON" | \
|
||||
jq -r '.devices | to_entries[] | .value[] | select(.name | test("iPhone"; "i")) | .name' | \
|
||||
grep -v "iPhone Air" | \
|
||||
head -1)
|
||||
else
|
||||
# Fallback: parse text output more carefully
|
||||
# Get line with iPhone, extract name before first parenthesis
|
||||
SIMULATOR_LINE=$(xcrun simctl list devices available 2>/dev/null | \
|
||||
grep -E "iPhone [0-9]" | \
|
||||
grep -v "iPhone Air" | \
|
||||
head -1)
|
||||
|
||||
if [ -n "$SIMULATOR_LINE" ]; then
|
||||
# Extract device name - everything before first "("
|
||||
SIMULATOR=$(echo "$SIMULATOR_LINE" | \
|
||||
sed -E 's/^[[:space:]]*([^(]+).*/\1/' | \
|
||||
sed 's/[[:space:]]*$//')
|
||||
fi
|
||||
fi
|
||||
|
||||
# Validate it's not a status word
|
||||
if [ "$SIMULATOR" = "Shutdown" ] || [ "$SIMULATOR" = "Booted" ] || [ "$SIMULATOR" = "Creating" ] || [ -z "$SIMULATOR" ]; then
|
||||
SIMULATOR=""
|
||||
else
|
||||
log_info "Found simulator via simctl: $SIMULATOR"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Method 3: Try to find iPhone 17 Pro specifically (preferred)
|
||||
if [ -z "$SIMULATOR" ] || [ "$SIMULATOR" = "Shutdown" ] || [ "$SIMULATOR" = "Booted" ]; then
|
||||
PRO_LINE=$(xcrun simctl list devices available 2>/dev/null | \
|
||||
grep -i "iPhone 17 Pro" | \
|
||||
head -1)
|
||||
|
||||
if [ -n "$PRO_LINE" ]; then
|
||||
PRO_SIM=$(echo "$PRO_LINE" | \
|
||||
awk -F'(' '{print $1}' | \
|
||||
sed 's/^[[:space:]]*//' | \
|
||||
sed 's/[[:space:]]*$//')
|
||||
|
||||
if [ -n "$PRO_SIM" ] && [ "$PRO_SIM" != "Shutdown" ] && [ "$PRO_SIM" != "Booted" ] && [ "$PRO_SIM" != "Creating" ]; then
|
||||
SIMULATOR="$PRO_SIM"
|
||||
log_info "Using preferred simulator: $SIMULATOR"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Final fallback to known good simulator
|
||||
if [ -z "$SIMULATOR" ] || [ "$SIMULATOR" = "Shutdown" ] || [ "$SIMULATOR" = "Booted" ] || [ "$SIMULATOR" = "Creating" ]; then
|
||||
# Try common simulator names that are likely to exist
|
||||
for DEFAULT_SIM in "iPhone 17 Pro" "iPhone 17" "iPhone 16" "iPhone 15 Pro" "iPhone 15"; do
|
||||
if xcrun simctl list devices available 2>/dev/null | grep -q "$DEFAULT_SIM"; then
|
||||
SIMULATOR="$DEFAULT_SIM"
|
||||
log_info "Using fallback simulator: $SIMULATOR"
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
# If still empty, use iPhone 17 Pro as final default
|
||||
if [ -z "$SIMULATOR" ] || [ "$SIMULATOR" = "Shutdown" ] || [ "$SIMULATOR" = "Booted" ]; then
|
||||
log_warn "Could not determine simulator. Using default: iPhone 17 Pro"
|
||||
SIMULATOR="iPhone 17 Pro"
|
||||
fi
|
||||
fi
|
||||
|
||||
log_info "Selected simulator: $SIMULATOR"
|
||||
|
||||
# Extract device ID for more reliable targeting
|
||||
# Format: " iPhone 17 Pro (68D19D08-4701-422C-AF61-2E21ACA1DD4C) (Shutdown)"
|
||||
SIMULATOR_ID=$(xcrun simctl list devices available 2>/dev/null | \
|
||||
grep -i "$SIMULATOR" | \
|
||||
head -1 | \
|
||||
sed -n 's/.*(\([A-F0-9-]\{36\}\)).*/\1/p')
|
||||
|
||||
# Verify simulator exists before building
|
||||
if [ -z "$SIMULATOR_ID" ] && ! xcrun simctl list devices available 2>/dev/null | grep -q "$SIMULATOR"; then
|
||||
log_warn "Simulator '$SIMULATOR' not found in available devices"
|
||||
log_info "Available iPhone simulators:"
|
||||
xcrun simctl list devices available 2>/dev/null | grep -i "iphone" | grep -v "iPhone Air" | head -5
|
||||
log_warn "Attempting build anyway with: $SIMULATOR"
|
||||
fi
|
||||
|
||||
# Build iOS app
|
||||
log_step "Building iOS app for simulator..."
|
||||
|
||||
# Use device ID if available, otherwise use name
|
||||
if [ -n "$SIMULATOR_ID" ]; then
|
||||
DESTINATION="platform=iOS Simulator,id=$SIMULATOR_ID"
|
||||
log_info "Using simulator ID: $SIMULATOR_ID ($SIMULATOR)"
|
||||
else
|
||||
DESTINATION="platform=iOS Simulator,name=$SIMULATOR"
|
||||
log_info "Using simulator name: $SIMULATOR"
|
||||
fi
|
||||
|
||||
if xcodebuild -workspace "$WORKSPACE" \
|
||||
-scheme App \
|
||||
-configuration Debug \
|
||||
-sdk iphonesimulator \
|
||||
-destination "$DESTINATION" \
|
||||
build; then
|
||||
log_info "iOS app built successfully"
|
||||
|
||||
# Find built app
|
||||
DERIVED_DATA="$HOME/Library/Developer/Xcode/DerivedData"
|
||||
APP_PATH=$(find "$DERIVED_DATA" -name "App.app" -path "*/Build/Products/Debug-iphonesimulator/*" -type d 2>/dev/null | head -1)
|
||||
|
||||
if [ -n "$APP_PATH" ]; then
|
||||
log_info "App built at: $APP_PATH"
|
||||
|
||||
# Run on simulator if requested
|
||||
if [ "$RUN_ALL" = true ] || [ "$RUN_IOS" = true ]; then
|
||||
log_step "Installing and launching iOS app on simulator..."
|
||||
|
||||
# Use the device ID we already extracted, or get it again
|
||||
if [ -z "$SIMULATOR_ID" ]; then
|
||||
SIMULATOR_ID=$(xcrun simctl list devices available 2>/dev/null | \
|
||||
grep -i "$SIMULATOR" | \
|
||||
head -1 | \
|
||||
sed -n 's/.*(\([A-F0-9-]\{36\}\)).*/\1/p')
|
||||
fi
|
||||
|
||||
# If we have device ID, use it; otherwise try to boot by name
|
||||
if [ -n "$SIMULATOR_ID" ]; then
|
||||
SIMULATOR_UDID="$SIMULATOR_ID"
|
||||
log_info "Using simulator ID: $SIMULATOR_UDID"
|
||||
else
|
||||
# Try to boot simulator by name and get its ID
|
||||
log_step "Booting simulator: $SIMULATOR..."
|
||||
xcrun simctl boot "$SIMULATOR" 2>/dev/null || true
|
||||
sleep 2
|
||||
SIMULATOR_UDID=$(xcrun simctl list devices 2>/dev/null | \
|
||||
grep -i "$SIMULATOR" | \
|
||||
grep -E "\([A-F0-9-]{36}\)" | \
|
||||
head -1 | \
|
||||
sed -n 's/.*(\([A-F0-9-]\{36\}\)).*/\1/p')
|
||||
fi
|
||||
|
||||
if [ -n "$SIMULATOR_UDID" ]; then
|
||||
# Install app
|
||||
if xcrun simctl install "$SIMULATOR_UDID" "$APP_PATH"; then
|
||||
log_info "App installed on simulator"
|
||||
|
||||
# Launch app
|
||||
APP_BUNDLE_ID="com.timesafari.dailynotification.test"
|
||||
if xcrun simctl launch "$SIMULATOR_UDID" "$APP_BUNDLE_ID"; then
|
||||
log_info "✅ iOS app launched successfully!"
|
||||
else
|
||||
log_warn "Failed to launch app (may already be running)"
|
||||
fi
|
||||
else
|
||||
log_warn "App installation failed (may already be installed)"
|
||||
fi
|
||||
else
|
||||
log_warn "Could not find or boot simulator"
|
||||
log_info "Open Xcode and run manually: open $WORKSPACE"
|
||||
fi
|
||||
fi
|
||||
else
|
||||
log_warn "Could not find built app in DerivedData"
|
||||
log_info "Build succeeded. Open Xcode to run: open $WORKSPACE"
|
||||
fi
|
||||
else
|
||||
log_error "iOS build failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
cd "$PROJECT_DIR"
|
||||
fi
|
||||
fi
|
||||
|
||||
log_info ""
|
||||
log_info "✅ Build process complete!"
|
||||
log_info ""
|
||||
|
||||
# Summary
|
||||
if [ "$BUILD_ANDROID" = true ] || [ "$BUILD_ALL" = true ]; then
|
||||
if [ -f "$PROJECT_DIR/android/app/build/outputs/apk/debug/app-debug.apk" ]; then
|
||||
log_info "Android APK: $PROJECT_DIR/android/app/build/outputs/apk/debug/app-debug.apk"
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$BUILD_IOS" = true ] || [ "$BUILD_ALL" = true ]; then
|
||||
if [ -d "$IOS_DIR/App.xcworkspace" ]; then
|
||||
log_info "iOS Workspace: $IOS_DIR/App.xcworkspace"
|
||||
log_info "Open with: open $IOS_DIR/App.xcworkspace"
|
||||
fi
|
||||
fi
|
||||
|
||||
@@ -22,6 +22,7 @@ const __dirname = path.dirname(__filename);
|
||||
|
||||
const PLUGINS_JSON_PATH = path.join(__dirname, '../android/app/src/main/assets/capacitor.plugins.json');
|
||||
const SETTINGS_GRADLE_PATH = path.join(__dirname, '../android/capacitor.settings.gradle');
|
||||
const PODFILE_PATH = path.join(__dirname, '../ios/App/Podfile');
|
||||
|
||||
const PLUGIN_ENTRY = {
|
||||
name: "DailyNotification",
|
||||
@@ -103,6 +104,98 @@ ${correctPath}`
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Fix iOS Podfile to use correct plugin pod name and path
|
||||
*/
|
||||
function fixPodfile() {
|
||||
console.log('🔧 Verifying iOS Podfile...');
|
||||
|
||||
if (!fs.existsSync(PODFILE_PATH)) {
|
||||
console.log('ℹ️ Podfile not found (iOS platform may not be added yet)');
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
let content = fs.readFileSync(PODFILE_PATH, 'utf8');
|
||||
const originalContent = content;
|
||||
|
||||
// The correct pod reference should be:
|
||||
// pod 'DailyNotificationPlugin', :path => '../../node_modules/@timesafari/daily-notification-plugin/ios'
|
||||
const correctPodLine = "pod 'DailyNotificationPlugin', :path => '../../node_modules/@timesafari/daily-notification-plugin/ios'";
|
||||
|
||||
// Check if Podfile already has the correct reference
|
||||
if (content.includes("pod 'DailyNotificationPlugin'")) {
|
||||
// Check if path is correct
|
||||
if (content.includes('@timesafari/daily-notification-plugin/ios')) {
|
||||
console.log('✅ Podfile has correct DailyNotificationPlugin reference');
|
||||
} else {
|
||||
// Fix the path
|
||||
console.log('⚠️ Podfile has DailyNotificationPlugin but wrong path - fixing...');
|
||||
content = content.replace(
|
||||
/pod ['"]DailyNotificationPlugin['"].*:path.*/,
|
||||
correctPodLine
|
||||
);
|
||||
|
||||
// Also fix if it's using the wrong name (TimesafariDailyNotificationPlugin)
|
||||
content = content.replace(
|
||||
/pod ['"]TimesafariDailyNotificationPlugin['"].*:path.*/,
|
||||
correctPodLine
|
||||
);
|
||||
|
||||
if (content !== originalContent) {
|
||||
fs.writeFileSync(PODFILE_PATH, content);
|
||||
console.log('✅ Fixed DailyNotificationPlugin path in Podfile');
|
||||
}
|
||||
}
|
||||
} else if (content.includes("TimesafariDailyNotificationPlugin")) {
|
||||
// Fix wrong pod name
|
||||
console.log('⚠️ Podfile uses wrong pod name (TimesafariDailyNotificationPlugin) - fixing...');
|
||||
content = content.replace(
|
||||
/pod ['"]TimesafariDailyNotificationPlugin['"].*:path.*/,
|
||||
correctPodLine
|
||||
);
|
||||
|
||||
if (content !== originalContent) {
|
||||
fs.writeFileSync(PODFILE_PATH, content);
|
||||
console.log('✅ Fixed pod name in Podfile (TimesafariDailyNotificationPlugin -> DailyNotificationPlugin)');
|
||||
}
|
||||
} else {
|
||||
// Add the pod reference if it's missing
|
||||
console.log('⚠️ Podfile missing DailyNotificationPlugin - adding...');
|
||||
|
||||
// Find the capacitor_pods function or target section
|
||||
if (content.includes('def capacitor_pods')) {
|
||||
// Add after capacitor_pods function
|
||||
content = content.replace(
|
||||
/(def capacitor_pods[\s\S]*?end)/,
|
||||
`$1\n\n # Daily Notification Plugin\n ${correctPodLine}`
|
||||
);
|
||||
} else if (content.includes("target 'App'")) {
|
||||
// Add in target section
|
||||
content = content.replace(
|
||||
/(target 'App' do)/,
|
||||
`$1\n ${correctPodLine}`
|
||||
);
|
||||
} else {
|
||||
// Add at end before post_install
|
||||
content = content.replace(
|
||||
/(post_install)/,
|
||||
`${correctPodLine}\n\n$1`
|
||||
);
|
||||
}
|
||||
|
||||
if (content !== originalContent) {
|
||||
fs.writeFileSync(PODFILE_PATH, content);
|
||||
console.log('✅ Added DailyNotificationPlugin to Podfile');
|
||||
}
|
||||
}
|
||||
|
||||
} catch (error) {
|
||||
console.error('❌ Error fixing Podfile:', error.message);
|
||||
// Don't exit - iOS might not be set up yet
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Run all fixes
|
||||
*/
|
||||
@@ -112,9 +205,10 @@ function fixAll() {
|
||||
|
||||
fixCapacitorPlugins();
|
||||
fixCapacitorSettingsGradle();
|
||||
fixPodfile();
|
||||
|
||||
console.log('\n✅ All fixes applied successfully!');
|
||||
console.log('💡 These fixes will persist until the next "npx cap sync android"');
|
||||
console.log('💡 These fixes will persist until the next "npx cap sync"');
|
||||
}
|
||||
|
||||
// Run if called directly
|
||||
@@ -122,4 +216,4 @@ if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
fixAll();
|
||||
}
|
||||
|
||||
export { fixCapacitorPlugins, fixCapacitorSettingsGradle, fixAll };
|
||||
export { fixCapacitorPlugins, fixCapacitorSettingsGradle, fixPodfile, fixAll };
|
||||
|
||||
@@ -72,15 +72,20 @@ export class TypedDailyNotificationPlugin implements DailyNotificationBridge {
|
||||
|
||||
/**
|
||||
* Check permissions with validation
|
||||
* Uses checkPermissionStatus() which is the correct method name for iOS
|
||||
*/
|
||||
async checkPermissions(): Promise<PermissionStatus> {
|
||||
try {
|
||||
const result = await (this.plugin as { checkPermissions: () => Promise<PermissionStatus> }).checkPermissions()
|
||||
// Use checkPermissionStatus() which is implemented on both iOS and Android
|
||||
const result = await (this.plugin as { checkPermissionStatus: () => Promise<any> }).checkPermissionStatus()
|
||||
|
||||
// Ensure response has required fields
|
||||
// Map PermissionStatusResult to PermissionStatus format
|
||||
return {
|
||||
notifications: result.notifications || 'denied',
|
||||
notificationsEnabled: Boolean(result.notificationsEnabled)
|
||||
notifications: result.notificationsEnabled ? 'granted' : 'denied',
|
||||
notificationsEnabled: Boolean(result.notificationsEnabled),
|
||||
exactAlarmEnabled: Boolean(result.exactAlarmEnabled),
|
||||
wakeLockEnabled: Boolean(result.wakeLockEnabled),
|
||||
allPermissionsGranted: Boolean(result.allPermissionsGranted)
|
||||
}
|
||||
|
||||
} catch (error) {
|
||||
@@ -166,6 +171,26 @@ export class TypedDailyNotificationPlugin implements DailyNotificationBridge {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Request notification permissions (iOS method name)
|
||||
* This is an alias for requestPermissions() for iOS compatibility
|
||||
*/
|
||||
async requestNotificationPermissions(): Promise<void> {
|
||||
try {
|
||||
// Try requestNotificationPermissions first (iOS), fallback to requestPermissions
|
||||
if (typeof (this.plugin as any).requestNotificationPermissions === 'function') {
|
||||
await (this.plugin as { requestNotificationPermissions: () => Promise<void> }).requestNotificationPermissions()
|
||||
} else if (typeof (this.plugin as any).requestPermissions === 'function') {
|
||||
await (this.plugin as { requestPermissions: () => Promise<PermissionStatus> }).requestPermissions()
|
||||
} else {
|
||||
throw new Error('Neither requestNotificationPermissions nor requestPermissions is available')
|
||||
}
|
||||
} catch (error) {
|
||||
logError(error, 'requestNotificationPermissions')
|
||||
throw error
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Open exact alarm settings
|
||||
*/
|
||||
|
||||
@@ -47,6 +47,13 @@
|
||||
@click="checkSystemStatus"
|
||||
:loading="isCheckingStatus"
|
||||
/>
|
||||
<ActionCard
|
||||
icon="🔐"
|
||||
title="Request Permissions"
|
||||
description="Check and request notification permissions"
|
||||
@click="checkAndRequestPermissions"
|
||||
:loading="isRequestingPermissions"
|
||||
/>
|
||||
<ActionCard
|
||||
icon="🔔"
|
||||
title="View Notifications"
|
||||
@@ -218,7 +225,8 @@ const checkSystemStatus = async (): Promise<void> => {
|
||||
console.log('✅ Plugin available, checking status...')
|
||||
try {
|
||||
const status = await plugin.getNotificationStatus()
|
||||
const permissions = await plugin.checkPermissions()
|
||||
// Use checkPermissionStatus() which is the correct method name for iOS
|
||||
const permissions = await plugin.checkPermissionStatus()
|
||||
const exactAlarmStatus = await plugin.getExactAlarmStatus()
|
||||
|
||||
console.log('📊 Plugin status object:', status)
|
||||
@@ -232,17 +240,17 @@ const checkSystemStatus = async (): Promise<void> => {
|
||||
|
||||
console.log('📊 Plugin permissions:', permissions)
|
||||
console.log('📊 Permissions details:')
|
||||
console.log(' - notifications:', permissions.notifications)
|
||||
console.log(' - notificationsEnabled:', (permissions as unknown as Record<string, unknown>).notificationsEnabled)
|
||||
console.log(' - exactAlarmEnabled:', (permissions as unknown as Record<string, unknown>).exactAlarmEnabled)
|
||||
console.log(' - wakeLockEnabled:', (permissions as unknown as Record<string, unknown>).wakeLockEnabled)
|
||||
console.log(' - allPermissionsGranted:', (permissions as unknown as Record<string, unknown>).allPermissionsGranted)
|
||||
console.log(' - notificationsEnabled:', permissions.notificationsEnabled)
|
||||
console.log(' - exactAlarmEnabled:', permissions.exactAlarmEnabled)
|
||||
console.log(' - wakeLockEnabled:', permissions.wakeLockEnabled)
|
||||
console.log(' - allPermissionsGranted:', permissions.allPermissionsGranted)
|
||||
console.log('📊 Exact alarm status:', exactAlarmStatus)
|
||||
|
||||
// Map plugin response to app store format
|
||||
// checkPermissionStatus() returns PermissionStatusResult with boolean flags
|
||||
const mappedStatus = {
|
||||
canScheduleNow: status.isEnabled ?? false,
|
||||
postNotificationsGranted: permissions.notifications === 'granted',
|
||||
postNotificationsGranted: permissions.notificationsEnabled ?? false,
|
||||
channelEnabled: true, // Default for now
|
||||
channelImportance: 3, // Default for now
|
||||
channelId: 'daily-notifications',
|
||||
@@ -351,6 +359,80 @@ const refreshSystemStatus = async (): Promise<void> => {
|
||||
await checkSystemStatus()
|
||||
}
|
||||
|
||||
/**
|
||||
* Check permissions and request if needed (Android pattern)
|
||||
* 1. Check permission status first
|
||||
* 2. If not granted, show system dialog
|
||||
* 3. Refresh status after request
|
||||
*/
|
||||
const checkAndRequestPermissions = async (): Promise<void> => {
|
||||
console.log('🔐 CLICK: Check and Request Permissions')
|
||||
|
||||
if (isRequestingPermissions.value) {
|
||||
console.log('⏳ Permission request already in progress')
|
||||
return
|
||||
}
|
||||
|
||||
isRequestingPermissions.value = true
|
||||
|
||||
try {
|
||||
const { DailyNotification } = await import('@timesafari/daily-notification-plugin')
|
||||
const plugin = DailyNotification
|
||||
|
||||
if (!plugin) {
|
||||
console.error('❌ DailyNotification plugin not available')
|
||||
return
|
||||
}
|
||||
|
||||
// Step 1: Check permission status first (Android pattern)
|
||||
console.log('🔍 Step 1: Checking current permission status...')
|
||||
const permissionStatus = await plugin.checkPermissionStatus()
|
||||
|
||||
console.log('📊 Permission status:', {
|
||||
notificationsEnabled: permissionStatus.notificationsEnabled,
|
||||
exactAlarmEnabled: permissionStatus.exactAlarmEnabled,
|
||||
allPermissionsGranted: permissionStatus.allPermissionsGranted
|
||||
})
|
||||
|
||||
// Step 2: If not granted, show system dialog
|
||||
if (!permissionStatus.notificationsEnabled) {
|
||||
console.log('⚠️ Permissions not granted - showing system dialog...')
|
||||
console.log('📱 iOS will show native permission dialog now...')
|
||||
|
||||
// Request permissions - this will show the iOS system dialog
|
||||
// Try requestNotificationPermissions first (iOS), fallback to requestPermissions
|
||||
if (typeof (plugin as any).requestNotificationPermissions === 'function') {
|
||||
await (plugin as { requestNotificationPermissions: () => Promise<void> }).requestNotificationPermissions()
|
||||
} else if (typeof (plugin as any).requestPermissions === 'function') {
|
||||
await (plugin as { requestPermissions: () => Promise<any> }).requestPermissions()
|
||||
} else {
|
||||
throw new Error('Permission request method not available')
|
||||
}
|
||||
|
||||
console.log('✅ Permission request completed')
|
||||
|
||||
// Step 3: Refresh status after request
|
||||
console.log('🔄 Refreshing status after permission request...')
|
||||
await new Promise(resolve => setTimeout(resolve, 1000)) // Wait 1 second for system to update
|
||||
await checkSystemStatus()
|
||||
} else {
|
||||
console.log('✅ Permissions already granted - no dialog needed')
|
||||
// Still refresh status to show current state
|
||||
await checkSystemStatus()
|
||||
}
|
||||
|
||||
} catch (error) {
|
||||
console.error('❌ Permission check/request failed:', error)
|
||||
console.error('❌ Error details:', {
|
||||
name: (error as Error).name,
|
||||
message: (error as Error).message,
|
||||
stack: (error as Error).stack
|
||||
})
|
||||
} finally {
|
||||
isRequestingPermissions.value = false
|
||||
}
|
||||
}
|
||||
|
||||
const runPluginDiagnostics = async (): Promise<void> => {
|
||||
console.log('🔄 CLICK: Plugin Diagnostics - METHOD CALLED!')
|
||||
console.log('🔄 FUNCTION START: runPluginDiagnostics called at', new Date().toISOString())
|
||||
|
||||
@@ -92,7 +92,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterD
|
||||
// Test if class can be cast to CapacitorPlugin.Type
|
||||
if let pluginType = aClass as? CAPPlugin.Type {
|
||||
// Try casting to CapacitorPlugin (which is CAPPlugin & CAPBridgedPlugin)
|
||||
if let capacitorPluginType = pluginType as? (CAPPlugin & CAPBridgedPlugin).Type {
|
||||
if pluginType is (CAPPlugin & CAPBridgedPlugin).Type {
|
||||
NSLog("DNP-DEBUG: ✅ Can cast to (CAPPlugin & CAPBridgedPlugin).Type")
|
||||
} else {
|
||||
NSLog("DNP-DEBUG: ❌ Cannot cast to (CAPPlugin & CAPBridgedPlugin).Type")
|
||||
|
||||
Reference in New Issue
Block a user