Tastenkombinationen mit dem In-App Promo SDK vorschlagen

Um Funktionen Ihrer App zu bewerben und die Nutzung zu vereinfachen, können Sie Ihren Nutzern Assistant-Verknüpfungen vorschlagen. Assistant-Verknüpfungen sind kurze Formulierungen, die Nutzer aussprechen können, um Funktionen in Ihrer App auszulösen.

Nutzer können Assistant-Verknüpfungen zwar manuell erstellen, aber mit dem In-App Promo SDK können Sie Assistant-Tastenkombinationen proaktiv vorschlagen und implementieren. Durch das Vorschlagen von Tastenkombinationen geben Sie Ihren Nutzern klare, einfache Pfade, um zu ihren Lieblingsaktivitäten in Ihrer App zurückzugelangen, ohne die Verknüpfungen einrichten zu müssen.

Wenn ein Nutzer beispielsweise in Ihrer Musik-App nach „Heavy Metal Training“ sucht, können Sie künftig eine Assistant-Verknüpfung zu diesen Suchergebnissen vorschlagen. Wenn Sie eine Verknüpfung vorschlagen, wird in Ihrer App eine Eingabeaufforderung mit der vorgeschlagenen Wortgruppe für die Verknüpfung angezeigt. Außerdem wird der Nutzer gefragt, ob die Verknüpfung erstellt werden kann.

In diesem Beispiel schlagen Sie den Satz „Beginne mein Heavy-Metal-Training“ vor. Der Nutzer nimmt den Vorschlag an und kann dann den Kurzbefehl starten, indem er „Hey Google, starte mein Heavy-Metal-Training“ sagt.

Weitere Informationen

Das In-App Promo SDK bietet folgende Methoden:

• lookupShortcut: Prüft, ob die vorgeschlagene Tastenkombination bereits vorhanden ist. Außerdem prüft sie, 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 Sie den Nutzer zum Erstellen der vorgeschlagenen Verknüpfung auffordern können.

• createShortcutSettingsIntent: gibt einen Intent zurück, mit dem du den Nutzer zu den Assistant-Verknüpfungseinstellungen für deine App verschieben kannst.

Voraussetzungen und Einschränkungen

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

Voraussetzungen für die Entwicklung

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

• Android-App auf die Verwendung von App Actions erweitern

• Füge com.google.android.googlequicksearchbox im <queries>-Tag in deinem Manifest ein. Beispiele:

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

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

Geräteanforderungen

Um Ihre Vorschläge auf einem Gerät zu testen, müssen auf Ihrem Gerät Folgendes installiert sein:

• Die neueste 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 einstellen.

Vorschläge implementieren

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 anbieten 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 Beispiel gilt:

   • CONTEXT (erforderlich) ist der Anwendungskontext.

   • VERIFY_INTENTS (erforderlich) bestimmt, ob jeder Intent geprüft wird, der beim Vorschlagen von Verknüpfungen für Nutzer erstellt wird. Wenn true ist, 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 nicht angegeben, verwendet das SDK einen Einzelthread-Executor für die Aufgabe.

3. Mit der Methode lookupShortcut können Sie feststellen, ob die vorgeschlagene Tastenkombination gültig ist und ob die Tastenkombination bereits vorhanden ist (optional).

   1. Erstellen Sie einen App-Verknüpfungs-Intent. Der Verknüpfungs-Intent steht für die Tastenkombination, die Sie einem Nutzer vorschlagen möchten. Im folgenden Beispiel wird ein Intent für eine Verknüpfung erstellt, um ein Getränk zu bestellen.

      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. Übergeben Sie den Verknüpfungs-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 mithilfe des Verknüpfungs-Intents. Es gibt zwei Methoden, um einen Vorschlag zu erstellen:

   • createShortcutSuggestionIntent: gibt einen Android-Intent zurück, mit dem Sie die Aktivität zu Verknüpfungsvorschlägen im Kontext Ihrer App starten.

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

     In diesem Beispiel ist PHRASE die Äußerung, die Sie dem Nutzer als Kürzel vorschlagen möchten. Wenn der Nutzer beispielsweise „Hey Google, bestell meinen Bubble Tea“ als Kurzbefehl sagen soll, ersetzen Sie PHRASE durch "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: gibt einen Android-Intent zurück, der den Nutzer zur Oberfläche mit den Einstellungen für Verknüpfungen in der Assistant App verschiebt.

     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 Tastenkombinationen auftreten können.

„GoogleInstallationNicht unterstützte Ausnahme: Keine Bindung an Dienst möglich“

Aufgrund des Filters der Paketsichtbarkeit kann unter Android 11 und höher „GoogleInstallationUnsupportedException: kann nicht an Dienst binden“ auftreten. Achte darauf, dass com.google.android.googlequicksearchbox in deinem Manifest im Tag <queries> 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 Produktionsanwendung 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.

„Fehler beim Abrufen der Nutzerverknüpfungen“

Die Fehlermeldung „Nutzerverknüpfungen konnten nicht abgerufen werden“ kann auftreten, 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.

Zum Synchronisieren der Verknüpfungsdaten auf dem Gerät kannst du über die Benutzeroberfläche der Assistant-App eine Assistant-Verknüpfung hinzufügen oder löschen.

Die Aktivität zum Erstellen von Kurzbefehlen 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 Testtool für App-Aktionen erstellen oder die Vorschau abläuft. Aktualisieren Sie die Vorschau und versuchen Sie es noch einmal.