Ciblage par niveau d'appareil

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Qu'est-ce que le ciblage par niveau d'appareil ?

Le ciblage par niveau d'appareil vous permet de diffuser différentes versions (résolutions, etc.) du même élément sur les appareils en fonction de leur matériel. Par exemple, vous pouvez diffuser des éléments basse résolution sur des appareils bas de gamme pour améliorer les performances, et des éléments haute résolution sur des appareils haut de gamme. Cela permet d'améliorer la qualité graphique sans augmenter la taille globale du jeu en ne fournissant que les éléments nécessaires aux appareils des utilisateurs. Cette approche s'appuie sur le concept des packs d'éléments dans Asset Delivery. Comme vous le verrez ci-dessous, vous pouvez définir les critères de niveau (pour le moment en fonction de la RAM, des modèles d'appareils ou des fonctionnalités système disponibles) dans la limite de cinq niveaux.

Comme pour le service Play Asset Delivery, le ciblage par niveau d'appareil est compatible avec l'API 16 (Jelly Bean 4.1) et les versions ultérieures. Toutefois, sur les appareils avec le niveau d'API 19 (KitKat 4.4.X) ou inférieur, le niveau par défaut est fourni indépendamment du build de l'appareil.

Parcours du développeur

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

  1. Intégrez le ciblage par niveau d'appareil (et par extension, Play Asset Delivery) à votre jeu.
    • Intégrez Play Asset Delivery dans votre jeu (si vous ne l'avez pas déjà fait).
    • Divisez vos éléments en packs d'éléments.
    • Empaquetez le code et les éléments pour le dernier artefact Android App Bundle que vous importerez sur Play.
  2. Créez votre configuration de ciblage par niveau d'appareil pour que Play sache comment diffuser vos éléments 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 niveau d'appareil à Play.
    • Suivez les étapes de création de la configuration de ciblage par niveau d'appareil.
  3. Importez votre AAB sur Play et testez-le pour vous assurer que tout est correctement configuré.

Vous remarquerez que la première section du guide contient des duplications en fonction du système de compilation que vous utilisez. Le système que vous choisissez dépend du moteur que vous utilisez et de votre configuration existante.

  • Gradle (recommandé pour les jeux Java et natifs) : pour les jeux créés avec Gradle, suivez ces étapes afin de configurer le système de compilation et de développer ainsi un AAB compatible avec le ciblage par niveau d'appareil.
    • Si vous exportez votre jeu vers Gradle, puis que vous y terminez le build, nous vous recommandons de suivre ces instructions (par exemple, jeux Unity exportés vers Gradle).
  • Plug-in Unity : nous fournissons des packages d'unité à importer dans un projet Unity afin de configurer et de créer un AAB compatible avec le ciblage par niveau d'appareil.

Configurer le ciblage par niveau d'appareil dans votre application

Intégrer Play Asset Delivery dans votre jeu (si ce n'est pas déjà fait)

Play Asset Delivery (PAD) vous permet de fournir les éléments de votre jeu de manière dynamique au moment de l'installation ou de l'exécution. Vous pouvez consulter sa présentation ici. Avec le ciblage par niveau d'appareil, Play fournit des packs d'éléments en fonction des configurations que vous spécifiez pour différents niveaux d'appareils. Nous vous recommandons de suivre les conseils ci-dessous et d'intégrer PAD à votre jeu (par exemple, créer des packs d'éléments et implémenter la récupération dans votre jeu), puis de modifier le code du projet pour activer le ciblage par niveau d'appareil.

Gradle

Pour les jeux créés avec Gradle, suivez ces instructions afin de créer vos packs d'éléments avec Gradle, puis suivez les instructions pour intégrer la récupération des packs d'éléments dans votre jeu :

Unity

Pour les jeux créés dans Unity, vous devez configurer vos packs d'éléments à l'aide de la classe AssetPackConfig, comme indiqué dans ces instructions.

Créer des répertoires spécifiques au niveau de l'appareil

Si vous utilisez Gradle

Vous allez maintenant diviser vos éléments entre le nombre de niveaux (cinq maximum) que vous définirez ultérieurement. Pour créer les répertoires de transfert de données, utilisez les répertoires d'éléments existants conçus à la dernière étape, puis ajoutez au dossier approprié (comme décrit ci-dessous) les suffixes #tier_0, #tier_1, #tier_2. , etc. Lorsque vous utilisez les packs d'éléments dans votre jeu, vous n'avez pas besoin de traiter les dossiers avec des suffixes (en d'autres termes, le suffixe est automatiquement supprimé pendant le processus de compilation).

Après avoir effectué l'étape précédente, vous pouvez obtenir le résultat suivant :

...
.../level1/src/main/assets/character-textures#tier_2/
.../level1/src/main/assets/character-textures#tier_1/
.../level1/src/main/assets/character-textures#tier_0/
...

Lorsque vous accédez aux fichiers dans le dossier, vous pouvez simplement utiliser le même chemin d'accès sans avoir à ajouter de suffixe (dans cet exemple, vous accéderiez donc à level1/assets/character-textures/ sans aucun suffixe).

Si vous utilisez Unity

Pour ajouter un pack d'éléments qui utilise le ciblage par niveau d'appareil, vous pouvez appliquer les méthodes AssetPackConfig ci-dessous :

/// Package the specified raw assets in the specified folders,
/// keyed by DeviceTier, in an AssetPack with the specified delivery mode.
public void AddAssetsFolders(
    string assetPackName,
    IDictionary<DeviceTier, string> deviceTierToAssetPackDirectoryPath,
    AssetPackDeliveryMode deliveryMode)

/// Package the specified AssetBundle files, which vary only by DeviceTier,
/// in an AssetPack with the specified delivery mode.
public void AddAssetBundles(
    IDictionary<DeviceTier, string> deviceTierToAssetBundleFilePath,
    AssetPackDeliveryMode deliveryMode)

Par exemple, supposons que vous disposiez de trois AssetBundles pour votre personnage à différents niveaux de détail.

Pour mapper ces AssetBundles au niveau d'appareil correspondant, utilisez l'extrait suivant.

var assetPackConfig = new AssetPackConfig();
var tiers = new Dictionary<DeviceTier, string>
{
    {0, "Assets/LowPoly/Character"},
    {1, "Assets/Mid/Character"},
    {2, "Assets/Detailed/Character"}
};
assetPackConfig.AddAssetBundles(tiers, AssetPackDeliveryMode.OnDemand);

Créer le package Android App Bundle

Gradle

Dans le fichier build.gradle de votre projet, configurez vos dépendances de sorte qu'elles disposent des versions ci-dessous (ou ultérieures) pour le plug-in Android Gradle et bundletool :

buildscript {
  dependencies {
    classpath 'com.android.tools.build:gradle:4.2.0'
    classpath "com.android.tools.build:bundletool:1.7.1"
    ...
  }
  ...
}

Vous devez également mettre à jour Gradle pour qu'il utilise la version 6.7.1 ou une version ultérieure. Pour ce faire, procédez dans gradle/wrapper/gradle-wrapper.properties au sein de votre projet.

distributionUrl=https://services.gradle.org/distributions/gradle-6.7.1-all.zip

Enfin, vous devez mettre à jour votre bibliothèque Google Play Core pour qu'elle utilise la version 1.8.3 ou ultérieure. Nous vous recommandons de passer à la dernière version, si possible.

dependencies {
  implementation 'com.google.android.play:core:1.10.0'
  ...
}

Dans le fichier build.gradle du module d'application principal, activez la division d ciblage par niveau d'appareil :

android {
  bundle {
    deviceTier {
      enableSplit true
    }
    ...
  }
  ...
}

Enfin, vous pouvez créer votre Android App Bundle (AAB).

Bundletool

Créez votre bundle avec bundletool, puis à l'étape de personnalisation de l'AAB, ajoutez les lignes suivantes à votre fichier BundleConfig.pb.

{
  "value": "DEVICE_TIER",
  "negate": false,
  "suffixStripping": {
    "enabled": true,
  }
}

Unity

Une fois que vous avez configuré votre AssetPackConfig pour inclure les packs de transfert de données, vous pouvez transmettre cette configuration dans l'une des méthodes ci-dessous afin de créer votre AAB :

// Configures the build system to use the newly created assetPackConfig when
// calling Google > Build and Run or Google > Build Android App
Bundle.AssetPackConfigSerializer.SaveConfig(assetPackConfig);
// Alternatively, use BundleTool.BuildBundle to build an App Bundle from script
BuildBundle(new buildPlayerOptions(), assetPackConfig)

Test 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 (1.8.0 ou version ultérieure), créez et testez localement votre application, en spécifiant explicitement le niveau d'appareil approprié. Utilisez d'abord build-apks pour générer un ensemble de fichiers .apks, puis déployez votre application sur un appareil connecté à l'aide d'install-apks Vous pouvez également spécifier le niveau que vous souhaitez installer via l'indicateur "device-tier". 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 transfert de données et qu'elle ne contient donc pas encore l'indicateur device-tier).

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testingbundletool install-apks --apks=/path/to/app.apks --device-tier=1

Autre méthode : vous pouvez également utiliser extract-apks pour extraire un ensemble de fichiers APK pour un appareil spécifique. Cependant, l'utilisation de get-device-spec en même temps que la spécification du niveau pour cet appareil ne fonctionne pas conjointement avec l'indicateur --local-testing. Autrement dit, vous ne pourrez pas tester les packs d'éléments à distribution rapide ou à la demande.

bundletool get-device-spec --output=/path/to/device-spec.json --device-tier=1bundletool 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

Unity

L'option de menu Google -> Compiler et exécuter permet de créer et d'exécuter votre jeu avec l'indicateur --local-testing activé. Toutefois, elle ne vous permet pas de spécifier le niveau d'appareil transmis dans la commande install-apks.

Si vous souhaitez spécifier un niveau d'appareil autre que 0, procédez comme suit :

  1. Créez l'AAB à l'aide de l'option de menu Google -> Créer un Android App Bundle.
  2. Suivez les instructions de la section précédente pour exécuter bundletool, build-apks et install-apks sur l'AAB créé.

Créer une configuration de ciblage par niveau 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 niveau d'appareil (pour définir les exigences pour chaque niveau, par exemple), 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 (le cas échéant) et associez votre projet d'API à la Google Play Console.
  2. Configurez un client d'accès à l'API.

Découvrez la documentation de référence de l'API. Ultérieurement, si vous choisissez d'importer votre build via l'API, vous utiliserez les méthodes Edits. Nous vous recommandons également de consulter cette page avant d'utiliser l'API.

Utiliser l'API de configuration de niveau d'appareil

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

Créer une configuration de niveau 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 niveau d'appareil
Corps de la réponse Configuration du niveau d'appareil
Objet de configuration du niveau d'appareil

La définition des niveaux d'appareil se fait en deux étapes :

  1. Définissez un ensemble de groupes d'appareils.
  2. Définissez un ensemble de niveaux d'appareils en attribuant un niveau à vos groupes d'appareils.

Un groupe d'appareils est un ensemble d'appareils correspondant aux sélecteurs que vous définissez dans la configuration.

Ces sélecteurs peuvent définir les conditions requises concernant la RAM et le modèle d'appareil.

Les groupes sont identifiés par le nom de votre choix. Ils peuvent se chevaucher.

Ensuite, pour définir un ensemble de niveaux d'appareil, classez les groupes : chaque niveau d'appareil est défini par son niveau et un groupe d'appareils.

Si un appareil correspond à plusieurs niveaux, il recevra le contenu correspondant au niveau de correspondance le plus élevé.

  {
    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
              }
            ]
          }
        ]
      }
    ],
    device_tier_set: {
      device_tiers: [
        {
          level: int,
          device_group_names: [string]
        }
      ]
    }
  }

