Tastenkombinationen mit dem In-App Promo SDK vorschlagen

Um für Funktionen Ihrer App zu werben und deren Nutzung zu erleichtern, können Sie Assistant-Verknüpfungen für Ihre Nutzer. 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. Durch Vorschläge für Verknüpfungen zu ihren Lieblingsaktivitäten in Ihrer App, ohne zusätzlichen Aufwand zu nutzen. zum Einrichten der Tastenkombinationen.

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 Shortcut angezeigt wird und der Nutzer gefragt wird, ob der Shortcut erstellt werden kann.

In diesem Beispiel schlagen Sie den Satz Training.“ 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 Sie die Zielgruppe Ihrer App vergrößern können, finden Sie unter App-Aktionen für mehr Nutzer.

Das In-App Promo SDK bietet die folgenden Methoden:

  • lookupShortcut:Prüft, ob die vorgeschlagene Verknüpfung bereits existiert. Die Methode sucht auch nach Problemen, die die Verknüpfung verhindern. nicht erstellt werden kann. Wenn die Verknüpfung nicht erstellt werden kann, lookupShortcut gibt die Gründe zurück.

  • createShortcutSuggestionIntent: gibt einen Intent zurück, mit dem Sie den Nutzer auffordern, 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

Ihre Entwicklungsumgebung muss die folgenden Anforderungen erfüllen, um Vorschläge verwenden zu können Voraussetzungen.

  • Erweitere deine Android-App 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.googlequicksearchbox" />
  </queries>
  ...
</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, müssen sie die Assistant-Sprache auf ihrem Gerät auf Englisch einstellen.

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 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 Folgendes:

    • CONTEXT (erforderlich) ist der Anwendungskontext.

    • VERIFY_INTENTS (erforderlich): Legt fest, ob alle Intents überprüft werden wenn Nutzern Verknüpfungen vorgeschlagen werden. Bei true werden die Intents die von AssistantShortcutSuggestionsClient erstellt wurden, sind bestätigt. 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 eine Single-Threaded-Executor für die Aufgabe.

  3. Mit der lookupShortcut-Methode 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. Der Shortcut-Intent steht für die Sie einem Nutzer vorschlagen möchten. Im folgenden Beispiel erstellt einen Intent für eine Verknüpfung zum Starten eines Trainings.

      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. Ü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 mithilfe des Shortcut-Intent. Es gibt zwei Methoden, mit denen Sie verwenden können, um einen Vorschlag zu erstellen:

    • createShortcutSuggestionIntent: gibt einen Android-Intent zurück, den Sie zum Starten der Aktivität zum Vorschlagen von Kurzbefehlen im Kontext Ihres

      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 der Nutzer z. B. um „Hey Google, Lauf starten“ als Shortcut zu sagen, ersetzen Sie PHRASE mit "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 sich bewegt. der Nutzer zur Oberfläche für die Verknüpfungseinstellungen in der Assistant-App gelangt.

      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. startActivity anrufen mit dem Android-Intent, der 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.

"GoogleInstallationOptimizedException: Bindung an Dienst nicht möglich"

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.googlequicksearchbox" />
  </queries>
  ...
</manifest>

„Die APK-Signatur konnte nicht überprüft werden“

Der folgende Fehler kann auftreten, wenn du deine Produktions-App nicht einreichst als ein 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.

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 und es werden keine Inhalte angezeigt

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.