Segmentación de recursos por país

¿Qué es la segmentación de recursos por país?

La segmentación de recursos por país te permite publicar diferentes versiones (como resoluciones) del mismo recurso en dispositivos según el país en el que se encuentre el usuario. Por ejemplo, puedes optar por publicar recursos personalizados para diferentes países en los que está disponible tu app, sin incurrir en ningún aumento en el tamaño general del juego. Para ello, solo publica los recursos necesarios en los dispositivos de los usuarios. Esto se basa en el concepto de paquetes de recursos de Asset Delivery en Play. Como verás a continuación, puedes definir los criterios de segmentación con hasta 20 conjuntos de países. En este contexto, el país del dispositivo generalmente está determinado por la dirección de facturación del usuario registrada en su cuenta de Google Play.

Al igual que Play Asset Delivery, la segmentación por país admite Android 4.1 (nivel de API 16) y versiones posteriores. Sin embargo, en dispositivos con Android 4.4 (nivel de API 19) o versiones anteriores, se entrega el conjunto de países predeterminado, independientemente de la ubicación del usuario.

Exploración del desarrollador

En términos generales, para integrar la segmentación por país en tu juego existente, sigue estos pasos:

1. Integra la segmentación por país (y por extensión, Play Asset Delivery) en tu juego.
   • Integra Play Asset Delivery en tu juego (si aún no lo hiciste).
   • Divide los recursos en paquetes de recursos.
   • Empaqueta los recursos y el código juntos para obtener el artefacto final de Android App Bundle que subirás a Play.
2. Crea la configuración de segmentación por dispositivo de modo que Play sepa cómo entregar tus recursos a los dispositivos de los usuarios.
   • Configura la API de Google Play Developer (si aún no lo hiciste), que es lo que usarás para enviar la configuración de la segmentación a Play.
   • Sigue los pasos para crear la configuración de la segmentación.
3. Sube tu AAB a Play y realiza pruebas a fin de asegurarte de que todo esté configurado correctamente.

Gradle es el sistema de compilación recomendado para Java y juegos nativos. En el caso de los juegos compilados con Gradle, sigue estos pasos para configurar el sistema de compilación para compilar tu AAB compatible con la orientación por país.

Si exportas tu juego a Gradle y, luego, terminas tu compilación allí, te recomendamos que sigas estas instrucciones (p. ej., Juegos de Unity exportados a Gradle).

Cómo configurar la segmentación de recursos por país en tu app

Cómo integrar Play Asset Delivery en tu juego (si aún no lo hiciste)

Play Asset Delivery (PAD) te permite enviar de manera dinámica los recursos de tu juego al momento de la instalación o durante el tiempo de ejecución. Puedes leer una descripción general sobre este proceso aquí. Con la segmentación por país, Play entregará el contenido de tus paquetes de recursos en función de las configuraciones de país establecidas para diferentes ubicaciones de usuario. Te recomendamos que sigas las instrucciones que se indican a continuación y que integres PAD en tu juego (es decir, que crees paquetes de recursos e implementes la recuperación en tu juego) y, luego, que modifiques el código del proyecto para habilitar la segmentación dispositivo.

Gradle

En el caso de los juegos compilados con Gradle, usa estas instrucciones para compilar paquetes de recursos con Gradle y, luego, sigue las instrucciones para integrar la recuperación de paquetes de recursos en tu juego:

• Java
• Nativo
• Juegos de Unity exportados a Gradle
  • Usa las bibliotecas de Java a través de la JNI (como la que está integrada en Unity).

Crea directorios específicos configurados por país

Si usas Gradle

Ahora dividirás los elementos entre los conjuntos de países (máx. 20) que definirás más adelante. Para crear tus directorios segmentados, toma los directorios del paquete de recursos existentes que creaste en el último paso y publica la corrección adecuada en la carpeta (como se describe a continuación) con #countries_latam, #countries_na, etc. Cuando uses los paquetes de recursos de tu juego, no necesitarás abordar las carpetas por postfijo (en otras palabras, el postfijo se quita automáticamente durante el proceso de compilación).

Después del paso anterior, podría verse así:

...
.../level1/src/main/assets/character-textures#countries_latam/
.../level1/src/main/assets/character-textures#countries_na/
.../level1/src/main/assets/character-textures/
...

Cuando accedes a los archivos de la carpeta, puedes usar la misma ruta de acceso sin los sufijos (en este ejemplo, nos referiríamos a level1/assets/character-textures/ sin postfijos).

Cómo compilar el Android App Bundle

