ios-app-intents

iOS App Intents

概要

システムに公開するアクションとエンティティの範囲は、役立つ最小限に抑えます。まず、アプリの外で実際に使いたい動詞と対象から始め、必要に応じてメインアプリへ適切にディープリンクまたは引き継ぎできる、範囲を絞った App Intents レイヤーを実装します。

必要に応じて、次のリファレンスを参照してください。

• 最初に扱うインテントとエンティティの範囲を選ぶには、references/first-pass-checklist.md
• 具体的な例の形を確認し、応用するには、references/example-patterns.md
• 汎用的な App Intents のコードテンプレートには、references/code-templates.md
• ショートカット、Siri、Spotlight、ウィジェットなど、システムの各エントリポイントについて考えるには、references/system-surfaces.md

コアワークフロー

1) 画面ではなくアクションから始める

• アプリの UI の外で動作させる価値が最も高いアクションを1〜3個特定します。
• 作成、開く、検索、絞り込み、続行、確認、開始などの動詞を優先します。
• アプリのナビゲーションツリー全体をインテントとして再現しないでください。

2) エンティティの範囲を絞る

• システムが理解またはルーティングする必要のあるオブジェクトに限り、AppEntity 型を追加します。
• エンティティの構造は、アプリの永続化モデルよりも絞り込みます。
• 曖昧さの解消や候補の提示に本当に役立つ場合に限り、EntityQuery やその他のクエリ型を追加します。

3) アクションをその場で完了するか、アプリを開くか決める

• システムの画面から直接完了できるアクションには、アプリを開かないインテントを使います。
• 特定のアプリ内ワークフローにユーザーを誘導する場合は、openAppWhenRun またはアプリを開く形式のインテントを使います。
• メインシーン内でアプリが反応する必要がある場合は、その場しのぎのルーティングロジックをあちこちに追加するのではなく、明確なランタイム引き継ぎ経路を1つ設けます。
• 両方の動作に対応できる場合は、どちらか一方に妥協して統一するのではなく、インライン版とアプリを開く版の両方を提供することを検討します。

4) アクションを見つけやすくする

• 最初に提供する価値の高いインテントには、AppShortcutsProvider のエントリを追加します。
• ショートカット、Siri、Spotlight で意味が伝わるタイトル、フレーズ、シンボルを選びます。
• ショートカットのフレーズは、直接的でタスク指向のものにします。
• ウィジェットの設定やインテント駆動型のコントロールで同じパラメーターが必要な場合は、同じアクションモデルをウィジェットやコントロールでも再利用します。

5) ランタイム引き継ぎを検証する

• アプリをビルドし、インテントのターゲットが問題なくコンパイルされることを確認します。
• インテントの実行時に、アプリが期待する場所を開く、またはそこへルーティングされることを検証します。
• 現在公開されているアクション、それを支えるエンティティ、アプリが呼び出しを処理する方法をまとめます。

推奨される基本方針

• システム向けレイヤーには、専用のインテントターゲットまたはモジュールを優先します。
• インテント型は薄く保ち、ビジネスロジックはアプリのサービスやドメインモデルに置きます。
• アプリのエンティティは小さく、表示に適したものにします。
• タブ、モード、表示レベルなど、アプリ内で選択肢が固定されている場合は、完全なエンティティ型を使う前にAppEnumを使います。
• メインアプリのシーンまたはルートルーターに、予測可能なアプリインテントのルーティング窓口を1つ設けることを優先します。
• App Intents はショートカット機能だけでなく、システム統合の基盤として扱います。

アンチパターン

• 実際のユーザー価値がないまま、すべての画面やタブを個別のインテントとして公開する。
• モデルグラフ全体をAppEntity型で再現する。
• 明確なアプリのエントリ経路を設けず、グローバルな副作用にランタイム引き継ぎを隠す。
• 曖昧なフレーズや汎用的なタイトルで App Shortcuts を追加する。
• 最初の App Intents の実装を、小さく役立つリリースではなく、広範な分類プロジェクトとして扱う。

メモ

• 主な参考資料として、Apple のドキュメントを使用してください。
  • https://developer.apple.com/documentation/appintents/making-actions-and-content-discoverable-and-widely-available
  • https://developer.apple.com/documentation/appintents/creating-your-first-app-intent
  • https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences
• 上記のリンクに加え、App Intents API やプラットフォームの動作が変更されている可能性がある場合は、ウェブ検索を使って最新の Apple Developer ドキュメントを確認してください。
• 最初の実装では、アプリを開くインテントを 1 つ、アクションインテントを 1 つ、エンティティタイプを 1〜2 個、小規模な AppShortcutsProvider を用意するとよいでしょう。
• カバーする例として適しているのは、次のとおりです。
  • アプリ内の画面やエディターを開く
  • アプリを開かずに、軽量なアクションをインラインで実行する
  • タブやモードなど、固定列挙から選択する
  • EntityQuery を通じて 1 つ以上のエンティティを解決する
  • 同じエンティティの仕組みを使って、ウィジェットの設定やコントロールを実現する