Tastenkombinationen mit dem In-App Promo SDK vorschlagen

Wenn du die Funktionen deiner App bewerben und die Nutzung vereinfachen möchtest, kannst du deinen Nutzern Assistant-Kurzbefehle vorschlagen. Assistant-Kurzbefehle sind kurze Sätze, die ein Nutzer sagen kann, um Funktionen in deiner App auszulösen.

Assistant-Kurzbefehle können zwar manuell von Nutzern erstellt werden, mit dem In-App Promo SDK kannst du Assistant-Kurzbefehle jedoch proaktiv vorschlagen und implementieren. Wenn du Verknüpfungen vorschlägst, bietest du deinen Nutzern klare, einfache Möglichkeiten, zu ihren Lieblingsaktivitäten in deiner App zurückzukehren, ohne dass sie die Verknüpfungen selbst einrichten müssen.

Wenn ein Nutzer beispielsweise in deiner Musik-App nach „Heavy Metal Workout“ sucht, kannst du ihm in Zukunft einen Assistant-Kurzbefehl direkt zu diesen Suchergebnissen vorschlagen. Wenn du einen Kurzbefehl vorschlägst, wird in deiner App eine Aufforderung angezeigt, die den vorgeschlagenen Ausdruck für den Kurzbefehl enthält und den Nutzer fragt, ob der Kurzbefehl erstellt werden kann.

In diesem Beispiel schlagen Sie die Wortgruppe „Starte mein Heavy-Metal-Workout“ vor. Der Nutzer akzeptiert den Vorschlag und kann die Verknüpfung dann mit „Hey Google, starte mein Heavy-Metal-Workout“ starten.

Weitere Informationen dazu, wie Sie die Zielgruppe Ihrer App vergrößern können, finden Sie unter App mit App-Aktionen ausbauen.

Das In-App Promo SDK bietet die folgenden Methoden:

  • lookupShortcut: prüft, ob die Verknüpfung, die Sie vorschlagen möchten, bereits vorhanden ist. Die Methode prüft auch, ob Probleme vorliegen, die das Erstellen der Verknüpfung verhindern. Wenn die Verknüpfung nicht erstellt werden kann, gibt lookupShortcut die Gründe dafür zurück.

  • createShortcutSuggestionIntent: gibt einen Intent zurück, mit dem du den Nutzer auffordern kannst, die vorgeschlagene Verknüpfung zu erstellen.

  • createShortcutSettingsIntent: gibt einen Intent zurück, mit dem Sie den Nutzer zu den Einstellungen für Assistant-Kurzbefehle für Ihre App weiterleiten können.

Voraussetzungen und Einschränkungen

In diesem Abschnitt werden die Voraussetzungen und Anforderungen für die Verwendung von Vorschlägen sowie die Einschränkungen beschrieben, die auftreten können.

Voraussetzungen für die Entwicklung

Damit Sie Vorschläge verwenden können, muss Ihre Entwicklungsumgebung die folgenden Voraussetzungen erfüllen.

  • Erweitern Sie Ihre Android-App, um App Actions zu verwenden.

  • Fügen Sie com.google.android.googlequicksearchbox in das <queries>-Tag in Ihrem Manifest ein. Beispiel:

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

  • Verwenden Sie Android App Bundles, um Ihre Apps zu veröffentlichen.

Geräteanforderungen

Wenn Sie Ihre Vorschläge auf einem Gerät testen möchten, muss Folgendes auf dem Gerät installiert sein:

  • Die aktuelle Version der Google App

  • Android 6.0 (API-Level 23) oder höher

Bekannte Einschränkungen

Vorschläge werden nur auf Englisch unterstützt. Damit Nutzer Ihre Vorschläge sehen können, müssen sie die Assistant-Sprache auf ihrem Gerät auf Englisch festlegen.

Vorschläge umsetzen

