Cette page a été traduite par l'API Cloud Translation.

Appel d'application au premier plan

Les actions dans l'application permettent aux utilisateurs de parler à l'Assistant Google et d'accéder directement à des destinations d'application spécifiques lorsqu'ils disent quelque chose comme Hey Google, réserve-moi un taxi dans l'appli XXX. Grâce à l'appel d'application au premier plan, vous pouvez améliorer davantage l'expérience utilisateur lorsque votre application est déjà ouverte.

Un appel d'application au premier plan permet de faire correspondre des intents intégrés sans qu'il soit nécessaire de mentionner le nom de l'application lorsqu'une activité spécifique se trouve au premier plan de l'appareil.

Par exemple, un utilisateur lance votre application de partage de course au premier plan et rédige ou énonce une commande pour demander Réserve-moi une course pour Neuilly-sur-Seine à l'Assistant Google. Votre application utilise cette entrée pour définir le champ de destination sur Neuilly-sur-Seine. Ensuite, lorsque l'utilisateur dit ou saisit Réserve-moi une course au départ de Paris-CDG, votre application peut définir le lieu de prise en charge tout en conservant l'état de votre application.

Limites

L'appel d'application au premier plan n'est disponible que pour les intents intégrés suivants :

Afin de profiter de la prise en charge de régions spécifiques et de consulter des exemples de requêtes liées aux appels d'application au premier plan pour un intent spécifique, consultez la documentation de référence sur les intents intégrés.

Permettre l'appel d'application au premier plan

Pour permettre les appels d'application au premier plan, vous devez ajouter un comportement de traitement basé sur l'activité de premier plan souhaitée. Lorsque cette activité est au premier plan et que l'action dans l'application est appelée, l'Assistant transmet l'intent de lien profond avec un indicateur supplémentaire à cette activité pour que votre application puisse mettre à jour son état.

Pour implémenter un appel d'application au premier plan pour un intent intégré, procédez comme suit :

Dans votre fichier shortcuts.xml, ajoutez une balise <intent> à l'intent intégré <capability> que vous souhaitez utiliser pour appeler l'application au premier plan.
Dans la balise <intent>, ajoutez une balise <extra>.
Dans la balise <extra>, définissez android:key sur "requiredForegroundActivity", puis android:value sur l'activité à appeler au premier plan. Spécifiez l'activité sans aucune abréviation de classe à l'aide du nom de votre package d'application, suivi d'une barre oblique (/), puis du nom de l'activité : APP_PACKAGE_NAME/ACTIVITY_NAME.
Dans l'activité de premier plan que vous avez spécifiée pour "requiredForegroundActivity", implémentez la méthode onNewIntent() pour gérer un intent de lien profond et assurez-vous que l'indicateur SINGLE_TOP est défini. L'Assistant transmet l'intent de lien profond avec cet indicateur en tant que traitement lorsque l'activité spécifiée est exécutée au premier plan.
Traitez les appels à onNewIntent() comme des mises à jour de votre activité de premier plan et gérez l'état de cette activité à l'aide de paramètres extraits du lien profond.

Si votre application utilise une activité de routeur pour permettre à tous les liens profonds externes de déclencher une seule activité de routeur de contrôle d'accès, consultez Gérer les activités de routeur.

Exemple

L'extrait suivant d'un exemple de fichier shortcuts.xml montre comment ajouter l'attribut requiredForegroundActivity :

  <capability name="actions.intent.CREATE_TAXI_RESERVATION">
      <!-- Trigger with foreground app invocation if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
          <extra
              android:key="requiredForegroundActivity"
              android:value="com.example.app/com.example.app.MainActivity" />
      </intent>
      <!-- This won't trigger if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
      </intent>
  </capability>

Autorisations utilisateur

Dans les paramètres de l'appareil, les utilisateurs doivent activer l'option "Utiliser le texte à l'écran" pour que l'appel d'application au premier plan fonctionne.

Pour que l'appel d'application au premier plan fonctionne pour un utilisateur, le paramètre d'appareil Utiliser le texte de l'écran doit être activé. L'emplacement et le nom exact de ce paramètre peuvent varier en fonction du fabricant d'équipement d'origine (OEM) ou de l'appareil. Par exemple, ce paramètre d'appareil peut être appelé Utiliser le contexte de l'écran sur l'appareil d'un utilisateur.

Pour accéder à ce paramètre Android sur un téléphone Pixel, sélectionnez Settings > Apps & notifications > Default apps > Assist app (Paramètres > Applications et notifications > Applications par défaut > Application d'assistance). Sur l'écran Assist and voice input (Assistance et saisie vocale), activez ensuite Use text from screen (Utiliser le texte de l'écran).

Tester votre appel

Pour tester l'appel de votre application au premier plan, procédez comme suit :

Suivez les instructions de la section Autorisations utilisateur pour activer le paramètre d'appareil Utiliser le texte de l'écran.
Ouvrez l'application pour accéder à l'activité que vous avez indiquée comme activité de premier plan requise.
Appuyez de manière prolongée sur le bouton d'accueil pour ouvrir l'Assistant en superposition sur l'application actuelle. Fournissez une requête correspondant à l'intent intégré que vous avez implémenté sans mentionner le nom de l'application proprement dite. Si l'appel aboutit, votre application se met à jour automatiquement en fonction de votre requête, tout en conservant son état et sans redémarrer l'activité.

Gérer les activités de routeur

Certaines applications gèrent tous les liens profonds externes à l'aide d'une seule activité de routeur de contrôle d'accès. Celle-ci démarre alors l'activité de logique métier appropriée (après avoir effectué les vérifications et les validations nécessaires) et renvoie cette activité de logique métier au premier plan.

Le déclenchement d'un lien profond peut entraîner l'ajout de l'activité du routeur en haut de la pile de tâches, au-dessus de l'activité de premier plan. Pour les applications qui utilisent une activité de routeur, vous devez vous assurer que celle-ci transmet l'intent envoyé par l'Assistant Google à l'instance d'activité de premier plan active. La marche à suivre varie en fonction de l'endroit où l'activité du routeur commence.

Si le routeur commence dans la même pile de tâches que l'activité de logique métier, transférez l'intent à l'aide de SINGLE_TOP, CLEAR_TOP et NEW_TASK et de l'opérateur OR au niveau du bit :

Kotlin

Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK

Java

Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK

Si le routeur démarre dans une pile de tâches distincte de votre activité de logique métier, transférez l'intent avec l'indicateur SINGLE_TOP à l'activité de logique métier.