Ciblage des éléments par pays

En quoi consiste le ciblage des éléments par pays ?

Le ciblage des éléments par pays permet de diffuser différentes versions (par exemple, différentes résolutions) d'un même élément sur les appareils en fonction du pays dans lequel se trouve l'utilisateur. Par exemple, vous pouvez choisir de diffuser des éléments personnalisés dans différents pays où votre application est disponible, 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 des critères de ciblage comportant jusqu'à 20 pays. 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.

Comme pour Play Asset Delivery, le ciblage par pays est compatible avec Android 4.1 (niveau d'API 16) ou version ultérieure. Toutefois, sur les appareils équipés d'Android 4.4 (niveau d'API 19) ou version antérieure, l'ensemble de pays par défaut est desservi, quel que soit le pays de l'utilisateur.

Parcours du développeur

De manière générale, pour intégrer le ciblage par pays dans votre jeu existant, procédez comme suit :

  1. Intégrez le ciblage par pays (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 types 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 à Play.
    • Suivez les étapes de création de la configuration de ciblage.
  3. Importez votre AAB sur Play et testez-le pour vous assurer que tout est correctement configuré.

Gradle est le système de compilation recommandé pour Java et les jeux natifs. Pour les jeux créés avec Gradle, procédez comme suit afin de configurer le système de compilation et de développer un AAB compatible avec le ciblage par pays.

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

Configurer le ciblage des éléments par pays 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 pays, Play diffuse le contenu de vos packs d'éléments en fonction de la configuration des ensembles de pays pour différents emplacements utilisateur. Nous vous recommandons de suivre les conseils ci-dessous et d'intégrer PAD dans 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 pays.

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 :

Créer des répertoires propres aux ensembles de pays

Si vous utilisez Gradle

Vous allez maintenant diviser les éléments entre les ensembles de pays (20 maximum) que vous définirez ultérieurement. Pour créer des répertoires ciblés, basez-vous sur les répertoires de bundles d'éléments existants conçus à la dernière étape, puis ajoutez au dossier approprié (comme décrit ci-dessous) les #countries_latam, #countries_na, 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#countries_latam/
.../level1/src/main/assets/character-textures#countries_na/
.../level1/src/main/assets/character-textures/
...

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

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:8.1.0-alpha01'
    classpath "com.android.tools.build:bundletool:1.14.0"
    ...
  }
  ...
}

Vous devez également mettre à jour Gradle pour qu'il utilise la version 8.0 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-8.0-rc-1-all.zip

Enfin, vous devez utiliser la bibliothèque Play Asset Delivery. Si vous utilisez toujours la bibliothèque monolithique Play Core, passez à la version 1.8.3 ou ultérieure. Nous vous recommandons de passer à la bibliothèque Play Asset Delivery et, si possible, d'installer la dernière version.

dependencies {
  implementation 'com.google.android.play:asset-delivery:2.0.1'
  ...
}

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

android {
  bundle {
    countrySet {
      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.

{
  ...
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [
      ...
      {
        "value": "COUNTRY_SET",
        "negate": false,
        "suffixStripping": {
          "enabled": true,
        }
      }],
    }
  }
}

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 (version 1.14.0 ou ultérieure), vous pouvez créer et tester en local votre application, en indiquant explicitement le pays 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 l'ensemble de pays que vous souhaitez installer via l'indicateur country-set. 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 country-set).

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testing
bundletool install-apks --apks=/path/to/app.apks --country-set=latam

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 pays 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 --country-set=latam
bundletool 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 pays (et donc définir des ensembles de pays), 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) votre projet d'API et associez-le à 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 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
{
  "user_country_sets": [
    {
      "name": "latam",
      "country_codes": [
        "AR",
        "BR",
        ...
      ]
    },
    {
      "name": "sea",
      "country_codes": [
        "VN",
        "TW",
        ...
      ]
    }
  ]
}

Champs :

  • device_confid_id (entier) : ID correspondant à la configuration du ciblage par types d'appareil.
  • user_country_sets (objet) : définitions des ensembles de pays.
    • name (chaîne) : nom de l'ensemble de pays (ID de chaîne que vous définissez).
    • country_codes (chaîne) : pays appartenant à l'ensemble de pays (format : ISO 3166-1 alpha-2).

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 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
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 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 définir 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
Contenu de la réponse Liste des configurations de ciblage par types d'appareil

page_token

Valider la 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.

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

Avec bundletool evaluate-device-targeting-config, vous pouvez déterminer quel pays correspond à un appareil spécifique. Vous pouvez indiquer le pays de l'utilisateur à l'aide de l'indicateur --country-code.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device --country-code=AR

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 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 ciblage par types 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.

Vérifier que les éléments appropriés sont diffusés

Utilisez la méthode suivante pour vous assurer que seuls les éléments appropriés sont envoyés à 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.countries_latam.apk

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 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 "{ "user_country_sets": [ { "name": "latam", "country_codes": [ "AR", "BR" ] }, { "name": "sea", "country_codes": [ "VN", "TW" ] } ] }" 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 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="{deviceTargetingConfigID}"

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