Questa pagina è stata tradotta dall'API Cloud Translation.

Suggerisci scorciatoie utilizzando l'SDK Promozione in-app

Per promuovere le funzionalità della tua app e semplificarne l'utilizzo, puoi suggerire Scorciatoie dell'assistente per i tuoi utenti. Le scorciatoie dell'assistente sono frasi concise che che un utente può pronunciare per attivare la funzionalità all'interno dell'app.

Sebbene le scorciatoie dell'assistente possano essere create manualmente dagli utenti, il L'SDK promozionale in-app ti consente di suggerire e implementare proattivamente l'assistente scorciatoie. Suggerendo scorciatoie, offri agli utenti informazioni chiare e semplici percorsi per tornare alle loro attività preferite nella tua app senza lo sforzo aggiuntivo della configurazione delle scorciatoie.

Ad esempio, se un utente esegue una ricerca per "allenamento heavy metal". nella tua musica app, potresti suggerire una scorciatoia per l'assistente direttamente a quei risultati di ricerca in futuro. Quando suggerisci una scorciatoia, nella tua app viene visualizzato un messaggio che visualizza la frase proposta per la scorciatoia e chiede all'utente se la scorciatoia è possibile creare.

In questo esempio, suggerisci la frase "start my heavy metal". esercizio fisico". L'utente accetta il suggerimento e può avviare la scorciatoia dicendo "Hey Google, inizia il mio allenamento heavy metal".

Per ulteriori informazioni su come ampliare il pubblico della tua app, consulta Fai crescere la tua app con le azioni per app.

L'SDK per la promozione in-app offre i seguenti metodi:

lookupShortcut: verifica se la scorciatoia che vuoi suggerire già esiste già. Il metodo verifica anche la presenza di eventuali problemi che impediscono alla scorciatoia dalla creazione. Se non è possibile creare la scorciatoia, lookupShortcut restituisce il motivo.
createShortcutSuggestionIntent: restituisce un intent che puoi utilizzare per chiede all'utente di creare la scorciatoia suggerita.
createShortcutSettingsIntent: restituisce un intent che puoi utilizzare per spostare l'utente alle impostazioni delle scorciatoie dell'assistente per la tua app.

di Gemini Advanced.

Prerequisiti e limitazioni

Questa sezione descrive i prerequisiti e i requisiti per l'utilizzo dei suggerimenti oltre alle limitazioni che potresti incontrare.

Prerequisiti di sviluppo

Per utilizzare i suggerimenti, l'ambiente di sviluppo deve soddisfare i seguenti requisiti e i prerequisiti necessari.

Estendi la tua app per Android a utilizzare Azioni app.

Includi com.google.android.googlequicksearchbox in <queries> nel tuo file manifest. Ad esempio:

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

Usa gli Android App Bundle per pubblicare le tue app.

Requisiti del dispositivo

Per testare i suggerimenti su un dispositivo, quest'ultimo deve avere quanto segue installato.

L'ultima versione App Google
Android 6.0 (livello API 23) o versioni successive

Limitazioni note

I suggerimenti sono supportati solo in inglese. Per consentire agli utenti di vedere i tuoi suggerimenti, il cliente deve impostare l'inglese come lingua dell'assistente sul dispositivo.

Implementa i suggerimenti

Per implementare i suggerimenti, devi aggiornare build.gradle impostare il client di suggerimenti, quindi definire i suggerimenti che che vuoi offrire agli utenti.

Aggiungi la dipendenza della libreria al file build.gradle.

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

Definisci un'istanza di 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 questo esempio:
- CONTEXT (obbligatorio) è il contesto dell'applicazione.
- VERIFY_INTENTS (obbligatorio) determina se verificare o meno ogni intent create quando suggerisci scorciatoie agli utenti. Quando true, gli intent creati da AssistantShortcutSuggestionsClient sono verificati. Se Un intent non è valido, viene restituita un'eccezione.
- CUSTOM_EXECUTOR (facoltativo) è un esecutore personalizzato per l'esecuzione le attività asincrone. Se non viene fornito, l'SDK utilizza un esecutore a thread singolo per l'attività.

Usa il metodo lookupShortcut per determinare se la scorciatoia che vuoi usare il suggerimento è valido e, facoltativamente, se la scorciatoia esiste già.

Crea un intent di scorciatoia app. L'intent della scorciatoia rappresenta che vuoi suggerire a un utente. Nell'esempio che segue crea un intent per una scorciatoia per ordinare una bevanda.

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

Passa l'intent della scorciatoia al metodo 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));

Crea il suggerimento utilizzando l'intent della scorciatoia. Esistono due metodi che puoi utilizzare per creare un suggerimento:

createShortcutSuggestionIntent: restituisce un intent Android che per avviare l'attività di suggerimento delle scorciatoie nel contesto della tua dell'app.

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 questo esempio, PHRASE è l'espressione che vuoi suggerire all'utente come scorciatoia. Ad esempio, se vuoi che l'utente per dire "Hey Google, ordina il mio bubble tea" come scorciatoia, sostituisci PHRASE con "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: restituisce un intent Android che si sposta l'utente all'interfaccia delle impostazioni delle scorciatoie nell'app Assistente.

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

Chiama il numero startActivity utilizzando l'intent Android restituito durante il passaggio precedente.

Nota: se la scorciatoia che suggerisci è in conflitto con una scorciatoia esistente, il all'utente rimane nel contesto della tua app e viene chiesto di impostare un nuovo per la scorciatoia.

Suggerimenti per la risoluzione dei problemi

In questa sezione sono elencati i problemi e le eccezioni che potresti riscontrare quando suggerisci scorciatoie.

"GoogleInstallationUnavailableEccezione: impossibile eseguire l'associazione al servizio"

A causa di il filtro per la visibilità dei pacchetti, "GoogleInstallationUnsupportedException: impossibile eseguire l'associazione al servizio" può verificarsi il giorno Android 11 e versioni successive. Assicurati che com.google.android.googlequicksearchbox è incluso nel tag <queries> del file manifest:

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

"Impossibile verificare la firma dell'APK"

Può verificarsi il seguente errore se non invii l'app di produzione come per un 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.

Assicurati di inviare l'app come Android App Bundle.

"Impossibile recuperare le scorciatoie utente"

L'errore "Impossibile recuperare le scorciatoie utente" può apparire se di recente ha aggiunto un account al dispositivo e i dati delle scorciatoie del nuovo account memorizzate nella cache del dispositivo.

Per sincronizzare i dati delle scorciatoie sul dispositivo, aggiungi o elimina una scorciatoia per l'assistente utilizzando l'interfaccia dell'app dell'assistente.

L'attività di creazione delle scorciatoie si chiude immediatamente senza mostrare alcun contenuto

L'attività di creazione di scorciatoie può chiudersi senza visualizzare alcun contenuto se non creare un'anteprima utilizzando lo strumento di test delle Azioni app o se l'anteprima scade. Aggiorna l'anteprima e riprova.