Wenn Sie Vorschläge implementieren möchten, müssen Sie die Datei build.gradle aktualisieren, den Vorschlagsclient einrichten und dann die Vorschläge definieren, die Sie Nutzern machen möchten.

  1. Fügen Sie der Datei build.gradle die Bibliotheksabhängigkeit hinzu.

    dependencies {
  ...
  implementation "com.google.assistant.appactions:suggestions:1.0.0"
}

  2. Definieren Sie eine Instanz von 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();

    In diesem Fall gilt Folgendes:

    • CONTEXT (erforderlich) ist der Anwendungskontext.

    • VERIFY_INTENTS (erforderlich) bestimmt, ob jeder Intent überprüft werden soll, der beim Vorschlagen von Kurzbefehlen für Nutzer erstellt wird. Wenn true, werden die von AssistantShortcutSuggestionsClient erstellten Intents überprüft. Wenn ein Intent ungültig ist, wird eine Ausnahme zurückgegeben.

    • CUSTOM_EXECUTOR (optional) ist ein benutzerdefinierter Executor zum Ausführen asynchroner Aufgaben. Wenn nichts angegeben ist, verwendet das SDK einen Single-Thread-Executor für die Aufgabe.

  3. Mit der Methode lookupShortcut kannst du feststellen, ob die Verknüpfung, die du vorschlagen möchtest, gültig ist und ob sie bereits vorhanden ist.

    1. Erstellen Sie einen Intent für eine App-Verknüpfung. Der Shortcut-Intent stellt die Verknüpfung dar, die Sie einem Nutzer vorschlagen möchten. Im folgenden Beispiel wird ein Intent für eine Verknüpfung zum Starten eines Trainings erstellt.

      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<String, Object> 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. Übergeben Sie den Shortcut-Intent an die Methode 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. Erstellen Sie den Vorschlag mit dem Intent für die Verknüpfung. Es gibt zwei Methoden, mit denen Sie einen Vorschlag erstellen können:

    • createShortcutSuggestionIntent: Gibt einen Android-Intent zurück, mit dem Sie die Aktivität für Kurzbefehl-Vorschläge im Kontext Ihrer App starten.

      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);
      );

      In diesem Beispiel ist PHRASE die Äußerung, die Sie dem Nutzer als Kurzbefehl vorschlagen möchten. Wenn Sie beispielsweise möchten, dass der Nutzer „Hey Google, starte einen Lauf“ als Kurzbefehl sagt, ersetzen Sie PHRASE durch "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: Gibt einen Android-Intent zurück, der den Nutzer zur Oberfläche für die Kurzbefehl-Einstellungen in der Assistant App weiterleitet.

      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. Rufen Sie startActivity mit dem Android-Intent auf, der im vorherigen Schritt zurückgegeben wurde.

Vorschläge zur Fehlerbehebung

In diesem Abschnitt werden Probleme und Ausnahmen aufgeführt, die beim Vorschlagen von Kurzbefehlen auftreten können.

„GoogleInstallationUnsupportedException: Cannot bind to service“

Aufgrund der Filterung der Paketsichtbarkeit kann unter Android 11 und höher die Meldung „GoogleInstallationUnsupportedException: Cannot bind to service“ (: Bindung an Dienst nicht möglich) angezeigt werden. Achten Sie darauf, dass com.google.android.googlequicksearchbox im <queries>-Tag in Ihrem Manifest enthalten ist:

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

„Die APK-Signatur konnte nicht bestätigt werden“

Der folgende Fehler kann auftreten, wenn Sie Ihre Produktions-App nicht als App-Bundle einreichen:

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.

Reichen Sie Ihre App als Android App Bundle ein.

„Nutzer-Kurzbefehle konnten nicht abgerufen werden“

Die Fehlermeldung „Failed to get user shortcuts“ (Nutzerverknüpfungen konnten nicht abgerufen werden) kann angezeigt werden, wenn Sie dem Gerät vor Kurzem ein Konto hinzugefügt haben und die Verknüpfungsdaten des neuen Kontos noch nicht auf dem Gerät im Cache gespeichert sind.

Wenn du die Kurzbefehldaten auf dem Gerät synchronisieren möchtest, füge über die Oberfläche der Assistant App einen Assistant-Kurzbefehl hinzu oder lösche ihn.

Die Aktivität zum Erstellen von Verknüpfungen wird sofort geschlossen, ohne dass Inhalte angezeigt werden

Die Aktivität zum Erstellen von Verknüpfungen kann geschlossen werden, ohne dass Inhalte angezeigt werden, wenn Sie keine Vorschau mit dem App Actions-Testtool erstellen oder die Vorschau abläuft. Aktualisieren Sie die Vorschau und versuchen Sie es noch einmal.