Flutterアプリのライフサイクルでつまずきやすいポイント

アプリがバックグラウンドに入ったら一時保存する
アプリに戻ってきたらデータを再取得する
画面復帰時にログイン状態を確認する
通知から戻ってきたときに特定画面を開く
位置情報やタイマーを一時停止・再開する

disposeが呼ばれると思っていた
バックグラウンドに入ったら必ずpausedになると思っていた
resumedで毎回APIを叩いたら二重実行された
通知や権限ダイアログでもライフサイクルが変わって混乱した

detached
resumed
inactive
hidden
paused

Widgetのライフサイクル:
initState
build
didUpdateWidget
dispose

アプリのライフサイクル:
resumed
inactive
hidden
paused
detached

resumed → paused
paused → resumed

resumed
↓
inactive
↓
hidden
↓
paused

OSがアプリを強制終了した
端末のメモリ不足でプロセスが落ちた
ユーザーがアプリをスワイプ終了した
クラッシュした
電源が切れた
デバッグ環境と実機で挙動が違う

同じAPIが何度も呼ばれる
画面復帰のたびにローディングが出る
権限ダイアログから戻っただけで再取得される
通知から戻ったときに複数回処理される
通信中に再度同じ通信が走る

bool _isRefreshing = false;
DateTime? _lastRefreshAt;

Future<void> refreshOnResume() async {
  if (_isRefreshing) return;

  final now = DateTime.now();
  if (_lastRefreshAt != null &&
      now.difference(_lastRefreshAt!) < const Duration(seconds: 30)) {
    return;
  }

  _isRefreshing = true;

  try {
    // API再取得など
    _lastRefreshAt = now;
  } finally {
    _isRefreshing = false;
  }
}

位置情報権限を求める
↓
アプリがinactiveになる
↓
ユーザーが許可・拒否する
↓
resumedになる
↓
意図せず復帰処理が走る

権限確認処理が二重に走る
API再取得が不要に走る
画面遷移が勝手に発生する
ダイアログが連続表示される

bool _requestingPermission = false;

Future<void> requestPermission() async {
  _requestingPermission = true;

  try {
    // 権限リクエスト処理
  } finally {
    _requestingPermission = false;
  }
}

void handleResumed() {
  if (_requestingPermission) {
    return;
  }

  // 通常の復帰処理
}

ホーム画面からアプリに戻った
アプリ切り替えで戻った
権限ダイアログから戻った
電話やシステムUIから戻った
通知をタップして戻った

class _HomePageState extends State<HomePage> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.resumed:
        // アプリが前面に戻ったとき
        break;
      case AppLifecycleState.inactive:
        // 一時的に非アクティブ
        break;
      case AppLifecycleState.hidden:
        // 画面が見えない状態
        break;
      case AppLifecycleState.paused:
        // バックグラウンド
        break;
      case AppLifecycleState.detached:
        // ビューから切り離された状態
        break;
    }
  }
}

class _HomePageState extends State<HomePage> {
  late final AppLifecycleListener _listener;

  @override
  void initState() {
    super.initState();

    _listener = AppLifecycleListener(
      onStateChange: (state) {
        switch (state) {
          case AppLifecycleState.resumed:
            // 復帰時の処理
            break;
          case AppLifecycleState.paused:
            // バックグラウンド移行時の処理
            break;
          case AppLifecycleState.inactive:
          case AppLifecycleState.hidden:
          case AppLifecycleState.detached:
            break;
        }
      },
    );
  }

  @override
  void dispose() {
    _listener.dispose();
    super.dispose();
  }
}

大量データのアップロード
長いAPI通信
大きなファイル保存
複雑なDB更新
位置情報の長時間取得

入力のたびに小さく保存する
画面遷移時に保存する
アプリ復帰時に未同期データを再送する
バックグラウンド移行時は補助的な保存だけにする

バッテリー消費が増える
復帰時にタイマーがずれる
二重にタイマーが動く
不要なAPI通信が続く
アニメーション状態が壊れる

DateTime? _backgroundAt;

void onPaused() {
  _backgroundAt = DateTime.now();
}

void onResumed() {
  if (_backgroundAt == null) return;

  final elapsed = DateTime.now().difference(_backgroundAt!);
  // 経過時間をもとに状態を補正する
}

Androidではpausedになるタイミングが、iOSでは違って見える
iOSではinactiveを経由する場面がある
システムダイアログやアプリ切り替え時の挙動が違う
端末やOSバージョンで通知タイミングが変わる

通知
位置情報
バックグラウンド処理
権限ダイアログ
アプリ復帰時の再取得
タイマー
音声再生

初回起動:
初期化
ログイン状態確認
設定読み込み
必要ならチュートリアル表示

復帰時:
データ再取得
権限状態の再確認
画面状態の補正
通知・位置情報状態の確認

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  late final AppLifecycleListener _lifecycleListener;

  bool _isRefreshing = false;
  DateTime? _lastRefreshAt;

  @override
  void initState() {
    super.initState();

    _lifecycleListener = AppLifecycleListener(
      onStateChange: _onLifecycleChanged,
    );
  }

  void _onLifecycleChanged(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.resumed:
        _refreshIfNeeded();
        break;
      case AppLifecycleState.inactive:
      case AppLifecycleState.hidden:
      case AppLifecycleState.paused:
      case AppLifecycleState.detached:
        break;
    }
  }

  Future<void> _refreshIfNeeded() async {
    if (_isRefreshing) return;

    final now = DateTime.now();

    if (_lastRefreshAt != null &&
        now.difference(_lastRefreshAt!) < const Duration(seconds: 30)) {
      return;
    }

    _isRefreshing = true;

    try {
      // API再取得など
      await Future.delayed(const Duration(seconds: 1));
      _lastRefreshAt = now;
    } finally {
      _isRefreshing = false;
    }
  }

  @override
  void dispose() {
    _lifecycleListener.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(
        child: Text('Home'),
      ),
    );
  }
}

class LifecycleObserverPage extends StatefulWidget {
  const LifecycleObserverPage({super.key});

  @override
  State<LifecycleObserverPage> createState() => _LifecycleObserverPageState();
}

class _LifecycleObserverPageState extends State<LifecycleObserverPage>
    with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    debugPrint('Lifecycle state: $state');

    if (state == AppLifecycleState.resumed) {
      // 復帰時の処理
    }

    if (state == AppLifecycleState.paused) {
      // バックグラウンド移行時の処理
    }
  }

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(
        child: Text('Lifecycle Observer'),
      ),
    );
  }
}

アプリライフサイクルとWidgetライフサイクルを分けて考えているか
disposeにバックグラウンド保存処理を依存していないか
resumedで無条件にAPIを叩いていないか
短時間の二重実行を防いでいるか
inactive / hidden / paused を考慮しているか
hiddenのcaseをswitch文に含めているか
権限ダイアログ後のresumedを考慮しているか
通知タップ処理をライフサイクルだけで判断していないか
WidgetsBindingObserverを使う場合、removeObserverしているか
AppLifecycleListenerを使う場合、disposeしているか
iOS実機とAndroid実機の両方で確認しているか
重要な保存処理をライフサイクル通知だけに依存していないか

アプリのライフサイクルとWidgetのライフサイクルを混同する
pausedだけ見ればよいと思ってしまう
すべての通知を必ず受け取れると思ってしまう
resumedでAPIを二重実行してしまう
権限ダイアログや通知復帰を考慮していない
ObserverやListenerの解除を忘れる
iOSとAndroidで同じように動くと思ってしまう