Tastenkombinationen mit dem In-App Promo SDK vorschlagen

Sie können Ihren Nutzern Assistant-Verknüpfungen vorschlagen, um für Funktionen Ihrer App zu werben und die Nutzung zu vereinfachen. Assistant-Verknüpfungen sind kurze Sätze, die Nutzer sagen können, um Funktionen in Ihrer App auszulösen.

Zwar können die Assistant-Verknüpfungen manuell von Nutzern erstellt werden, der Mit dem In-App Promo SDK kannst du Assistant proaktiv vorschlagen und implementieren Tastenkombinationen. Wenn Sie Verknüpfungen vorschlagen, bieten Sie Ihren Nutzern klare und einfache Wege zurück zu ihren bevorzugten Aktivitäten in Ihrer App, ohne dass sie die Verknüpfungen selbst einrichten müssen.

Wenn ein Nutzer beispielsweise nach „Heavy Metal Training“ sucht in deiner Musik App kannst du Assistant-Verknüpfungen direkt zu diesen Suchergebnissen vorschlagen zu erhalten. Wenn Sie einen Befehl vorschlagen, wird in Ihrer App ein Prompt angezeigt, in dem der vorgeschlagene Befehl für den Befehl angezeigt wird und der Nutzer gefragt wird, ob der Befehl erstellt werden kann.

In diesem Beispiel schlagen Sie den Befehl „Starte mein Heavy-Metal-Training“ vor. Der Nutzer akzeptiert den Vorschlag und kann die Verknüpfung starten, indem er sagt: „Hey Google, starte mein Heavy-Metal-Training.“

Weitere Informationen dazu, wie du für deine App mehr Nutzer gewinnen kannst, findest du unter Mehr Erfolg für Ihre App durch App-Aktionen:

Das In-App Promo SDK bietet die folgenden Methoden:

  • lookupShortcut: Prüft, ob die Verknüpfung, die Sie vorschlagen möchten, bereits vorhanden ist. Außerdem wird geprüft, ob Probleme vorliegen, die das Erstellen des Symbols verhindern. Wenn die Verknüpfung nicht erstellt werden kann, lookupShortcut gibt die Gründe zurück.

  • createShortcutSuggestionIntent: Gibt eine Intent zurück, mit der Sie den Nutzer auffordern können, die vorgeschlagene Verknüpfung zu erstellen.

  • createShortcutSettingsIntent: gibt einen Intent zurück, mit dem Sie die Datei verschieben können den Nutzer zu den Einstellungen für Assistant-Verknüpfungen für deine App weiterleiten.

Voraussetzungen und Einschränkungen

In diesem Abschnitt werden die Voraussetzungen und Anforderungen für die Verwendung von Vorschlägen beschrieben. sowie auf mögliche Einschränkungen.

Entwicklungsvoraussetzungen

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

  • Android-App erweitern auf App Actions 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.googlequicksearchb>ox&<quot; /
>  /quer<ies
  ...>
/manifest

  • Veröffentlichen Sie Ihre Apps mit Android App Bundles.

Geräteanforderungen

Damit du deine Vorschläge auf einem Gerät testen kannst, muss dein Gerät folgende Voraussetzungen erfüllen: installiert haben.

  • Die neueste Version des 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, muss er die Assistant-Sprache auf seinem Gerät auf Englisch festlegen.

Implementierungsvorschläge

Um Vorschläge zu implementieren, müssen Sie Ihr build.gradle aktualisieren Datei, richten Sie den Vorschlagsclient ein und definieren dann die Vorschläge, die Sie den Nutzenden bieten möchten.

  1. Fügen Sie der Datei build.gradle die Bibliothek als Abhä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 Beispiel gilt Folgendes:

    • CONTEXT (erforderlich) ist der Anwendungskontext.

    • VERIFY_INTENTS (erforderlich) gibt an, ob jeder Intent überprüft werden soll, der beim Vorschlagen von Verknüpfungen für Nutzer erstellt wird. Bei true werden die Intents von AssistantShortcutSuggestionsClient erstellten wurden bestätigt. Wenn eine Absicht ungültig ist, wird eine Ausnahme zurückgegeben.

    • CUSTOM_EXECUTOR (optional) ist ein benutzerdefinierter Executor zum Ausführen asynchrone Aufgaben. Wenn nicht angegeben, verwendet das SDK für die Aufgabe einen einzeiligen Executor.

  3. Mit der Methode lookupShortcut können Sie prüfen, ob die von Ihnen vorgeschlagene Verknüpfung gültig ist und ob sie bereits vorhanden ist.

    1. Erstellen Sie einen Intent für App-Verknüpfungen. Die Kurzbefehlsabsicht stellt den Kurzbefehl dar, den Sie einem Nutzer vorschlagen möchten. Im folgenden Beispiel wird ein Intent für einen Hotkey erstellt, um eine Übung zu starten.

      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 Intent der Verknüpfung 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 „Verknüpfung“. Es gibt zwei Methoden, mit denen Sie verwenden können, um einen Vorschlag zu erstellen:

    • createShortcutSuggestionIntent: Gibt eine Android-Intent zurück, mit der Sie die Aktivität für die Vorschlagsfunktion für Verknüpfungen 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 Tastenkürzel vorschlagen möchten. Wenn Sie beispielsweise möchten, dass der Nutzer als Verknüpfung „Hey Google, starte einen Lauf“ sagen soll, 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 eine Android-Intent zurück, über die der Nutzer zur Oberfläche für die Verknüpfungseinstellungen in der Assistant App weitergeleitet wird.

      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 der Android-Intent auf, die im vorherigen Schritt zurückgegeben wurde.

Fehlerbehebung bei Vorschlägen

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

„GoogleInstallationUnsupportedException: Cannot bind to service“

Aufgrund von Paketsichtbarkeit filtern "GoogleInstallationUnsupportedException: Bindung an Dienst nicht möglich" kann auftreten am Android 11 und höher. Achten Sie darauf, dass com.google.android.googlequicksearchbox ist im <queries>-Tag in deinem Manifest enthalten:

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchb>ox&<quot; /
>  /quer<ies
  ...>
/manifest

„Die APK-Signatur konnte nicht überprüft 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.

Stellen Sie sicher, dass Sie Reichen Sie Ihre App als Android App Bundle ein.

„Fehler beim Abrufen der Nutzerverknüpfungen“

Die Meldung „Nutzerverknüpfungen konnten nicht abgerufen werden“ kann eine Fehlermeldung auftreten, ein Konto zu dem Gerät hinzugefügt hat und die Verknüpfungsdaten des neuen Kontos noch im Cache auf dem Gerät gespeichert ist.

Wenn du die Verknüpfungsdaten auf dem Gerät synchronisieren möchtest, musst du eine Assistant-Verknüpfung hinzufügen oder löschen über die Benutzeroberfläche der Assistant-App.

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.