engage-sdk-integration

このスキルでは、Play Engage SDK を Android アプリに統合する手順を説明します。コードが必須の構造に従い、各バーティカルに必要な Engage エンティティを使用するようにします。

ワークフロー

開発者を支援するには、次の手順に従います。

1. バーティカルとクラスターを特定します。

   • アプリがどのバーティカルに属するか、references/schemas/ に基づいて開発者に尋ねます。
   • 統合対象が TV 向けかモバイル向けかを確認します。TV 向けの場合は、patterns.md の TV 固有のセクションも読みます。
   • references/schemas/ ディレクトリ内の {VERTICAL}.md を使用して、対応する Engage エンティティと client クラス名を特定します。JSON の client フィールドには完全修飾クラス名が記載されています。例：com.google.android.engage.food.service.AppEngageFoodClient。
   • 注： クライアントクラスの初期化には Context パラメーターが必要です。例：AppEngageFoodClient(context)。
   • 共通エンティティについては、必ず common.md を参照します。
   • そのバーティカルでサポートされているクラスタータイプのうち、どのタイプを公開したいか開発者に尋ねます。
   • 指定されたクラスターについて、references/schemas/ ディレクトリ内の {VERTICAL}.md から呼び出すメソッドを確認します。各メソッドには、必要なリクエストが記載されています。
   • requests.md からリクエストの構造を、clusters.md からクラスターを取得します。そのうえで、必要なエンティティとクラスターとともに、リクエストの各フィールドを正しく埋めるための情報源を提案し、使用します。

2. 構造化されたボイラープレートコードを生成します。

   • Engage 関連コードをすべて格納する新しいディレクトリを作成します。既存のコードベースの命名規則に合わせてディレクトリ名を付けます。
   • patterns.md のテンプレートを使用して、次のクラスを生成します。
     • Constants：試行回数や公開タイプなどの定数値を保持します。
     • ItemToEntityConverter：アプリのローカルモデルを Engage の Entity モデルに変換します。
     • ClusterRequestFactory：公開リクエストを構築します。
     • EngageWorker：WorkManager を使用して、実際の公開処理と公開エラーを処理します。
     • EngagePublisher：定期ジョブと単発ジョブを調整します。
     • EngageBroadcastReceiver：AppEngageService インテントを監視し、EngagePublisher から単発の公開ジョブを開始します。重要：EngageBroadcastReceiver クラス内にコンパニオンオブジェクトの register メソッドを含め、静的登録と動的登録の両方のパターンを実装します。

3. エンティティのマッピングを提案します。

   • 開発者に、ローカルモデルのスキーマ（データクラスや JSON スニペットなど）を提示してもらいます。
   • 提示されていない場合は、ガイドとして references/schemas/ ディレクトリ内の {VERTICAL}.md にあるエンティティを共有します。
   • ローカルモデルを特定したら、対応する Engage エンティティへのマッピングを提案します。
   • patterns.md の ItemToEntityConverter パターンを使用して変換ロジックを生成し、生成した {ENGAGE_CODE_DIR}/ItemToEntityConverter に追加します。

4. データソースを提案します。

   • 公開する実データのソースを開発者に提示してもらいます。
   • データソースを特定したら、それを使用してアプリのローカルモデルスキーマに沿ったデータを取得します。
   • {ENGAGE_CODE_DIR}/ItemToEntityConverter を使用して、このデータを Engage エンティティに変換します。
   • 取得した Engage エンティティモデルのデータを {ENGAGE_CODE_DIR}/ ClusterRequestFactory で使用して、クラスターリクエストを取得します。
   • 前の手順で取得したリクエストを使い、references/schemas/ ディレクトリ内の {VERTICAL}.md で確認した対応するクラスター公開メソッドを {ENGAGE_CODE_DIR}/EngageWorker 内で呼び出します。

