Ciblage par types d'appareil pour les modules conditionnels

Qu'est-ce que le ciblage par types d'appareil pour les modules conditionnels ?

Le ciblage par types d'appareil vous permet de proposer des modules de fonctionnalités conditionnels aux appareils en fonction de leur matériel. Par exemple, vous pouvez choisir de distribuer certaines fonctionnalités uniquement aux appareils haut de gamme et de ne pas les distribuer aux appareils qui ne peuvent pas utiliser cette fonctionnalité (par exemple, économiser de l'espace sur ces appareils). Cette approche repose sur le concept des modules de fonctionnalités de Play Feature Delivery. Comme vous le verrez ci-dessous, vous pouvez définir les critères de ciblage (pour le moment en fonction de la RAM, des modèles d'appareils ou des fonctionnalités système disponibles) et cibler des modules sur des groupes d'appareils spécifiques.

Parcours du développeur

De manière générale, pour intégrer le ciblage par types d'appareil dans votre application existante, vous devez suivre les étapes suivantes :

  1. Développez une fonctionnalité que vous ne souhaitez distribuer qu'à un ensemble d'appareils en fonction de leur matériel.
    • Implémentez cette fonctionnalité en tant que module de fonctionnalité.
    • Spécifiez dans la section des conditions du module du fichier AndroidManifest.xml les groupes d'appareils auxquels les diffuser.
  2. Créez votre configuration de ciblage par types d'appareil afin de permettre à Play de savoir comment diffuser vos modules de fonctionnalités sur les appareils des utilisateurs.
    • Configurez l'API Google Play Developer (si ce n'est pas déjà fait) que vous utiliserez pour envoyer les configurations de ciblage par types d'appareil à Play.
    • Suivez les étapes de création de la configuration de ciblage par types d'appareil.
  3. Importez votre AAB sur Play et testez-le pour vous assurer que tout est correctement configuré

Ce document explique comment ajouter le ciblage par types d'appareil à la diffusion conditionnelle à l'aide du plug-in Android Gradle.

Créer un module de fonctionnalités conditionnel avec le ciblage par types d'appareil

Ajouter un module de fonctionnalités à l'application

Play Feature Delivery vous permet de distribuer certaines fonctionnalités de votre application de manière conditionnelle ou de les télécharger à la demande. Pour en savoir plus, cliquez ici. Le ciblage par types d'appareil vous permet de distribuer une fonctionnalité de manière conditionnelle aux appareils attribués aux groupes fournis.

Pour utiliser le ciblage par types d'appareil pour la livraison conditionnelle, vous devez utiliser bundletool version 1.7.0 ou ultérieure. Pour ce faire, vous devez spécifier explicitement la version de bundletool pour le plug-in Android Gradle, dans la section buildscript du fichier racine build.gradle :

buildscript {
  dependencies {
    classpath "com.android.tools.build:bundletool:1.7.0"
    ...
  }
  ...
}

Pour créer un module de fonctionnalités, suivez ces instructions afin de modulariser une application Android.

Une fois le développement de la fonctionnalité terminé, vous pouvez spécifier des conditions de diffusion en fonction du ciblage par types d'appareil dans le fichier AndroidManifest.xml de votre fonctionnalité. Vous devez fournir une condition de groupe d'appareils dans dist:conditions de dist:module. Des informations générales sur les conditions sont disponibles sur cette page. Pour les groupes d'appareils, de nouvelles conditions vous permettent de spécifier tous les groupes auxquels cette fonctionnalité doit être distribuée :

<dist:device-groups>
  <dist:device-group dist:name="..." />
  <dist:device-group dist:name="..." />
  ...
</dist:device-groups>

Par exemple, imaginons que vous ayez défini un groupe d'appareils appelé "_my_group1" (vous découvrirez comment le définir dans la section Créer une configuration de ciblage par types d'appareil ci-dessous). Si le module de fonctionnalité ne doit être diffusé que sur des appareils appartenant à _my_group1, son AndroidManifest.xml doit se présenter comme suit :

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

Pour une caractéristique qui cible à la fois _my_group1 et _my_group2, son AndroidManifest.xml se présente comme suit :

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
            <dist:device-group dist:name="my_group_2"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

Une fois cela fait, vous pouvez créer votre Android App Bundle (AAB).

Tester en local

