In-App Promo SDK を使用してショートカットを提案する

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

アプリの機能を宣伝し、使いやすさを向上させるために、アシスタント ショートカットをユーザーに提案できます。アシスタント ショートカットとは、ユーザーの発話によりアプリ内の機能をトリガーできる簡潔なフレーズです。

アシスタント ショートカットはユーザーが手動で作成することもできますが、In-App Promo SDK を使用すると積極的な提案と実装が可能です。ショートカットを提案することで、ショートカットを設定する手間をかけずに、アプリ内のお気に入りのアクティビティに明確かつシンプルな経路でアクセスできるようにします。

たとえば、ユーザーが音楽アプリで「ヘビーメタル ワークアウト」を検索した場合、その後、そうした検索結果へのアシスタント ショートカットを直接提案します。ショートカットを提案すると、ショートカットの候補フレーズを表示し、ショートカットを作成する必要があるかどうかをユーザーに尋ねるプロンプトがアプリに表示されます。この例では、「ヘビーメタル ワークアウトを始めて」というフレーズを提案します。ユーザーが提案を承認すると、「OK Google, ヘビーメタル ワークアウトを始めて」と話しかけてショートカットを開始できるようになります。

アプリのユーザーを増やす方法について詳しくは、App Actions でアプリを拡張するをご覧ください。

In-App Promo SDK には以下のメソッドがあります。

  • lookupShortcut は、提案するショートカットがすでに存在するかどうかを確認します。このメソッドでは、ショートカットの作成を妨げる問題があるかどうかも確認されます。ショートカットを作成できない場合、LookupShortcut は理由を返します。

  • createShortcutSuggestionIntent は、ショートカットの候補を作成するようユーザーに促すために使用できるインテントを返します。

  • createShortcutSettingsIntent は、ユーザーをアプリのアシスタント ショートカット設定に移動するために使用できるインテントを返します。

前提条件と制限事項

このセクションでは、提案を使用するための前提条件と要件、および発生する可能性がある制限事項について説明します。

開発の前提条件

提案を使用するには、開発環境が次の前提条件を満たしている必要があります。

  • Android アプリが App Actions を使用するように拡張されている。

  • マニフェストの <queries> タグ内に com.google.android.googlequicksearchbox が含まれている。例:

    <manifest ...>
      <queries>
        <package android:name="com.google.android.googlequicksearchbox" />
      </queries>
      ...
    </manifest>
    
  • Android App Bundle を使用してアプリを公開する。

デバイスの要件

デバイスで提案をテストするには、デバイスが次の要件を満たしている必要があります。

  • 最新バージョンの Google アプリがインストールされている。

  • Android のバージョンが M(API レベル 23)以降。

既知の制限事項

このセクションでは、提案に関する制限事項について説明します。

提案は英語のみに対応しています。候補を表示するには、デバイスのアシスタントの言語を英語に設定する必要があります。

提案を実装する

提案を実装するときは、build.gradle ファイルを更新し、提案クライアントを設定してから、ユーザーに提供する候補を定義する必要があります。

