Suggérer des raccourcis à l'aide du SDK de promotion intégré à l'application

Pour promouvoir les fonctionnalités de votre application et les rendre plus faciles à utiliser, vous pouvez suggérer à vos utilisateurs des raccourcis destinés à l'Assistant. Les raccourcis de l'Assistant sont des expressions concises qu'un utilisateur peut énoncer pour déclencher une fonctionnalité dans votre application.

Bien que les raccourcis de l'Assistant puissent être créés manuellement par les utilisateurs, le SDK de promotion intégré à l'application vous permet de suggérer et d'implémenter de manière proactive les raccourcis de l'Assistant. En suggérant des raccourcis, vous permettez aux utilisateurs de revenir à leurs activités préférées dans votre application de manière simple et claire, sans avoir à configurer ces raccourcis.

Par exemple, si un utilisateur recherche une "séance d'entraînement heavy metal" dans votre application musicale, vous pourriez suggérer un raccourci de l'Assistant permettant d'accéder directement à ces résultats de recherche à l'avenir. Lorsque vous suggérez un raccourci, une invite apparaît dans l'application. Celle-ci affiche la proposition de raccourci et demande à l'utilisateur si le raccourci peut être créé.

Dans cet exemple, vous suggérez l'expression suivante : "start my heavy metal workout" (démarre ma séance d'entraînement heavy metal). L'utilisateur accepte cette suggestion, puis peut lancer le raccourci en disant "Hey Google, start my heavy metal workout." (Hey Google, démarre ma séance d'entraînement heavy metal).

Pour en savoir plus sur les façons d'élargir l'audience de votre application, consultez Développer votre application avec les actions dans l'application.

Le SDK de promotion intégré à l'application propose les méthodes suivantes :

• lookupShortcut : vérifie si le raccourci que vous souhaitez suggérer existe déjà. Cette méthode détecte également les problèmes qui empêchent la création du raccourci. Si le raccourci ne peut pas être créé, lookupShortcut en explique la raison.

• createShortcutSuggestionIntent : renvoie un intent qui vous permet d'inviter l'utilisateur à créer le raccourci suggéré.

• createShortcutSettingsIntent : renvoie un intent qui permet de rediriger l'utilisateur vers les paramètres de raccourci de l'Assistant pour votre application.

Remarque : Le SDK de promotion intégré à l'application n'est pas compatible avec les raccourcis associés aux intents personnalisés.

Conditions préalables et limites

Cette section décrit les conditions préalables et la configuration d'appareil à respecter pour pouvoir utiliser les suggestions. Vous y trouverez également les limites que vous pouvez rencontrer.

Conditions préalables pour le développement

Pour pouvoir utiliser les suggestions, votre environnement de développement doit remplir les conditions suivantes.

• Étendez votre application Android afin d'utiliser les actions dans l'application.

• Incluez com.google.android.googlequicksearchbox dans la balise <queries> de votre fichier manifeste. Par exemple :

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

• Utilisez le format Android App Bundle pour publier vos applications.

Configuration d'appareil requise

Pour que vous puissiez tester vos suggestions sur un appareil, les éléments suivants doivent y être installés :

• La dernière version de l'appli Google

• Android 6.0 (niveau d'API 23) ou version ultérieure

Limites connues

Les suggestions ne fonctionnent qu'en anglais. Pour que les utilisateurs voient vos suggestions, ils doivent choisir l'anglais comme langue de l'Assistant sur leur appareil.

Implémenter des suggestions

Pour implémenter des suggestions, vous devez mettre à jour votre fichier build.gradle, configurer le client de suggestions, puis définir les suggestions que vous souhaitez proposer aux utilisateurs.

1. Ajoutez la dépendance de bibliothèque à votre fichier build.gradle.

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

2. Définissez une instance 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();
   

   Dans cet exemple :

   • CONTEXT (obligatoire) correspond au contexte de l'application.

   • VERIFY_INTENTS (obligatoire) détermine s'il faut vérifier tous les intents créés lors de la suggestion de raccourcis aux utilisateurs. Avec true, les intents créés par AssistantShortcutSuggestionsClient sont validés. Si un intent n'est pas valide, une exception est renvoyée.

   • CUSTOM_EXECUTOR (facultatif) est un exécuteur personnalisé permettant d'exécuter des tâches asynchrones. S'il n'est pas fourni, le SDK utilise un exécuteur monothread pour la tâche.

3. Utilisez la méthode lookupShortcut pour déterminer si le raccourci que vous souhaitez suggérer est valide et, éventuellement, si ce raccourci existe déjà.

   1. Créez un intent de raccourci d'application. L'intent de raccourci représente le raccourci que vous souhaitez suggérer à un utilisateur. L'exemple suivant crée un intent pour un raccourci afin de démarrer un exercice.

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

   2. Transmettez l'intent de raccourci à la méthode 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. Créez la suggestion à l'aide de l'intent de raccourci. Deux options s'offrent à vous pour créer une suggestion :

   • createShortcutSuggestionIntent : renvoie un intent Android que vous utilisez pour lancer l'activité de suggestion de raccourci dans le contexte de votre application.

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

     Dans cet exemple, PHRASE est l'énoncé que vous souhaitez suggérer à l'utilisateur en tant que raccourci. Par exemple, si vous souhaitez que l'utilisateur pour dire "Hey Google, démarre une course à pied" comme raccourci, remplacez PHRASE avec "start a run".

     Remarque : N'incluez pas Hey Google dans votre suggestion.

     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 : renvoie un intent Android qui redirige l'utilisateur vers l'interface des paramètres de raccourci de l'application Assistant.

     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. Appelez startActivity à l'aide de l'intent Android renvoyé à l'étape précédente.

   Remarque : Si le raccourci que vous suggérez est en conflit avec un raccourci existant, l'utilisateur reste dans le contexte de votre application et est invité à définir un nouvel énoncé pour le raccourci.

Résoudre les problèmes liés aux suggestions

Cette section liste les problèmes et les exceptions que vous pouvez rencontrer lorsque vous suggérez des raccourcis.

"GoogleInstallationUnsupportedException: Cannot bind to service" (GoogleInstallationUnsupportedException : association au service impossible)

En raison du filtrage de la visibilité des packages, le message "GoogleInstallationUnsupportedException: Cannot bind to service" peut apparaître sur Android 11 et versions ultérieures. Assurez-vous que com.google.android.googlequicksearchbox est inclus dans la balise <queries> de votre fichier manifeste :

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

"Failed to verify the APK signature" (Échec de la validation de la signature de l'APK)

L'erreur suivante peut se produire si vous n'envoyez pas votre application de production en tant qu'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.

Assurez-vous d'envoyer votre application au format Android App Bundle.

"Failed to get user shortcuts" (Échec de l'obtention des raccourcis utilisateur)

Le message d'erreur "Failed to get user shortcuts" (Échec de l'obtention des raccourcis utilisateur) peut s'afficher si vous avez récemment ajouté un compte à l'appareil et que les données de raccourci de ce nouveau compte n'ont pas encore été mises en cache sur l'appareil.

Pour synchroniser les données de raccourci sur l'appareil, ajoutez ou supprimez un raccourci de l'Assistant à l'aide de l'interface de l'application Assistant.

L'activité de création de raccourcis se ferme immédiatement, sans afficher de contenu

L'activité de création de raccourcis peut se fermer sans afficher de contenu si vous n'avez pas créé d'aperçu à l'aide de l'outil de test des actions dans l'application ou si l'aperçu a expiré. Mettez à jour l'aperçu, puis réessayez.