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

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

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

たとえば、ユーザーが音楽アプリで「heavy metal workout」という検索を行った場合、その検索結果に直接移動するアシスタント ショートカットを以降の検索時に提案します。ショートカットを提案する際は、ショートカットの候補フレーズを表示し、ショートカットを作成してよいかどうかをユーザーに尋ねるプロンプトがアプリに表示されます。

この例では、「start my heavy metal workout」というフレーズを提案します。ユーザーが提案を承認すると、「Hey Google, start my heavy metal workout」と話しかけてショートカットを起動できるようになります。

アプリの利用者を増やす方法について詳しくは、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 6.0（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 メソッドを使用して、提案するショートカットが有効かどうかを確認します。任意で、そのショートカットがすでに存在するかどうかも確認できます。

    1. アプリのショートカット インテントを作成します。ショートカット インテントは、ユーザーに提案するショートカットを表します。次の例をご覧ください。 エクササイズを開始するショートカットのインテントを作成します。

      Kotlin

      val exercise = mapOf(
    "@type" to "Exercise",
    "@context" to "http://schema.googleapis.com",
    "name" to "Running",
)

val appShortcutIntent = AppShortcutIntent.builder()
    .setIntentName("actions.intent.START_EXERCISE")
    .setPackageName("my.app.package")
    .setIntentParamName("exercise")
    .setIntentParamValue(exercise)
    .build()

      Java

        Map exercise = new HashMap<>();
  exercise.put("@type", "Exercise");
  menuItem.put("@context", "http://schema.googleapis.com");
  menuItem.put("name", "Running");

  AppShortcutIntent appShortcutIntent =
      AppShortcutIntent.builder()
          .setIntentName("actions.intent.START_EXERCISE")
          .setPackageName("my.app.package")
          .setIntentParamName("exercise")
          .setIntentParamValue(exercise)
          .build();

    2. ショートカット インテントを lookupShortcut メソッドに渡します。

      Kotlin

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

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
  .addOnSuccessListener(shortcutLookupResult -> {
    if (!shortcutLookupResult.isShortcutPresent()) {
      // App can suggest creating a shortcut
    } else {
      // App can remind the user that they have a shortcut for this app action
    }
  })
  .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));

  4. ショートカット インテントを使用して提案を作成します。提案を作成する方法には次の 2 つがあります。

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

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand(PHRASE: String)
    .build()

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

      Java

        AppShortcutSuggestion exerciseShortcut =
      AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build();

  shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut)
      .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, ランニングを開始」と言うには、 PHRASE を "start a run" に置き換えます。

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand("start a run")
    .build()

      Java

      AppShortcutSuggestion exerciseShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("start a run")
        .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」というエラー メッセージが表示されることがあります。

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

ショートカット作成アクティビティがコンテンツを表示せずにすぐに終了する

App Actions Test Tool を使用してプレビューを作成していない場合またはプレビューの期限が切れている場合に、ショートカット作成アクティビティがコンテンツを表示せずに終了することがあります。プレビューを更新して、もう一度お試しください。