Gradle

En el archivo build.gradle del proyecto, configura las dependencias de modo que tengan las siguientes versiones (o alguna posterior) del complemento de Android para Gradle y bundletool:

buildscript {
  dependencies {
    classpath 'com.android.tools.build:gradle:8.1.0-alpha01'
    classpath "com.android.tools.build:bundletool:1.14.0"
    ...
  }
  ...
}

También deberás actualizar tu versión de Gradle a 8.0 o una posterior. Puedes actualizar esto en gradle/wrapper/gradle-wrapper.properties dentro de tu proyecto.

distributionUrl=https://services.gradle.org/distributions/gradle-8.0-rc-1-all.zip

Por último, deberás usar la Biblioteca de Play Asset Delivery. Si todavía usas la biblioteca monolítica de Play Core, actualízala a la versión 1.8.3 o a una posterior. Recomendamos cambiar a la Biblioteca de Play Asset Delivery y actualizar a la versión más reciente si es posible.

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

En el archivo build.gradle del módulo de app principal, habilita la división de segmentación por país:

android {
  bundle {
    countrySet {
      enableSplit true
    }
    ...
  }
  ...
}

Por último, puedes compilar tu Android App Bundle (AAB).

• Android Studio
• CLI

Bundletool

Compila tu paquete con bundletool y, durante el paso para personalizar tu AAB, agrega lo siguiente a tu archivo BundleConfig.pb.

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

Cómo realizar pruebas locales

Antes de continuar, te recomendamos que pruebes tu paquete de aplicación de forma local a fin de asegurarte de que todo esté configurado de manera correcta. Con bundletool (1.14.0 o versiones posteriores), compilarás y probarás la app de forma local y especificarás de forma explícita el país correcto. Primero, usarás build-apks para generar un conjunto de archivos .apks y, luego, implementarás tu app en un dispositivo conectado usando install-apks. También puedes especificar el país que deseas instalar mediante la marca country-set. Puedes encontrar más información sobre este método de pruebas locales aquí. Ten en cuenta que esta página aún no se actualizó para la segmentación y, por lo tanto, falta la marca de 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

Otra alternativa: También puedes usar extract-apks para extraer un conjunto de APK para un dispositivo específico. Sin embargo, el uso de get-device-spec junto con la especificación del país del dispositivo en cuestión, no funciona junto con la marca de --local-testing, lo que significa que no podrás probar los paquetes de recursos de seguimiento rápido o a pedido.

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

Cómo crear una configuración de segmentación por dispositivo a través de la API de Google Play Developer

Cómo comenzar a usar la API de Google Play Developer (si aún no lo hiciste)

Para configurar la segmentación por país (es decir, definir tus conjuntos de países), deberás usar la API de Android Publisher para subir la configuración a Google Play. Puedes obtener más información sobre la API en el vínculo de arriba. Hay algunos pasos que deberás seguir para comenzar:

1. Crea tu proyecto de API (si es necesario) y vincúlalo a Google Play Console.
2. Configura un cliente de acceso a la API.

Puedes encontrar la referencia de la API aquí. Más adelante, si eliges subir tu compilación a través de la API, usarás los métodos de edición. Además, te recomendamos que revises esta página antes de usar la API.

Cómo usar la API de configuración de la segmentación por dispositivo

Puedes usar la siguiente llamada a la API para crear la configuración de la segmentación por dispositivo:

Cómo crear la configuración de segmentación por dispositivo

Solicitud HTTP	POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Parámetros de ruta de acceso	N/A
Cuerpo de la solicitud	Configuración de la segmentación por dispositivo
Cuerpo de la respuesta	Configuración de la segmentación por dispositivo

Objeto de la configuración de segmentación por dispositivo

{
  "user_country_sets": [
    {
      "name": "latam",
      "country_codes": [
        "AR",
        "BR",
        ...
      ]
    },
    {
      "name": "sea",
      "country_codes": [
        "VN",
        "TW",
        ...
      ]
    }
  ]
}

Campos:

• device_confid_id (número entero): ID correspondiente a la configuración de segmentación por dispositivo
• user_country_sets (objeto): Definiciones de los conjuntos de países
  • name (cadena): Nombre del país establecido (un ID de cadena que definas)
  • country_codes (cadena): Países que pertenecen a este conjunto de países (formato: ISO 3166-1 alpha-2)

Puedes seguir las instrucciones que aparecen a continuación para validar tu configuración de segmentación por dispositivo antes de subirla a Google Play.

