Configurer la distribution conditionnelle

La distribution conditionnelle vous permet de définir certaines exigences de configuration de l'appareil pour que les modules de fonctionnalités soient téléchargés automatiquement lors de l'installation de l'application. Par exemple, vous pouvez configurer un module de fonctionnalité comprenant la fonction de réalité augmentée (RA) afin qu'il ne soit disponible lors de l'installation d'une application que pour les appareils compatibles avec la RA.

Ce mécanisme de distribution permet actuellement de contrôler le téléchargement d'un module au moment de l'installation de l'application en fonction des configurations d'appareil suivantes :

Si un appareil ne répond pas à toutes les exigences spécifiées, le module n'est pas téléchargé au moment de l'installation de l'application. Cependant, votre application peut ensuite demander à télécharger le module à la demande à l'aide du SDK Play Core.

Avant de commencer, assurez-vous d'utiliser Android Studio 3.5 ou une version ultérieure. Dans les sections suivantes, nous vous expliquons comment activer la distribution conditionnelle des modules de fonctionnalités.

Ajouter un module avec des options de distribution conditionnelle

Le moyen le plus simple de créer un module de fonctionnalité avec distribution conditionnelle consiste à utiliser l'assistant Nouveau module, comme suit :

  1. Pour ouvrir la boîte de dialogue Nouveau module, sélectionnez Fichier > Nouveau > Nouveau module dans la barre de menu.
  2. Dans la boîte de dialogue "Nouveau module", sélectionnez Module de fonctionnalité dynamique, puis cliquez sur Suivant.
  3. Configurez le module comme vous le feriez normalement, puis cliquez sur Suivant.

  4. Dans la section Options de téléchargement du module, procédez comme suit :

    1. Spécifiez le titre du module en utilisant jusqu'à 50 caractères. La plate-forme utilisera ce titre pour que les utilisateurs puissent identifier le module, par exemple pour confirmer le téléchargement. C'est pourquoi le module de base de votre application doit inclure le titre du module en tant que ressource de chaîne, que vous pouvez traduire. Lors de la création du module à l'aide d'Android Studio, l'IDE ajoute la ressource de chaîne au module de base et injecte l'entrée suivante dans le fichier manifeste du module de fonctionnalité :

      <dist:module
    ...
    dist:title="@string/feature_title">
</dist:module>

    2. Dans le menu déroulant Inclusion à l'installation, sélectionnez Inclure le module uniquement lors de l'installation de l'application pour les appareils dotés de fonctionnalités spécifiques. Un module est alors inclus avec votre application lors de son installation, seulement sur les appareils associés à certaines configurations que vous pouvez spécifier, telles que les fonctionnalités de l'appareil ou le pays. Android Studio injecte les éléments suivants dans le fichier manifeste du module pour refléter votre choix :

      <dist:module ... >
  <dist:delivery>
      <dist:install-time>
          <dist:conditions>
              <!-- If you specify conditions, as described in the steps
                   below, the IDE includes them here. -->
          </dist:conditions>
      </dist:install-time>
  </dist:delivery>
</dist:module>

    3. Si vous souhaitez limiter le téléchargement automatique du module à certains pays ou à un niveau d'API minimal, cliquez sur Terminer afin de terminer la création du module. Consultez ensuite la section expliquant comment spécifier des conditions en fonction du pays ou du niveau d'API minimal. Sinon, cliquez sur + fonctionnalité de l'appareil pour ajouter une fonctionnalité que l'appareil doit avoir afin que le module soit téléchargé au moment de l'installation.

    4. À côté de fonctionnalité de l'appareil, sélectionnez l'une des options suivantes dans le menu déroulant et spécifiez sa valeur :

      • Nom : permet de spécifier une fonctionnalité matérielle ou logicielle nécessaire à un appareil pour télécharger le module au moment de l'installation. Les fonctionnalités compatibles avec la distribution conditionnelle sont les mêmes que celles répertoriées comme constantes FEATURE_* par PackageManager. Si vous sélectionnez cette option, commencez à saisir une partie de la valeur constante de cette fonctionnalité, par exemple "Bluetooth", dans le champ situé à côté du menu déroulant, puis choisissez l'une des suggestions qui s'affichent.
      • Version OpenGL ES : permet de spécifier une version d'OpenGL ES requise par un appareil pour télécharger le module au moment de l'installation. Si vous sélectionnez cette option, commencez à saisir la version (par exemple, "0x00030001") dans le champ situé à côté du menu déroulant, puis choisissez l'une des suggestions qui s'affichent.

    5. Si vous souhaitez ajouter plusieurs conditions en fonction des fonctionnalités d'appareil disponibles, cliquez sur + fonctionnalité de l'appareil pour chaque condition que vous souhaitez spécifier.

    6. Cochez la case Fusion si vous souhaitez que ce module soit disponible pour les appareils équipés d'Android 4.4 (niveau d'API 20) ou version antérieure, et qu'il soit inclus dans plusieurs APK. Autrement dit, vous pouvez activer le comportement à la demande pour ce module et désactiver la fusion pour les appareils qui ne sont pas compatibles avec le téléchargement et l'installation d'APK divisés. Android Studio injecte les éléments suivants dans le fichier manifeste du module pour refléter votre choix :

      <dist:module ...>
    <dist:fusing dist:include="true | false" />
