Esta página foi traduzida pela API Cloud Translation.

Segmentação por dispositivo para módulos condicionais

O que é a segmentação por dispositivo para módulos condicionais?

A segmentação por dispositivo permite enviar módulos de recursos condicionais para dispositivos com base no hardware. Por exemplo, você pode optar por enviar um recurso apenas para dispositivos de última geração e não para aqueles que não têm capacidade de usar esse recurso, economizando espaço nos dispositivos. Isso se baseia no conceito de módulos de recursos no Play Feature Delivery. Como você verá abaixo, é possível definir os critérios de segmentação (por enquanto, com base em RAM, modelos de dispositivos específicos ou recursos disponíveis do sistema) e módulos de segmentação para grupos de dispositivos específicos.

Jornada do desenvolvedor

No geral, para integrar a segmentação por dispositivo ao aplicativo existente, é necessário seguir estas etapas:

Desenvolva um recurso que você queira oferecer apenas para um conjunto de dispositivos com base no hardware deles.
- Faça a implementação como um módulo de recurso.
- Especifique na seção de condições do módulo do AndroidManifest.xml a quais grupos de dispositivos ele precisa ser enviado.
Crie sua configuração de segmentação por dispositivo para que o Google Play saiba como enviar seus módulos de recursos aos dispositivos dos usuários.
- Configure a API Google Play Developer, caso ainda não esteja concluída. É ela que você vai usar para enviar as configurações de DT ao Google Play.
- Use as etapas para criar a configuração de DT.
Faça upload do AAB no Google Play e teste para garantir que tudo esteja configurado corretamente.

Este documento descreve como adicionar segmentação por dispositivo para envio condicional usando o Plug-in do Android para Gradle.

Criar um módulo de recurso condicional com a segmentação por dispositivo

Como adicionar um módulo de recurso ao app

O Play Feature Delivery permite que você envie determinados recursos do seu app de modo condicional ou por download sob demanda. Para ter uma visão geral sobre ele, clique neste link. Com a segmentação por dispositivo, você pode enviar um recurso de modo condicional para dispositivos atribuídos aos grupos fornecidos.

Se quiser usar a DT para envio condicional, você precisa da ferramenta bundletool 1.7.0 ou versões mais recentes. Isso exige a especificação explícita da versão da bundletool para o Plug-in do Android para Gradle. Essa ação pode ser realizada na seção da buildscript do arquivo build.gradle raiz:

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

Para criar um módulo de recurso, use estas instruções de modularização do app Android.

Depois que o desenvolvimento do recurso for concluído, você pode especificar as condições de envio com base na segmentação por dispositivo no AndroidManifest.xml do recurso. É necessário fornecer uma condição de grupo de dispositivos dentro de dist:conditions de um elemento dist:module. Clique aqui para ver informações gerais sobre condições. Para grupos de dispositivos, há novas condições disponíveis, em que você pode especificar todos os grupos aos quais esse recurso será enviado:

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

Por exemplo, digamos que você tenha definido um grupo de dispositivos chamado _my_group1. Você vai aprender a definir esse grupo na seção Criar uma configuração de segmentação por dispositivo abaixo. Se o módulo de recurso precisar ser enviado apenas a dispositivos pertencentes ao _my_group1, o AndroidManifest.xml vai ficar assim:

<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 um recurso destinado ao _my_group1 e _my_group2, o AndroidManifest.xml tem a seguinte aparência:

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

Quando terminar, você pode criar seu Android App Bundle (AAB).

Teste local

Antes de continuar, é recomendável testar localmente seu pacote de apps para conferir se tudo está configurado corretamente. Ao usar a ferramenta bundletool, você cria e testa localmente o app, especificando de forma explícita o grupo de dispositivos correto. Primeiro, você vai usar o comando build-apks para gerar um conjunto de arquivos .apks e, depois, vai implantar o app em um dispositivo conectado usando install-apks. Você também pode especificar quais grupos quer instalar usando a sinalização device-groups. Veja mais informações sobre esse método de teste local clicando aqui. Essa página ainda não foi atualizada para DT e, por isso, não tem a sinalização 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

Outra opção seria usar extract-apks com o objetivo de extrair um conjunto de APKs para um dispositivo específico, usando get-device-spec e especificando os grupos para esse 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

Como criar uma configuração de segmentação por dispositivo usando a API Google Play Developer

Primeiros passos com a API Google Play Developer, caso ainda não esteja concluída

Para configurar a segmentação por dispositivo e definir grupos de dispositivos, é necessário usar a API Android Publisher e fazer upload da sua configuração para o Google Play. Saiba mais sobre a API no link acima. Há algumas etapas que você precisa seguir para começar:

