android-navigation-deeplinks

Android ナビゲーションのディープリンク

使用する場面

• リクエストが次の内容に関する場合に、このスキルを使用します：Android ナビゲーショングラフ、Android アプリへのディープリンク、Compose Navigation のバックスタックの問題。
• 主な成果：Android アプリのナビゲーショングラフ、バックスタックの動作、アプリリンク、インテント、遷移先の所有権を扱います。
• 対象範囲が広がった場合の引き継ぎ先スキル：
• android-permissions-activity-results
• android-testing-ui

ワークフロー

1. ユーザーに見える操作の流れ、対象デバイスでの動作、重要な失敗状態を確認します。
2. フローを担う画面、アクティビティ、遷移先、状態ホルダーを特定します。
3. ローディング、成功、空、エラーを明示的に処理してフローを実装します。
4. ショーケースアプリで、アクセシビリティ、構成変更、バックスタックの動作を検証します。
5. 引き継ぎメモに記載された専門スキルに、データ、アーキテクチャ、リリースに関する懸念を引き継ぎます。

ガードレール

• ローディング、空、エラー、オフライン、権限拒否の状態を、第一級の UI 状態として扱います。
• 再利用可能な UI コンポーネント内に、ナビゲーションや権限に伴う副作用を隠さないでください。
• 手動のコールバックチェーンより、ライフサイクルを考慮した API を優先します。
• ディープリンク、インテント、権限プロンプトはテスト可能かつ観察可能な状態に保ちます。

アンチパターン

• プロダクトのフローでは、問題のない経路だけで十分だと考えること。
• リクエストコードやルート文字列を複数の場所にハードコードすること。
• リポジトリやネットワーク層から直接ナビゲーションを開始すること。
• 権限拒否や状態の破損に対する復旧 UI がないままフローをリリースすること。

修正例

ルートの所有権を一元化する

sealed interface OrbitRoute {
    data object Board : OrbitRoute
    data class Task(val taskId: String) : OrbitRoute
}

期待されるバックスタックの動作を維持する

navController.navigate(OrbitRoute.Task(taskId)) {
    launchSingleTop = true
    restoreState = true
}

ディープリンクの引数を一か所で解析する

val taskId = intent?.data?.getQueryParameter("taskId")
require(!taskId.isNullOrBlank()) { "Missing taskId deep-link argument" }

例

想定どおりの経路

• シナリオ：ディープリンクから Compose のショーケースをタスク詳細の遷移先に移動します。
• コマンド：cd examples/orbittasks-compose && ./gradlew :app:testDebugUnitTest

エッジケース

• シナリオ：XML アクティビティをリンクからコールドスタートしたとき、期待される Up と Back の動作を維持します。
• コマンド：cd examples/orbittasks-xml && ./gradlew :app:testDebugUnitTest

失敗からの復旧

• シナリオ：権限、状態、リリースに関するプロンプトで混乱が生じないようにします。
• コマンド：python3 scripts/eval_triggers.py --skill android-navigation-deeplinks

完了チェックリスト

• 実装経路が明確かつ最小限で、適切な Android のサーフェスに対応しています。
• 関連するサンプルコマンドとベンチマーク用プロンプトを実行または更新しています。
• リクエストが隣接するスキルの範囲にまたがる場合、そのスキルへの引き継ぎを文書化しています。
• 公式リファレンスで、選択したパターンと主な移行手順またはトラブルシューティング手順を網羅しています。

公式リファレンス

• https://developer.android.com/guide/navigation
• https://developer.android.com/guide/navigation/design
• https://developer.android.com/training/app-links
• https://developer.android.com/guide/components/intents-filters