Suggerisci scorciatoie utilizzando l'SDK Promozione in-app

Per promuovere le funzionalità della tua app e facilitarne l'utilizzo, puoi suggerire ai tuoi utenti le scorciatoie dell'assistente. Le scorciatoie dell'assistente sono frasi concise 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 le scorciatoie, fornisci agli utenti percorsi semplici e chiari per riportarli alle loro attività preferite nella tua app, senza dover configurare le scorciatoie.

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

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

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

L'SDK per le promozioni in-app offre 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 il motivo.

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

  • createShortcutSettingsIntent: restituisce un intent che puoi utilizzare per spostare l'utente nelle impostazioni della scorciatoia dell'assistente per la tua app.

Prerequisiti e limitazioni

In questa sezione vengono descritti i prerequisiti e i requisiti per l'utilizzo dei suggerimenti, nonché le limitazioni che potresti riscontrare.

Prerequisiti di sviluppo

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

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

  • Includi com.google.android.googlequicksearchbox all'interno del tag <queries> nel tuo file manifest. Ecco alcuni esempi:

    <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 tuoi suggerimenti su un dispositivo, è necessario che sul dispositivo sia installato 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. Per poter vedere i tuoi suggerimenti, gli utenti devono impostare l'inglese come lingua dell'assistente sul dispositivo.

Implementa suggerimenti

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

  1. Aggiungi la dipendenza dalla 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 suggerisci scorciatoie agli utenti. Quando true, vengono verificati gli intent creati da AssistantShortcutSuggestionsClient. Se un intent non è valido, viene restituita un'eccezione.

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

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

    1. Crea un intent della scorciatoia app. L'intent della scorciatoia rappresenta la scorciatoia da suggerire a un utente. L'esempio seguente 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();
       
    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 della scorciatoia. Esistono due metodi per creare un suggerimento:

    • createShortcutSuggestionIntent: restituisce un intent Android che utilizzi per avviare l'attività di suggerimento di scorciatoie nel contesto della tua 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 dica "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 sposta l'utente nell'interfaccia delle impostazioni della scorciatoia nell'app dell'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);
          );
      
  5. Chiama startActivity utilizzando l'intent Android restituito durante il passaggio precedente.

Suggerimenti per la risoluzione dei problemi

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

"GoogleInstallationSupportedException: Impossibile eseguire l'associazione al servizio"

A causa del filtro sulla visibilità dei pacchetti, su Android 11 e versioni successive potrebbe verificarsi il messaggio "GoogleInstallationUnsupportedException: impossibile associarsi al servizio". Assicurati che com.google.android.googlequicksearchbox sia incluso nel tag <queries> del tuo file manifest:

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

"Impossibile verificare la firma dell'APK"

Se non invii la tua 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 l'app come Android App Bundle.

"Impossibile recuperare le scorciatoie utente"

Il messaggio di errore "Impossibile recuperare le scorciatoie 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 sul dispositivo.

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

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

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.