Suggerisci scorciatoie utilizzando l'SDK Promozione in-app

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

Sebbene le scorciatoie per l'assistente possano essere create manualmente dagli utenti, l'SDK In-App Promo ti consente di suggerire e implementare in modo proattivo le scorciatoie per l'assistente. Suggerendo scorciatoie, offri agli utenti percorsi chiari e semplici per tornare alle loro attività preferite nella tua app senza lo sforzo aggiuntivo di configurare le scorciatoie.

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

In questo esempio, suggerisci la frase "Avvia il mio allenamento heavy metal". L'utente accetta il suggerimento e può quindi avviare la scorciatoia dicendo: "Hey Google, avvia il mio allenamento heavy metal".

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

L'SDK In-App Promo fornisce i seguenti metodi:

• lookupShortcut: controlla se la scorciatoia che vuoi suggerire esiste già. Il metodo verifica anche la presenza di eventuali problemi che impediscono la creazione della scorciatoia. Se non è possibile creare la scorciatoia, lookupShortcut restituisce i motivi.

• createShortcutSuggestionIntent: restituisce un intent che puoi utilizzare per chiedere all'utente di creare la scorciatoia suggerita.

• createShortcutSettingsIntent: restituisce un intent che puoi utilizzare per indirizzare l'utente alle impostazioni delle scorciatoie per l'assistente della tua app.

Nota: l'SDK In-App Promo non supporta le scorciatoie associate a segmenti di pubblico personalizzati per intenzione.

Prerequisiti e limitazioni

Questa sezione descrive i prerequisiti e i requisiti per l'utilizzo dei suggerimenti, nonché le limitazioni che potresti riscontrare.

Prerequisiti per lo sviluppo

Per utilizzare i suggerimenti, il tuo ambiente di sviluppo deve soddisfare i seguenti prerequisiti.

• Estendi la tua app per Android per utilizzare Azioni app.

• Includi com.google.android.googlequicksearchbox all'interno del tag <queries> nel manifest. Ad esempio:

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

• Utilizza gli Android App Bundle per pubblicare le tue app.

Requisiti del dispositivo

Per testare i suggerimenti su un dispositivo, devi installare quanto segue.

• L'ultima versione dell'app Google

• Android 6.0 (livello API 23) o versioni successive

Limitazioni note

I suggerimenti sono supportati solo in inglese. Affinché gli utenti possano visualizzare i tuoi suggerimenti, devono impostare la lingua dell'assistente sul proprio dispositivo su inglese.

Implementa i suggerimenti

Per implementare i suggerimenti, devi aggiornare il file build.gradle, configurare il client dei suggerimenti e poi definire i suggerimenti che vuoi fornire agli utenti.

1. Aggiungi la dipendenza della libreria al file build.gradle.

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

2. 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 intent creato quando vengono suggerite scorciatoie agli utenti. Quando true, gli intent creati da AssistantShortcutSuggestionsClient vengono verificati. Se un intent non è valido, viene restituita un'eccezione.

   • CUSTOM_EXECUTOR (facoltativo) è un executor personalizzato per l'esecuzione di attività asincrone. Se non viene fornito, l'SDK utilizza un esecutore single-thread per l'attività.

3. Utilizza il metodo lookupShortcut per determinare se la scorciatoia che vuoi suggerire è valida e, facoltativamente, se esiste già.

   1. Crea un intent di scorciatoia per l'app. L'intent della scorciatoia rappresenta la scorciatoia che vuoi suggerire a un utente. L'esempio seguente crea un intent per una scorciatoia per iniziare 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<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. 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));

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

   • createShortcutSuggestionIntent: restituisce un intent Android che utilizzi per avviare l'attività di suggerimento delle scorciatoie nel contesto della tua 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'enunciato che vuoi suggerire all'utente come scorciatoia. Ad esempio, se vuoi che l'utente dica "Hey Google, avvia una corsa" come scorciatoia, sostituisci PHRASE con "start a run".

     Nota: non includere Hey Google nel suggerimento.

     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 indirizza l'utente all'interfaccia delle impostazioni delle scorciatoie nell'app di assistenza.

     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. Chiama startActivity utilizzando l'intent Android restituito nel passaggio precedente.

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

Suggerimenti per la risoluzione dei problemi

Questa sezione elenca i problemi e le eccezioni che potresti riscontrare quando suggerisci scorciatoie.

"GoogleInstallationUnsupportedException: Cannot bind to service"

A causa del filtraggio della visibilità dei pacchetti, l'errore "GoogleInstallationUnsupportedException: impossibile eseguire il binding al servizio" potrebbe verificarsi su Android 11 e versioni successive. Assicurati che com.google.android.googlequicksearchbox sia incluso nel tag <queries> nel manifest:

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

"Impossibile verificare la firma dell'APK"

Se non invii l'app di produzione come app bundle, può verificarsi il seguente errore:

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 la tua app come Android App Bundle.

"Impossibile recuperare le scorciatoie dell'utente"

Il messaggio di errore "Impossibile recuperare le scorciatoie dell'utente" può essere visualizzato se di recente hai aggiunto un account al dispositivo e i dati delle scorciatoie del nuovo account non sono ancora memorizzati 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 di assistenza.

L'attività di creazione della scorciatoia si chiude immediatamente senza mostrare alcun contenuto

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