Avant de continuer, nous vous recommandons de tester localement votre app bundle pour vous assurer que tout est correctement configuré. À l'aide de bundletool, vous créez et testez votre application localement, en spécifiant le bon groupe d'appareils. Vous allez d'abord utiliser build-apks pour générer un ensemble de fichiers .apks, puis déployer votre application sur un appareil connecté à l'aide de install-apks. Vous pouvez également spécifier le ou les groupes que vous souhaitez installer via l'indicateur device-groups. Pour en savoir plus sur cette méthode de test local, cliquez ici. Notez que cette page n'a pas encore été mise à jour pour le ciblage par types d'appareil et qu'elle ne comporte donc pas l'indicateur device-groups.

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testingbundletool install-apks --apks=/path/to/app.apks --device-groups=my_group_1,my_group_2

Vous pouvez également utiliser extract-apks afin d'extraire un ensemble d'APK pour un appareil spécifique (à l'aide de get-device-spec et spécifier les groupes d'appareils de cet appareil).

bundletool get-device-spec --output=/path/to/device-spec.json --device-groups=my_group_1,my_group_2bundletool extract-apks --apks=/path/to/existing_APK_set.apks --output-dir=/path/to/device_specific_APK_set.apks --device-spec=/path/to/device-spec.json

Créer une configuration de ciblage par types d'appareil via l'API Google Play Developer

Premiers pas avec l'API Google Play Developer (si ce n'est pas déjà fait)

Pour configurer le ciblage par types d'appareil (définir vos groupes d'appareils), vous devez utiliser l'API Android Publisher afin d'importer votre configuration dans Google Play. Pour en savoir plus sur l'API, cliquez sur le lien ci-dessus. Pour commencer, vous devez suivre quelques étapes :

  1. Créez (si nécessaire) et associez votre projet d'API à la Google Play Console.
  2. Configurez un client d'accès aux API.

Vous trouverez la documentation de référence de l'API sur cette page. Si vous choisissez d'importer votre compilation via l'API par la suite, vous utiliserez la méthode Edits. Nous vous recommandons également de consulter cette page avant d'utiliser l'API.

Utiliser l'API de configuration du ciblage par types d'appareil

Vous pouvez utiliser l'appel d'API suivant pour créer votre configuration de ciblage par types d'appareil :

Créer une configuration de ciblage par types d'appareil

Requête HTTP : POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Paramètres du chemin d'accès N/A
Corps de la requête Configuration du ciblage par types d'appareil
Contenu de la réponse Configuration du ciblage par types d'appareil
Objet de configuration du ciblage par types d'appareil
{
  device_groups: [
    {
      name: string,
      device_selectors: [
        {
          device_ram : {
            min_bytes: integer
            max_bytes: integer
          },
          included_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          excluded_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          required_system_features: [
            {
              name: string
            }
          ],
          forbidden_system_features: [
            {
              name: string
            }
          ]
        }
      ]
    }
  ]
}

Champs :

  • device_tier_config_id (entier) : ID correspondant à cette configuration de ciblage par types d'appareil.
  • device_groups (objet) : définitions des groupes.

    • name (chaîne) : nom du groupe d'appareils (un identifiant de chaîne que vous définissez).
    • device_selectors (objet) : configuration requise pour qu'un appareil appartienne à ce groupe.
    • device_ram (objet) : configuration requise pour la RAM de l'appareil.
      • min_bytes (entier) : quantité de RAM minimale requise (en octets).
      • max_bytes (entier) : quantité de RAM maximale requise (en octets).
    • included_device_ids (objet) : modèles d'appareils à inclure dans ce sélecteur (1 000 device_ids par groupe au maximum). Un appareil doit figurer dans cette liste pour correspondre au sélecteur. Il s'agit d'une condition nécessaire, mais pas suffisante, pour correspondre au sélecteur complet (voir la remarque ci-dessous sur la combinaison des exigences dans un sélecteur).
      • build_brand (chaîne) : fabricant de l'appareil.
      • build_device (chaîne) : code du modèle de l'appareil.
    • excluded_device_ids (objet) : modèles d'appareils à exclure dans ce sélecteur (1 000 device_ids par groupe au maximum). Un appareil de cette liste ne correspondra pas au sélecteur, même s'il répond à toutes les autres exigences du sélecteur.
      • build_brand (chaîne) : fabricant de l'appareil.
      • build_device (chaîne) : code du modèle de l'appareil.
    • required_system_features (objet) : fonctionnalités qu'un appareil doit avoir pour rejoindre ce sélecteur (100 caractéristiques maximum par groupe). Un appareil doit disposer de toutes les fonctionnalités système de cette liste pour correspondre au sélecteur. Il s'agit d'une condition nécessaire, mais pas suffisante, pour correspondre au sélecteur complet (voir la remarque ci-dessous sur la combinaison des exigences dans un sélecteur).

      Référence des fonctionnalités système

      • name (chaîne) : fonctionnalité système.
    • forbidden_system_features (objet) : fonctionnalités dont l'appareil ne doit pas être équipé pour rejoindre ce sélecteur (100 caractéristiques maximum par groupe). Si un appareil possède l'une des fonctionnalités système de cette liste, il ne correspond pas au sélecteur, même s'il répond à toutes les autres exigences de ce dernier.

      Référence des fonctionnalités système

      • name (chaîne) : fonctionnalité système.