</dist:module>

  5. Une fois que vous avez terminé de configurer les options de téléchargement du module, cliquez sur Terminer.

Notez que le plug-in Android Gradle ne permet pas l'exécution de lint à partir des modules de fonctionnalités dynamiques. L'exécution de l'outil lint à partir du module d'application correspondant permet d'exécuter l'outil lint sur ses modules de fonctionnalités dynamiques et d'inclure tous les problèmes dans le rapport d'analyse lint de l'application.

Ajouter des options de distribution conditionnelle à un module de fonctionnalité existant

Vous pouvez facilement ajouter des options de distribution conditionnelle à un module de fonctionnalité existant via le fichier manifeste du module. Cependant, vous devez d'abord vous informer sur la compatibilité des options de distribution conditionnelle avec d'autres options de distribution que vous avez peut-être déjà activées.

Pour commencer, vous devez migrer le fichier manifeste vers le nouvel élément <dist:delivery>. L'extrait de code ci-dessous est un exemple de l'ancienne syntaxe :

<!-- This is the old syntax. -->
<dist:module
  dist:title="@string/feature_title" dist:onDemand="true">
  <dist:fusing dist:include="true"/>
</dist:module>

Les options de distribution ci-dessus sont désormais spécifiées comme suit.

<dist:module
  dist:title="@string/feature_title">
  <dist:delivery>
      <dist:on-demand/>
  </dist:delivery>
  <dist:fusing dist:include="true"/>
</dist:module>

Vous pouvez ensuite inclure des options de distribution conditionnelle en fonction des fonctionnalités de l'appareil, comme suit.

<dist:module
    dist:title="@string/feature_title">
    <dist:delivery>
      <dist:on-demand/>
      <dist:install-time>
        <dist:conditions>
          <!-- Requires that the device support AR to download the module at
          app install-time.  -->
          <dist:device-feature dist:name="android.hardware.camera.ar"/>
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
    <dist:fusing dist:include="true"/>
</dist:module>

Les sections ci-dessous présentent d'autres options de distribution conditionnelle, par exemple par pays ou par niveau d'API minimal.

Compatibilité avec les autres options de téléchargement de module

Étant donné que les modules de fonctionnalités offrent plusieurs options pour configurer la manière dont chaque fonctionnalité est distribuée sur l'appareil d'un utilisateur, il est important de comprendre comment d'autres paramètres affectent les options de distribution conditionnelle. Le tableau suivant présente brièvement la compatibilité de la distribution conditionnelle avec d'autres options de téléchargement de modules.

Option de téléchargement de module Compatibilité avec la distribution conditionnelle
Fusion (<dist:fusing dist:include="true"/>) Si un module définit cette option sur "true", Google Play ne respecte pas les options de distribution conditionnelle que vous spécifiez lorsque vous déployez votre application sur les appareils exécutant le niveau d'API 19 ou inférieur. Autrement dit, les modules de fonctionnalités qui activent la fusion sont toujours inclus au moment de l'installation pour les appareils exécutant le niveau d'API 19 ou inférieur.
Permettant une utilisation instantanée (<dist:module dist:instant="true"/>) Les options de distribution conditionnelle ne sont pas compatibles avec les modules de fonctionnalités permettant une utilisation instantanée.
À la demande (<dist:on-demand/>) Par défaut, si vous spécifiez des options de distribution conditionnelle, le module est également disponible à la demande.

Spécifier des conditions en fonction du pays

La distribution conditionnelle vous permet également de spécifier les pays que vous souhaitez empêcher (ou autoriser) à télécharger votre module au moment de l'installation de l'application. La définition de condition peut être utile si, par exemple, votre module implémente un mode de paiement indisponible dans certaines régions.

Dans ce contexte, le pays de l'appareil est généralement déterminé par l'adresse de facturation que l'utilisateur a enregistrée dans son compte Google Play.

Pour spécifier les pays non autorisés à télécharger votre module, incluez les éléments suivants dans le fichier manifeste du module de fonctionnalité.

<dist:conditions>
   <!-- Set to "true" to specify countries to exclude from downloading
   this module at app install-time. By default, modules are available
   for download to all user countries. -->
  <dist:user-countries dist:exclude="true">
    <!-- Specifies the two-letter  CLDR country code for regions that should
    not download the module at app install-time. -->
    <dist:country dist:code="CN"/>
    <dist:country dist:code="HK"/>
  </dist:user-countries>
</dist:conditions>

Spécifier des conditions pour le niveau d'API

Il peut être utile de spécifier une condition basée sur le niveau d'API d'un appareil si un module de fonctionnalité dépend d'API disponibles uniquement dans certaines versions de la plate-forme Android.

Pour définir une condition basée sur un niveau d'API minimal ou maximal, incluez les éléments suivants dans le fichier manifeste de votre module de fonctionnalité.

<dist:conditions>
    <!-- Specifies the minimum API level that the device must satisfy
         in order to download your module at app install-time. The API level you
         specify must be greater or equal to the module's own minSdkVersion. -->
   <dist:min-sdk dist:value="21"/>
    <!-- Specifies the maximum API level that the device cannot exceed
         in order to download your module at app install-time. The API level you
         specify must be less than or equal to the module's own maxSdkVersion. -->
   <dist:max-sdk dist:value="24"/>
</dist:conditions>