Champs :

  • device_confid_id (entier) : ID correspondant à la configuration du niveau de cet appareil
  • device_groups (objet) : définitions des groupes.

    • name (chaîne) : nom du groupe d'appareils (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, inclus) : quantité de RAM minimale requise (en octets).
      • max_bytes (entier, exclu) : quantité de RAM maximale requise (en octets).
    • included_device_ids (objet) : modèles d'appareils à inclure dans ce sélecteur (100 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-dessus sur la combinaison des conditions requises 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 (100 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 être pris en compte par ce sélecteur (100 fonctionnalités 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-dessus sur la combinaison des conditions requises 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 être pris en compte par ce sélecteur (100 fonctionnalités 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 conditions requises.

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

      • name (chaîne) : fonctionnalité système.
  • device_tiers (objet) : définitions du niveau.

    • level (entier) : niveau.
    • group_name (tableau de chaînes) : nom des groupes d'appareils appartenant à ce niveau.

Afin de déterminer la bonne mise en forme 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 identifiez 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.

Voici un exemple de configuration avec trois niveaux. Le niveau 2 utilise le groupe d'appareils supérieur (qui inclut tous les appareils de plus de 7 Go et le Pixel 4), le niveau 1 utilise le groupe d'appareils moyen (qui inclut tous les appareils compris entre 4 et 7 Go) et le niveau 0, qui est implicitement défini comme le groupe "valise".