Pour trouver le bon formatage pour le fabricant de l'appareil et le code du modèle, utilisez le catalogue d'appareils dans la Google Play Console en suivant l'une de ces méthodes :

  • Inspectez les appareils individuels à l'aide du catalogue d'appareils, et trouvez le fabricant et le code du modèle aux emplacements indiqués dans l'exemple ci-dessous. (Pour un Google Pixel 4a, le fabricant est "Google" et le code du modèle est "sunfish".)

    page du Pixel 4a dans le catalogue d'appareils

    page du Pixel 4a dans le catalogue d'appareils

  • Téléchargez un fichier CSV des appareils compatibles, et utilisez le fabricant et le code du modèle pour les champs build_brand et build_device, respectivement.

Par exemple, le groupe suivant correspond à tous les appareils disposant de plus de 4 Go de RAM, à l'exception du Pixel 5 (Google Redfin) et du Pixel 3 (Google Blueline, qui dispose de moins de 4 Go de RAM).

device_groups: [
  {
    name: "my_group_1",
    device_selectors: [
      {
        device_ram: {
          min_bytes: 4294967296
        },
        excluded_device_ids: [
          {
            build_brand: "google",
            build_device: "redfin"
          }
        ]
      },
      {
        included_device_ids: [
          {
            build_brand: "google",
            build_device: "blueline"
          }
        ]
      }
    ]
  }
]

Vous pouvez le lire comme suit :

[ (RAM > 4GB) AND NOT (google redfin) ] OR [ (google blueline) ]

Vous pouvez suivre les instructions ci-dessous pour valider votre configuration de ciblage par types d'appareil avant de l'importer dans Google Play.

Obtenir la configuration du ciblage par types d'appareil par ID

Vous pouvez récupérer une configuration de ciblage par types d'appareil spécifique par ID à l'aide de l'appel suivant :

Requête HTTP : GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
Paramètres du chemin d'accès N/A
Corps de la requête N/A
Contenu de la réponse Configuration du ciblage par types d'appareil

Obtenir la liste des configurations de ciblage par types d'appareil