Você pode encontrar a referência da API neste link. Posteriormente, se quiser fazer upload do seu build pela API, você vai usar os métodos Edits. Além disso, é recomendável ler esta página antes de usar a API.

Como usar a API de configuração de segmentação por dispositivo

É possível usar a seguinte chamada de API para criar a configuração de segmentação por dispositivo:

Criar configuração de segmentação por dispositivo

Solicitação HTTP	`POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs`
Parâmetros de caminho	N/A
Corpo da solicitação	Configuração de segmentação por dispositivo
Corpo da resposta	Configuração de segmentação por dispositivo

Objeto de configuração da segmentação 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 inteiro): ID correspondente à configuração de segmentação do dispositivo.
device_groups (objeto): definições de grupo.
- name (string): nome do grupo de dispositivos (um código de string definido por você).
- device_selectors (objeto): requisitos do dispositivo para que ele pertença ao grupo.
- device_ram (objeto): requisitos de RAM do dispositivo.
  - min_bytes (número inteiro): mínimo de RAM necessária (em bytes).
  - max_bytes (número inteiro): máximo de RAM necessária (em bytes).
- included_device_ids (objeto): os modelos do dispositivo serão incluídos no seletor (máximo de 10.000 device_ids por grupo). Um dispositivo precisa estar nessa lista para corresponder ao seletor. Essa é uma condição necessária, mas não suficiente para corresponder ao seletor completo. Veja a observação abaixo sobre como combinar os requisitos em um seletor.
  - build_brand (string): fabricante do dispositivo.
  - build_device (string): código do modelo do dispositivo.
- excluded_device_ids (objeto): modelos de dispositivo a serem excluídos neste seletor (máximo de 10.000 device_ids por grupo). Um dispositivo dessa lista não corresponde ao seletor, mesmo que corresponda a todos os outros requisitos dele.
  - build_brand (string): fabricante do dispositivo.
  - build_device (string): código do modelo do dispositivo.
- required_system_features (objeto): recursos que um dispositivo precisa ter para ser incluído por esse seletor (máximo de 100 recursos por grupo). Um dispositivo precisa ter todos os recursos do sistema nessa lista para corresponder ao seletor. Essa é uma condição necessária, mas não suficiente, para corresponder ao seletor completo. Veja a observação abaixo sobre como combinar os requisitos em um seletor.
  
  Referência de recursos do sistema
  - name (string): um recurso do sistema.
- forbidden_system_features (objeto): recursos que um dispositivo não pode ter para ser incluído por esse seletor (máximo de 100 recursos por grupo). Se um dispositivo tiver algum recurso do sistema nessa lista, ele não vai corresponder ao seletor, mesmo que corresponda a todos os outros requisitos dele.
  
  Referência de recursos do sistema
  - name (string): um recurso do sistema.

Observação:

Um grupo pode especificar vários seletores: um dispositivo pertence ao grupo se ele corresponde a pelo menos um seletor de grupo (lógica com OR).
Um dispositivo pode pertencer a vários grupos.
Um seletor pode especificar condições de RAM, inclusão e exclusão de modelos de dispositivos e recursos do sistema obrigatórios/proibidos. Se um seletor especificar várias condições, um dispositivo vai corresponder ao seletor caso ele corresponda a todas elas (lógica com AND).

Aviso: a inclusão de várias regras como parte do mesmo seletor cria uma lógica com AND. Por exemplo:

  {
    device_ram: {
        min_bytes: 7516192768
    },
    included_device_ids: [
          {
               build_brand: ‘google',
               build_device: ‘flame'
          }
    ],
  }

cria a condição para todos os dispositivos com mais de 7 GB de RAM e (AND) é um Pixel 4, também escrito da seguinte forma:

Se você quiser uma condição OR, agrupe os seletores separadamente. Por exemplo:

  {
    device_ram: {
        min_bytes: 7516192768
    },
  },
  {
    included_device_ids: [
          {
               build_brand: ‘google',
               build_device: ‘flame'
          }
    ],
  }

cria a condição para todos os dispositivos com mais de 7 GB de RAM ou (OR) é um Pixel 4, também escrito da seguinte forma:

Para encontrar a formatação correta do fabricante do dispositivo e o código do modelo, use o catálogo de dispositivos no Google Play Console de uma das seguintes maneiras:

Inspeção dos dispositivos individuais usando o catálogo de dispositivos e encontrando o código do fabricante e do modelo nos locais, conforme mostrado no exemplo abaixo. No caso de um Google Pixel 4a, o fabricante é "Google" e o código do modelo é "sunfish".
Download de um CSV dos dispositivos com suporte e uso do código do fabricante e do modelo para os campos build_brand e build_device, respectivamente.