{
  device_groups: [
    {
      name: 'high',
      device_selectors: [
        {
          device_ram: {
            min_bytes: 7516192768
          },
        },
        {
          included_device_ids: [
            {
              build_brand: 'google',
              build_device: 'flame'
            }
          ],
        }
      ]
    },
    {
      name: 'medium',
      device_selectors: [
        {
          device_ram: {
            min_bytes: 4294967296,
            max_bytes: 7516192768
          },
        }
      ]
    }
  ],
  device_tier_set: {
    device_tiers: [
      {
        level: 1,
        device_group_names: [
          'medium'
        ]
      },
      {
        level: 2,
        device_group_names: [
          'high'
        ]
      }
    ]
  }
}

Obtenir la configuration du niveau d'appareil via son ID

Vous pouvez récupérer une configuration de niveau d'appareil spécifique via un ID à l'aide de l'appel suivant :

Requête HTTP GET https://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
Corps de la réponse Configuration du niveau d'appareil

Obtenir la liste des configurations de niveau d'appareil

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

Requête HTTP GET https://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 spécifier un groupe spécifique de 10 configurations de niveau d'appareil. Cette option est utile si vous avez créé plus de 10 configurations de niveau d'appareil et que vous souhaitez afficher les configurations de niveau d'appareil créées avant les 10 plus récentes.
Corps de la requête N/A
Corps de la réponse Liste des configurations de niveau d'appareil