Vous pouvez obtenir les 10 dernières configurations de ciblage par types d'appareil grâce à l'appel suivant (ou spécifiez de manière optimale un ensemble de 10 configurations à l'aide du paramètre de requête page_token) :

Requête HTTP : GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Paramètres du chemin d'accès N/A
Paramètres de requête page_token (facultatif) : permet de définir un groupe spécifique de 10 configurations de ciblage par types d'appareil. Cette option est utile si vous avez créé plus de 10 configurations de ciblage par types d'appareil et souhaitez afficher les configurations de ciblage par types d'appareil créés avant les 10 les plus récents.
Corps de la requête N/A
Contenu de la réponse Liste des configurations de ciblage par types d'appareil

page_token

Valider votre configuration de ciblage par types d'appareil

bundletool inclut deux commandes qui vous aident à valider votre configuration de ciblage par types d'appareil en attestant qu'elle fonctionne comme prévu avant de l'importer dans Play.

bundletool print-device-targeting-config vous permet de confirmer que la syntaxe de votre fichier JSON est correcte et de visualiser vos groupes d'appareils dans un format plus lisible.

bundletool print-device-targeting-config --config=mydtc.json

bundletool evaluate-device-targeting-config vous permet d'évaluer quels groupes correspondent à un appareil spécifique. Soit vous connectez votre appareil cible à votre station de travail et vous utilisez l'indicateur --connected-device, soit vous compilez manuellement un fichier JSON avec les propriétés de l'appareil et vous le fournissez via l'indicateur --device-properties.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device
bundletool evaluate-device-targeting-config --config=mydtc.json --device-properties=deviceproperties.json

Le fichier de propriétés de l'appareil doit être au format JSON suivant la structure protobuf DeviceProperties. Exemple :

{
  "ram": 2057072640,
  "device_id": {
    "build_brand":"google",
    "build_device":"redfin"
  },
  "system_features": [
    {
      "name":"android.hardware.bluetooth"
    },
    {
      "name":"android.hardware.camera"
    }
  ]
}

Importer votre Android App Bundle dans Google Play

Via l'API

Vous pouvez utiliser l'API Google Play Developer pour importer votre Android App Bundle dans Google Play et associer une configuration de ciblage par types d'appareil spécifique à votre compilation.

Il existe une présentation générale des méthodes Edits, ainsi quedes exemples plus détaillés concernant la publication sur les différents canaux dans la Google Play Console (pour le dernier lien, utilisez l'API compatible avec l'AAB au lieu de l'API compatible avec l'APK listées sur la page). Pour spécifier la configuration du ciblage par types d'appareil pour votre compilation, vous devrez ajouter l'ID de configuration aux paramètres de requête deviceTierConfigId lors de l'appel de la méthodeedits.bundle.upload :

https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editId}/bundles?deviceTierConfigId="{deviceTierConfigId}"

Via la Google Play Console

Pour importer votre fichier Android App Bundle, suivez ces instructions. La dernière configuration de ciblage par types d'appareil sera appliquée à votre app bundle.

Auxiliaire

Guide de démarrage rapide avec curl

Vous trouverez ci-dessous un exemple (à l'aide de l'outil de ligne de commande curl) de création d'une configuration de ciblage par types d'appareil, et d'utilisation de l'API Edits pour apporter une nouvelle modification, importer un fichier AAB (en l'associant à une configuration de ciblage par types d'appareil spécifique), et définir la configuration de suivi/sortie et valider la modification (et ainsi rendre la modification publique). Assurez-vous d'avoir l'emplacement de :

  • La clé correspondant à votre client API
  • Le nom du package de votre application

Commencez par créer une configuration de ciblage par types d'appareil et notez le deviceTierConfigId que vous recevrez une fois l'appel réussi.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ device_groups: [ { name: "my_group_1", device_selectors: [ { device_ram: { min_bytes: 4294967296 }, excluded_device_ids: [ { build_brand: "google", build_device: "redfin" } ] }, { included_device_ids: [ { build_brand: "google", build_device: "blueline" } ] } ] } ] }" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs

Lancer une modification : vous obtenez un ID et un délai d'expiration pour la modification. Enregistrez l'ID pour les appels suivants.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits

Importez l'AAB, en spécifiant la configuration du ciblage par types d'appareil (deviceTierConfigId) comme paramètre de requête. Si l'appel aboutit, un code de version de la compilation (sha1 et sha256) apparaîtra. Enregistrez le code de version pour l'appel suivant.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" --data-binary @$HOME/{aabFile} -H "Content-Type: application/octet-stream" -XPOST https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editID}/bundles?deviceTierConfigId="{deviceTierConfigId}

Attribuez l'AAB au canal souhaité. Pour les tests, il est recommandé d'utiliser le canal de test interne, mais vous pouvez en apprendre davantage sur les différents canaux ici. Il est question ici d'effectuer un déploiement simple sans notes de version, mais vous pouvez lire cette page pour en savoir plus sur les déploiements par étapes, les versions brouillon et les notes de version. Si vous utilisez l'API Publisher pour la première fois, nous vous recommandons de la créer en tant que version brouillon et de la finaliser dans la Google Play Console pour vous assurer que tout a été correctement configuré.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPUT -H "Content-Type: application/json" -d "{ releases: [{status: '{status}', versionCodes: ['{versionCode}'] }]}" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}/tracks/{track}

Validez les modifications (procédez avec prudence, car toutes les modifications apparaîtront sur Play pour le canal souhaité).

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}:commit