Segmentación por dispositivo para módulos condicionales

¿Qué es la segmentación por dispositivo para módulos condicionales?

La segmentación por dispositivo (DT) te permite publicar módulos de funciones condicionales en los dispositivos según su hardware. Por ejemplo, puedes optar por enviar alguna función solo a dispositivos de alta gama y no enviarla a dispositivos que no pueden usarla (es decir, ahorras espacio en ellos). Esto se basa en el concepto de módulos de funciones en Play Feature Delivery. Como verás a continuación, puedes definir los criterios de segmentación (por ahora, basados en la RAM, los modelos de dispositivo específicos o las funciones disponibles del sistema) y puedes segmentar módulos a determinados grupos de dispositivos.

Exploración del desarrollador

En términos generales, para integrar la segmentación por dispositivo en una aplicación existente, deberás seguir estos pasos:

  1. Desarrolla una función que solo desees entregar a un conjunto de dispositivos según su hardware.
    • Implementa esta función como un módulo de funciones.
    • Especifica en la sección de condiciones del módulo de AndroidManifest.xml a qué grupos de dispositivos se deberá enviar.
  2. Crea la configuración de segmentación por dispositivo de modo que Play sepa cómo entregar tus módulos de funciones 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 DT a Play.
    • Sigue los pasos para crear la configuración de la DT.
  3. Sube tu AAB a Play y realiza pruebas a fin de asegurarte de que todo esté configurado correctamente.

En este documento, se describe cómo agregar la segmentación por dispositivo para la entrega condicional mediante el complemento de Android para Gradle.

Cómo crear un módulo de funciones condicional mediante la segmentación por dispositivo

Cómo agregar un módulo de funciones en la app

Play Feature Delivery te permite entregar ciertas funciones de tu app de forma condicional o por medio de una descarga a pedido. Si deseas obtener una descripción general, consulta esta página. Con la segmentación por dispositivo, puedes entregar una función de manera condicional a los dispositivos asignados a los grupos proporcionados.

Si quieres usar la DT para la entrega condicional, debes usar la versión 1.7.0 de bundletool o una posterior. A tal fin, debes especificar de forma explícita la versión de bundletool para el complemento de Android para Gradle. Esto se puede lograr en la sección buildscript del archivo raíz build.gradle:

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

Si deseas crear un módulo de funciones, usa estas instrucciones para modular la aplicación para Android.

Una vez que se complete el desarrollo de tu función, puedes especificar las condiciones de entrega en función de la segmentación por dispositivo en el archivo AndroidManifest.xml de la función. Debes proporcionar una condición de grupo de dispositivos dentro de un elemento dist:conditions de dist:module. La información general sobre las condiciones está disponible aquí. En el caso de los grupos de dispositivos, hay nuevas condiciones disponibles en las que puedes especificar todos los grupos a los que se debería entregar esta función:

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

Por ejemplo, supongamos que definiste un grupo de dispositivos llamado _my_group1 (aprenderás a definirlo en la sección Cómo crear una configuración de segmentación por dispositivo más abajo). Si el módulo de funciones se debe entregar solo a los dispositivos que pertenecen a _my_group1, su AndroidManifest.xml debería verse de la siguiente manera:

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

Para una función segmentada a _my_group1 y _my_group2, su AndroidManifest.xml se ve de la siguiente manera:

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

Cuando termines, puedes compilar tu Android App Bundle (AAB).

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, compilarás y probarás la app de forma local y especificarás de forma explícita el grupo de dispositivos 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 los grupos que te gustaría instalar mediante la marca device-groups. 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 DT y, por lo tanto, falta la marca de 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

Otra alternativa: También puedes usar extract-apks a fin de extraer un conjunto de APK para un dispositivo específico (usa get-device-spec y especifica los grupos para este dispositivo).

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

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)

Si deseas configurar la segmentación por dispositivo (definir tus grupos de dispositivos), 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 a fin de 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 Edits. 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
{
  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
            }
          ]
        }
      ]
    }
  ]
}