Por exemplo, o grupo a seguir corresponde a todos os dispositivos com mais de 4 GB de RAM, exceto o Pixel 5 (Google Redfin) e incluindo o Pixel 3 (Google Blueline), que tem 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"
          }
        ]
      }
    ]
  }
]

Ele pode ser lido da seguinte maneira:

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

Siga as instruções abaixo para validar sua configuração de segmentação por dispositivo antes de fazer o upload dela para o Google Play.

Acessar a configuração de segmentação por dispositivo pelo ID

Você pode recuperar uma configuração de segmentação por dispositivo específica pelo ID usando a seguinte chamada:

Solicitação HTTP	`GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}`
Parâmetros de caminho	N/A
Corpo da solicitação	N/A
Corpo da resposta	Configuração de segmentação por dispositivo

Acessar a lista de configurações de segmentação por dispositivo

Você pode ver as últimas 10 configurações de segmentação por dispositivo considerando a seguinte chamada ou, de preferência, especificar um conjunto de 10 delas usando o parâmetro de consulta page_token:

Solicitação HTTP	`GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs`
Parâmetros de caminho	N/A
Parâmetros de consulta	page_token (opcional): usado para especificar um grupo específico de 10 configurações de segmentação por dispositivo (DTCs). É útil se você criou mais de 10 DTCs e quer ver as criadas antes das 10 mais recentes.
Corpo da solicitação	N/A
Corpo da resposta	Lista de configurações de segmentação por dispositivo `page_token`

Como validar a configuração da segmentação por dispositivo

O bundletool inclui dois comandos que ajudam a validar se a configuração de segmentação por dispositivo funcionar conforme o esperado antes do upload para o Google Play.

Com bundletool print-device-targeting-config, é possível validar se o arquivo JSON está sintaticamente correto e visualizar seus grupos de dispositivos em um formato mais legível.

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

Com bundletool evaluate-device-targeting-config, é possível avaliar quais grupos corresponderiam a um dispositivo específico. Conecte o dispositivo de destino à estação de trabalho e use a flag --connected-device. Você também pode compilar um arquivo JSON manualmente com as propriedades do dispositivo e fornecê-lo usando a flag --device-properties.

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

O arquivo de propriedades do dispositivo precisa ser um arquivo JSON seguindo a estrutura protobuf DeviceProperties. Por exemplo:

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

Como fazer upload do seu Android App Bundle para o Google Play

Por API

Você pode usar a API Google Play Developer para fazer upload do Android App Bundle no Google Play e vincular ao build uma configuração específica de segmentação por dispositivo.

Há uma visão geral dos métodos de edição neste link, além de exemplos mais detalhados sobre como lançar para as diferentes faixas no Google Play Console. No caso do último link, use as APIs com suporte a AAB em vez da API com suporte a APK, que estão listadas na página. Para especificar a configuração de segmentação por dispositivo do seu build, adicione o ID de configuração ao parâmetro de consulta deviceTierConfigId ao chamar o método edits.bundle.upload, desta forma:

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

Pelo Google Play Console

Siga estas instruções para fazer upload do Android App Bundle. A DTC mais recente será aplicada ao seu pacote de apps.

Auxiliar

Guia de início rápido sobre o uso do curl

Veja abaixo um exemplo (com o curl da ferramenta de linha de comando) de como criar uma nova configuração de segmentação por dispositivo e usar a API Edits para criar uma nova edição, fazer upload de um novo AAB associado a uma configuração específica de segmentação por dispositivo, definir a configuração de rastreamento/versão e confirmar a edição, tornando a mudança pública. Você precisa saber a localização:

da chave correspondente ao seu cliente de API;
do nome do pacote do seu app.

Primeiro, crie uma configuração de segmentação por dispositivo e anote o deviceTierConfigId que você vai receber após uma chamada bem-sucedida.

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

Inicie uma edição: você vai receber um ID e um prazo de validade da edição. Salve o ID das chamadas a seguir.

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

Faça upload do AAB, especificando a configuração de segmentação por dispositivo (deviceTierConfigId) como parâmetro de consulta. Se a chamada for bem-sucedida, você verá um código de versão, sha1 e sha256 do build. Salve o código da versão para a próxima chamada.

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}

Atribua o AAB à faixa desejada. Para testes, é recomendável usar a faixa de teste interno, mas você pode ler mais sobre as diferentes faixas neste link. Aqui fazemos um lançamento simples, sem notas da versão, mas você pode ler esta página para saber mais sobre como fazer lançamentos graduais, versões de rascunho e notas da versão. Se esta for a primeira vez que você usa a API Publisher, recomendamos que a crie como uma versão de rascunho e conclua o lançamento no Google Play Console para garantir que tudo tenha sido configurado corretamente.

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}

Confirme as mudanças. Prossiga com cautela, já que elas vão entrar em vigor no Google Play para a faixa desejada.

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