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, l'SDK In-App Promo ti consente di suggerire e implementare in modo proattivo le scorciatoie dell'assistente. 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 "avvia il mio allenamento heavy metal". 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 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 ogni intento creato quando si suggeriscono 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 avviare un allenamento.

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

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 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 questo esempio, PHRASE è l'espressione che vuoi suggerire all'utente come scorciatoia. Ad esempio, se vuoi che l'utente per dire "Hey Google, inizia una corsa" come scorciatoia, sostituisci PHRASE con "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: 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 Assistente.

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

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