Cómo obtener la configuración de la segmentación por dispositivo según el ID

Puedes recuperar una configuración de la segmentación por dispositivo específica según el ID mediante la siguiente llamada:

Solicitud HTTP	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
Parámetros de ruta de acceso	N/A
Cuerpo de la solicitud	N/A
Cuerpo de la respuesta	Configuración de la segmentación por dispositivo

Cómo obtener una lista de configuraciones de segmentación por dispositivo

Puedes obtener las últimas 10 configuraciones de la segmentación por dispositivo mediante la siguiente llamada (o idealmente especifica un conjunto de diez mediante el parámetro de consulta page_token):

Solicitud HTTP	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Parámetros de ruta de acceso	N/A
Parámetros de búsqueda	page_token (opcional): Se usa para especificar un grupo determinado de 10 DTC. Esto resulta útil si creaste más de 10 DTC y deseas ver aquellas creadas antes de las 10 más recientes.
Cuerpo de la solicitud	N/A
Cuerpo de la respuesta	Lista de configuraciones de segmentación por dispositivo page_token

Cómo validar la configuración de la segmentación por dispositivo

bundletool incluye dos comandos que te ayudan a validar que tu configuración de segmentación por dispositivo funcione según lo previsto antes de subirla a Play.

Con bundletool print-device-targeting-config, puedes validar que tu archivo JSON sea sintácticamente correcto.

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

Con bundletool evaluate-device-targeting-config, puedes evaluar qué conjunto de países coincidiría con un dispositivo específico. Puedes proporcionar el país del usuario a través de la marca --country-code.

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

Cómo subir tu Android App Bundle a Google Play

Mediante la API

Puedes usar la API de Google Play Developer a fin de subir tu Android App Bundle a Google Play y vincular una configuración específica de segmentación por dispositivo a la compilación.

Aquí se presenta una descripción general de los métodos de edición junto con ejemplos más detallados sobre el lanzamiento en los diferentes segmentos en Google Play Console (para el último vínculo, te recomendamos que uses APIs compatibles con AAB en lugar de APIs compatibles con APK, las cuales se enumeran en la página). Si quieres especificar la configuración de segmentación por dispositivo para tu compilación, debes agregar el ID de configuración al parámetro de búsqueda deviceTierConfigId mientras llamas al método edits.bundle.upload, de esta manera:

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

Mediante Google Play Console

Puedes seguir estas instrucciones para subir el Android App Bundle. Se aplicará la configuración de la DTC más reciente a tu Android App Bundle.

Verifica que se publiquen los elementos correctos

Usa el siguiente método para asegurarte de que solo se entreguen los recursos correctos al dispositivo.

adb shell pm path {packageName}

Deberías ver algo como lo siguiente:

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

Información auxiliar

Guía de inicio rápido para Curl

A continuación, se muestra un ejemplo (que usa la herramienta de línea de comandos curl) para crear una nueva configuración de segmentación por dispositivo y usar la API de edición para crear una edición nueva, subir un AAB nuevo (y asociarlo a una configuración de segmentación por dispositivo específica), establecer la configuración del segmento y la versión, y confirmar la edición (por lo tanto, harás público el cambio). Asegúrate de tener la ubicación de los siguientes datos:

• La clave correspondiente a tu cliente de la API
• El nombre del paquete de tu app

Primero, crea una configuración de la segmentación por dispositivo y toma nota del deviceTierConfigId que recibirás cuando se realice una llamada con éxito.

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

Inicia una edición: Recibirás un ID y una hora de vencimiento para la edición. Guarda el ID para las siguientes llamadas.

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

Sube el AAB y especifica la configuración de segmentación por dispositivo como un parámetro de búsqueda. Si la llamada se realiza correctamente, verás un código de versión y los SHA1 y SHA256 de la compilación. Guarda el código de versión para la próxima llamada.

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}"

Asigna el AAB al segmento deseado (para las pruebas, te recomendamos que uses el segmento de pruebas internas, pero puedes obtener más información sobre los distintos segmentos aquí). Este es un lanzamiento sencillo sin notas de la versión, pero puedes leer esta página para obtener más información sobre el lanzamiento en etapas, las versiones en borrador y las notas de la versión. Si es la primera vez que usas la API de Publisher, te recomendamos que crees esta versión como una en borrador y que la completes en Google Play Console para asegurarte de que todo se haya configurado correctamente.

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}

Confirma los cambios (hazlo con cuidado, ya que esto permitirá que todos los cambios se publiquen en Play en el segmento deseado).

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