page_token

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 niveau d'appareil spécifique à votre build.

Il existe une présentation générale des méthodes Edits, ainsi que des 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 niveau d'appareil pour votre build, vous devrez ajouter l'ID de configuration au paramètre de requête deviceTierConfigId lors de l'appel de la méthode edits.bundle.upload, comme suit :

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 niveau d'appareil sera appliquée à votre app bundle.

Pour vérifier que votre package a été compilé correctement, accédez à l'explorateur d'app bundle (en veillant à ce que le build correct soit sélectionné) > Livraison, puis cliquez sur chaque pack d'éléments. Vous devriez voir que vous disposez du nombre de niveaux que vous avez créés. Cet exemple montre trois niveaux (0, 1 et 2) pour le pack d'éléments main_asset.

pack d'éléments avec trois niveaux

Vérifier que le niveau approprié est ciblé

Utilisez la méthode suivante pour vous assurer que seul le niveau approprié est transmis à l'appareil :

adb shell pm path {packageName}

Vous devriez obtenir un résultat semblable au suivant :

package:{...}/base.apk
package:{...}/split_config.en.apk
package:{...}/split_config.xxhdpi.apk
package:{...}/split_main_asset.apk
package:{...}/split_main_asset.config.tier_2.apk

Puis, associez une configuration de ciblage par niveau d'appareil à votre build.

Auxiliaire

Guide de démarrage rapide avec curl

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

  • Clé correspondant à votre client API
  • Nom du package de votre application

Commencez par créer une configuration de niveau d'appareil et notez le deviceTierConfigId que vous recevrez après un appel réussi.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ device_groups: [ { name: 'high', device_selectors: [ { device_ram: { min_bytes: 7516192768 }, }, { included_device_ids: [ { build_brand: 'google', build_device: 'flame' } ], } ] }, { name: 'medium', device_selectors: [ { device_ram: { min_bytes: 4294967296, max_bytes: 7516192768 }, } ] } ], device_tier_set: { device_tiers: [ { level: 1, device_group_names: [ 'medium' ] }, { level: 2, device_group_names: [ 'high' ] } ] } }" 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 niveau d'appareil en tant que 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="{dttConfigID}"

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 le créer en tant que version brouillon et de le 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}'</code>, <code><strong>versionCodes</strong></code>: <code>['{versionCode}']</code> <code><strong>}]}</strong></code>" <code>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