アプリに提案を実装するには:

  1. build.gradle ファイルにライブラリの依存関係を追加します。

    dependencies {
      ...
      implementation "com.google.assistant.appactions:suggestions:1.0.0"
    }
    
  2. AssistantShortcutSuggestionsClient のインスタンスを定義します。

    Kotlin

    val shortcutsClient =
      AssistantShortcutSuggestionsClient.builder()
        .setContext(CONTEXT: Context)
        .setVerifyIntents(VERIFY_INTENTS: Boolean)
        .setCustomExecutor(CUSTOM_EXECUTOR: Object)
        .build()
    

    Java

    AssistantShortcutSuggestionsClient shortcutsClient =
      AssistantShortcutSuggestionsClient.builder()
        .setContext(CONTEXT: Context)
        .setVerifyIntents(VERIFY_INTENTS: Boolean)
        .setCustomExecutor(CUSTOM_EXECUTOR: Object)
        .build();
    

    ここで

    • CONTEXT(必須)はアプリのコンテキストです。

    • VERIFY_INTENTS(必須)は、ユーザーにショートカットを提案する際に作成されたすべてのインテントを検証するかどうかを指定します。true の場合、AssistantShortcutSuggestionsClient によって作成されたインテントが検証されます。インテントが無効な場合は、例外が返されます。

    • CUSTOM_EXECUTOR(省略可)は、非同期タスクを実行するカスタム エグゼキュータです。指定されていない場合、SDK はこのタスクにシングルスレッドのエグゼキュータを使用します。

  3. lookupShortcut メソッドを使用して、提案するショートカットが有効かどうかと、そのショートカットがすでに存在するかどうかを確認します。既存のユーザー ショートカットを確認する予定がなくても、提案によって作成されたインテントが有効であることを確認するために lookupShortcut を実装することをおすすめします。

    1. アプリのショートカット インテントを作成します。ショートカット インテントは、ユーザーに提案するショートカットを表します。次の例は、ユーザーが飲み物を注文するためのショートカットを示しています。

      Kotlin

      val menuItem = mapOf(
          "@type" to "MenuItem",
          "@context" to "http://schema.googleapis.com",
          "name" to "Fresh Lemon Honey Jasmine Green Tea",
      )
      
      val appShortcutIntent = AppShortcutIntent.builder()
          .setIntentName("actions.intent.ORDER_MENU_ITEM")
          .setPackageName("my.app.package")
          .setIntentParamName("menuItem")
          .setIntentParamValue(menuItem)
          .build()
       

      Java

        Map menuItem = new HashMap<>();
        menuItem.put("@type", "MenuItem");
        menuItem.put("@context", "http://schema.googleapis.com");
        menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea");
      
        AppShortcutIntent appShortcutIntent =
            AppShortcutIntent.builder()
                .setIntentName("actions.intent.ORDER_MENU_ITEM")
                .setPackageName("my.app.package")
                .setIntentParamName("menuItem")
                .setIntentParamValue(menuItem)
                .build();
       
    2. ショートカット インテントを lookupShortcut メソッドに渡します。

      Kotlin

      val result = shortcutsClient.lookupShortcut(appShortcutIntent).await()
      if (!result.isShortcutPresent) {
          // app can suggest to create a shortcut
      } else {
          // app can remind that the user has a shortcut for this app action
      }
      

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
        .addOnSuccessListener(shortcutLookupResult -> {
          if (!shortcutLookupResult.isShortcutPresent()) {
            // app can suggest to create a shortcut
          } else {
            // app can remind that the user has a shortcut for this app action
          }
        })
        .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));
      
  4. ショートカット インテントを使用して候補を作成します。

    候補を作成する方法には、次の 2 つがあります。

    • createShortcutSuggestionIntent は、アプリのコンテキストでショートカット提案のアクティビティを開始するために使用する Android インテントを返します。

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build()
      
      val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await()
      application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
      

      Java

        AppShortcutSuggestion orderShortcut =
            AppShortcutSuggestion.builder()
                .setAppShortcutIntent(appShortcutIntent)
                .setCommand(PHRASE: String)
                .build();
      
        shortcutsClient.createShortcutSuggestionIntent(orderShortcut)
            .addOnSuccessListener(intent ->
                getApplication().startActivity(
                    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
            )
            .addOnFailureListener(e ->
                Log.e(TAG, "Failed to get shortcut suggestion intent", e);
            );
      

      ここで、PHRASE は、ショートカットとしてユーザーに提案する発話です。たとえば、ユーザーにショートカットとして「OK Google, order my bubble tea」と言ってほしい場合は、PHRASE"order my bubble tea" に置き換えます。

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand("order my bubble tea")
          .build()
      

      Java

      AppShortcutSuggestion orderShortcut =
          AppShortcutSuggestion.builder()
              .setAppShortcutIntent(appShortcutIntent)
              .setCommand("order my bubble tea")
              .build();
      
    • createShortcutSettingsIntent は、ユーザーをアシスタント アプリのショートカット設定インターフェースに移動する Android インテントを返します。

      Kotlin

      val intent = shortcutsClient.createShortcutSettingsIntent().await()
      application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
      

      Java

        shortcutsClient.createShortcutSettingsIntent()
          .addOnSuccessListener(intent ->
              getApplication().startActivity(
                  intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
          )
          .addOnFailureListener(e ->
              Log.e(TAG, "Failed to get shortcut settings intent", e);
          );
      
  5. 前のステップで返された Android インテントを使用して startActivity を呼び出します。

提案のトラブルシューティング

このセクションでは、ショートカットを提案する際に発生する可能性のある問題と例外を示します。

GoogleInstallationUnsupportedException: Cannot bind to service

パッケージの公開設定のフィルタリングにより、Android 11 以降で GoogleInstallationUnsupportedException: Cannot bind to service が発生する可能性があります。com.google.android.googlequicksearchbox がマニフェストの <queries> タグに含まれていることを確認してください。

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

「Failed to verify the APK signature」

製品版アプリを App Bundle として提出しないと、次のエラーが発生することがあります。

Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.

Android App Bundle としてアプリを提出してください。

「Failed to get user shortcuts」

「Failed to get user shortcuts」というエラー メッセージが表示されるのは、デバイスに最近アカウントを追加したが、新しいアカウントのショートカット データがまだデバイスのキャッシュに保存されていない場合です。

デバイスのショートカット データを同期するには、アシスタント アプリのインターフェースでアシスタント ショートカットを追加または削除します。

Shortcut Creation Activity がコンテンツを表示せずにすぐに終了する

App Actions Test Tool を使用してプレビューを作成していない場合や、プレビューの期限が切れている場合、Shortcut Creation Activity がコンテンツを表示せずに閉じる場合があります。プレビューを更新して、もう一度お試しください。