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 percorsi chiari e semplici per tornare alle loro attività preferite nella tua app senza dover configurare le 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 prompt che mostra la frase proposta per la scorciatoia e chiede all'utente se può essere creata.

In questo esempio, suggerisci la frase "avvia il mio allenamento 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 ampliare il pubblico della tua app, consulta Fai crescere la tua app con le azioni app.

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

  • lookupShortcut: verifica se la scorciatoia che vuoi suggerire esiste già. Il metodo controlla 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 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.

Prerequisiti e limitazioni

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

Prerequisiti di sviluppo

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

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

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

    <manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchb>ox&<quot; /
>  /quer<ies
  ...>
/manifest

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

Requisiti del dispositivo

Per testare i suggerimenti su un dispositivo, è necessario che sia installato quanto segue.

  • L'ultima versione App Google

  • Android 6.0 (livello API 23) o versioni successive

Limitazioni note

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

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.

  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 intento creato quando si suggeriscono scorciatoie agli utenti. Quando true, le intenzioni create da AssistantShortcutSuggestionsClient vengono verificate. 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 Executor a thread singolo 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 app. L'intent di scorciatoia rappresenta la scorciatoia 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<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. Puoi utilizzare due metodi per creare un suggerimento:

    • createShortcutSuggestionIntent: restituisce un'intent di Android che viene utilizzato per avviare l'attività di suggerimento di scorciatoie nel contesto 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 diga "Hey Google, avvia 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 indirizza 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);
    );

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

Suggerimenti per la risoluzione dei problemi

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

"GoogleInstallationsupportedEccezione: impossibile eseguire l'associazione al servizio"

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.googlequicksearchb>ox&<quot; /
>  /quer<ies
  ...>
/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 l'app come Android App Bundle.

"Impossibile recuperare le scorciatoie utente"

Il messaggio di errore "Impossibile recuperare le scorciatoie utente" può verificarsi 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 per l'assistente utilizzando l'interfaccia dell'app Assistente.

L'attività di creazione della scorciatoia 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.