Campos:

  • device_tier_config_id (número entero): ID correspondiente a esta configuración de segmentación por dispositivo

  • device_groups (objeto): Definiciones de los grupos

    • name (string): Nombre del grupo de dispositivos (un ID de string que definas)
    • device_selectors (objeto): Los requisitos del dispositivo para que un dispositivo pertenezca a este grupo
    • device_ram (objeto): Requisitos de RAM del dispositivo
      • min_bytes (número entero): RAM mínima requerida (en bytes)
      • max_bytes (número entero): RAM máxima requerida (en bytes)
    • included_device_ids (objeto): Modelos de dispositivos que se incluirán en este selector (10000 device_ids por grupo como máximo). Un dispositivo debe estar en esta lista para coincidir con el selector. Esta es una condición necesaria, pero no suficiente, para hacer coincidir el selector completo (consulta la nota que sigue sobre la combinación de requisitos de un selector)
      • build_brand (string): Fabricante del dispositivo
      • build_device (string): Código del modelo del dispositivo
    • excluded_device_ids (objeto): Modelos de dispositivos que se excluirán en el selector (10000 device_ids por grupo como máximo). Los dispositivos de esta lista no coincidirán con el selector incluso aunque coincidieran con todos los demás requisitos del selector
      • build_brand (string): Fabricante del dispositivo
      • build_device (string): Código del modelo del dispositivo

    • required_system_features (objeto): Funciones que un dispositivo debe tener para que se incluya en este selector (100 funciones por grupo como máximo). Un dispositivo debe tener todas las funciones del sistema de esta lista a fin de que coincida con el selector. Esta es una condición necesaria, pero no suficiente, para hacer coincidir el selector completo (consulta la nota que sigue sobre la combinación de requisitos de un selector)

      Referencia de las funciones del sistema

      • name (string): Una función del sistema

    • forbidden_system_features (objeto): Funciones que un dispositivo no debe tener para que se incluya en este selector (100 funciones por grupo como máximo). Si un dispositivo tiene alguna de las funciones del sistema que se detallan en esta lista, no coincidirá con el selector, incluso aunque coincidiera con todos los demás requisitos del selector.

      Referencia de las funciones del sistema

      • name (string): Una función del sistema

Puedes encontrar el formato correcto para el fabricante y el código del modelo del dispositivo en el catálogo de dispositivos de Google Play Console optando por una de las siguientes maneras:

  • Inspecciona los dispositivos individuales mediante el catálogo de dispositivos y encuentra el fabricante y el código del modelo en las ubicaciones como se muestra en el siguiente ejemplo (para un Google Pixel 4a, el fabricante es "Google" y el código del modelo es "Sunfish").

    Página del Pixel 4a en el catálogo de dispositivos

    Página del Pixel 4a en el catálogo de dispositivos

  • Descarga un archivo CSV de dispositivos compatibles e ingresa el Fabricante y Código del modelo en los campos build_brand y build_device, respectivamente.

Por ejemplo, el siguiente grupo coincide con todos los dispositivos que tienen más de 4 GB de RAM, excepto el Pixel 5 (Google Redfin), incluido el Pixel 3 (Google Blueline, que tiene menos de 4 GB 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"
          }
        ]
      }
    ]
  }
]

Puedes leerlo de la siguiente manera:

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

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 utilizando la siguiente llamada:

Solicitud HTTP GEThttps://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 utilizando la siguiente llamada (o idealmente especifica un conjunto de diez mediante el parámetro de consulta page_token):

Solicitud HTTP GEThttps://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 y visualizar tus grupos de dispositivos en un formato más legible.

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

Con bundletool evaluate-device-targeting-config, puedes evaluar qué grupos coincidirían con un dispositivo específico. Conecta el dispositivo de destino a la estación de trabajo y usa la marca --connected-device. También puedes compilar manualmente un archivo JSON con las propiedades del dispositivo y proporcionarlo a través de la marca --device-properties.

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

El archivo de propiedades del dispositivo debe ser un archivo JSON según la estructura protobuf de DeviceProperties. Por ejemplo:

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

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 API compatibles con AAB en lugar de API compatibles con APK, las cuales se enumeran en la página). Si quieres especificar la configuración de la segmentación por dispositivo para tu compilación, debes agregar el ID de configuración al parámetro de consulta 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.

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 la segmentación por dispositivo y usar la API de edición a fin de crear una edición nueva, subir un AAB nuevo (y asociarlo a una configuración de la 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:

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

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 la segmentación por dispositivo (deviceTierconfigId) como un parámetro de consulta. 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="{deviceTierConfigId}

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}', versionCodes: ['{versionCode}'] }]}" 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