5. Gradle とマニフェストを更新します。

   • build.gradle と AndroidManifest.xml への更新を提案します。
   • モバイルアプリの場合は、patterns.md を使用してください。
   • TV アプリの場合は、patterns.md 内の TV 固有のセクションを使用してください。
   • patterns.md から、build.gradle または build.gradle.kts に必要な implementation 依存関係を提供します。
   • AndroidManifest.xml に <receiver> および <service> の宣言を提供します。
   • 注: TV を除き、業種固有のインポートはありません。その他のすべての業種では、com.google.android.engage:engage-core:1.6.0 で十分です。

6. デバッグと検証:

   • 自己検証チェックリスト: 作業が完了したと見なす前に、以下をすべて実装したことを検証する必要があります:
     • [ ] AndroidManifest.xml 内で（<application> タグ内に）EngageBroadcastReceiver を静的に登録した。
     • [ ] Application クラスまたはメインの Activity クラスで EngageBroadcastReceiver.register(context) を呼び出すことにより、EngageBroadcastReceiver を動的に登録した。
     • [ ] 動的登録を処理するために、EngageBroadcastReceiver の companion object に register メソッドを実装した。
     • [ ] EngageWorker で空のデータリストを処理した（たとえば、空のデータを公開する代わりにクラスターを削除するなど）。
     • [ ] すべての Gradle コンパイルで --no-daemon を使用した。
   • Gradle 同期を実行します。
   • エラーが発生した場合（インポートの失敗、名前空間の競合、コンパイルエラーなど）は、references/troubleshooting.md を読んで解決してください。
   • Gradle コンパイルを実行します。./gradlew compileDebugUnitTestSources --no-daemon または ./gradlew assembleDebug --no-daemon を実行する必要があります。コンパイルのルールと高速コンパイルのショートカットに関する警告については、references/troubleshooting.md を参照してください。コンパイルが成功するまで、このステップを繰り返してください。

7. ユーザーチェックリスト: コード生成の最後に、統合が完了し意図どおりであることを確認するために、このチェックリストを確認するようユーザーに通知します:

   • [ ] すべての Engage 関連ファイルが {ENGAGE_CODE_DIR}/ に作成されていることを確認する:
     • Constants
     • ItemToEntityConverter
     • ClusterRequestFactory
     • EngageWorker
     • {cluster_type}Publisher
     • EngageBroadcastReceiver
   • [ ] {ENGAGE_CODE_DIR}/ItemToEntityConverter 内のモデルのフィールドを正しく設定することにより、アプリのローカルモデルが Engage エンティティに変換されることを確認する。
   • [ ] ItemToEntityConverter 内のすべての画像 URI が、業種の厳格なアスペクト比要件（たとえば、16:9、1:1、2:3）に一致する画像を指していることを確認する。
   • [ ] {ENGAGE_CODE_DIR}/EngageWorker がステップ 4 で特定したデータソースを使用していることを確認する。
   • [ ] レシーバーを動的に登録するために、EngageBroadcastReceiver.register(context) が Application クラスまたは MainActivity 内で呼び出されていることを確認する。
   • [ ] AndroidManifest.xml に、必要な intent アクションを伴う EngageBroadcastReceiver の静的な <receiver> 宣言が含まれていることを確認する。
   • 重要: レシーバーを動的に登録するために、開発者独自の Application クラスの onCreate()（またはメインアクティビティの onCreate()）内で EngageBroadcastReceiver.register(context) を呼び出すよう明示的に指示してください。統合が機能するには、静的登録と動的登録の両方が必要であることを強調してください。

参考資料

• FAQ： Engage FAQ - 開発者からよく寄せられる質問への回答については、このドキュメントを参照してください。

• 分野別ガイド：

  • Food 分野
  • Watch 分野
  • Listen 分野
  • Read 分野
  • Shopping 分野
  • Social 分野
  • Travel 分野
  • Health and Fitness 分野
  • その他の分野
  • TV の利用開始
  • TV のおすすめ
  • TV の視聴を続ける
  • TV の利用権

• 分野別スキーマ：

  • Food スキーマ
  • Watch スキーマ
  • Listen スキーマ
  • Read スキーマ
  • Shopping スキーマ
  • Social スキーマ
  • Travel スキーマ
  • TV スキーマ
  • その他のスキーマ