Segmentação por nível de dispositivo

O que é a segmentação por nível de dispositivo?

A segmentação por nível de dispositivo permite que você forneça versões diferentes (como resoluções etc.) do mesmo recurso para os dispositivos de acordo com o hardware deles. Por exemplo, você pode optar por enviar recursos de baixa resolução a dispositivos mais simples para melhorar o desempenho e recursos de alta resolução a dispositivos mais sofisticados para melhorar a qualidade gráfica. Tudo isso sem gerar aumento geral no tamanho do jogo, apenas enviando os recursos necessários para os dispositivos dos usuários. Isso se baseia no conceito de pacotes de recursos no Play Asset Delivery. Como você verá abaixo, é possível definir os critérios de nível (por enquanto, com base em RAM, modelos de dispositivos específicos ou recursos disponíveis do sistema) e usar até cinco níveis.

Assim como o Play Asset Delivery, a segmentação por nível de dispositivo oferece suporte à API 16 (Jelly Bean 4.1) e versões mais recentes. No entanto, em dispositivos com a API 19 (KitKat 4.4.X) e versões anteriores, o nível padrão é enviado independentemente do build do dispositivo.

Jornada do desenvolvedor

No geral, para integrar a segmentação por nível do dispositivo (DTT, na sigla em inglês) no seu jogo, você precisa seguir estas etapas:

  1. Integre ao seu jogo a segmentação por nível de dispositivo e, consequentemente, o Play Asset Delivery.
    • Integre o Play Asset Delivery ao jogo, caso ainda não tenha feito isso.
    • Divida seus recursos em pacotes de recursos.
    • Agrupe o código e os recursos no artefato final do Android App Bundle para upload no Google Play.
  2. Crie sua configuração de segmentação por nível de dispositivo para que o Google Play saiba como enviar seus 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 DTT ao Google Play.
    • Siga as etapas para criar a configuração de DTT.
  3. Faça upload do AAB no Google Play e teste para garantir que tudo esteja configurado corretamente.

Na primeira seção, você vai ver bifurcações no guia, dependendo do sistema de compilação que usar. O sistema escolhido depende do mecanismo usado e da configuração atual.

  • Gradle (recomendado para jogos nativos e Java): no caso de jogos criados com o Gradle, siga estas etapas para configurar o sistema de compilação e criar seu AAB com suporte a DTT.
    • Se você exportar seu jogo para o Gradle e concluir seu build nele, recomendamos seguir estas instruções. Por exemplo, jogos do Unity exportados para o Gradle (link em inglês).
  • Plug-in do Unity: vamos fornecer pacotes para importar no seu projeto do Unity. Assim, você pode configurar e criar seu AAB com suporte a DTT.

Como configurar a segmentação por nível de dispositivo no seu app

Como integrar o Play Asset Delivery ao jogo, caso ainda não esteja concluído

O Play Asset Delivery (PAD) permite que você envie dinamicamente os recursos do jogo no momento da instalação ou da execução. Clique aqui para acessar uma visão geral sobre ele. Com a segmentação por nível de dispositivo, o Google Play vai enviar pacotes de recursos com base nas configurações que você especificar para diferentes níveis de dispositivo. É recomendável seguir as orientações abaixo e integrar o PAD ao seu jogo, criando pacotes de recursos e implementando a recuperação no jogo. Depois, você precisa modificar o código do projeto para ativar a segmentação por nível de dispositivo.

Gradle

No caso de jogos criados com o Gradle, use estas instruções para criar seus pacotes de recursos com o Gradle e siga as instruções para integrar a recuperação de pacotes de recursos no seu jogo:

Unity

Para jogos criados no Unity, você vai configurar seus pacotes de recursos usando a classe AssetPackConfig, conforme descrito nestas instruções.

Como criar diretórios específicos de níveis de dispositivo

Se estiver usando o Gradle

Agora, você vai dividir seus recursos entre os N níveis (máximo de cinco) que serão definidos posteriormente. Crie seus diretórios de DTT pegando os diretórios de pacotes de recursos existentes criados na última etapa e depois adicione à pasta adequada, conforme descrito abaixo, os sufixos #tier_0, #tier_1, #tier_2 etc. Ao usar os pacotes de recursos no jogo, não é necessário resolver as pastas pela adição de sufixos. Em outras palavras, essa etapa é removida automaticamente durante o processo de compilação.

Após a etapa anterior, a aparência do código será esta:

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

Quando você acessa os arquivos na pasta, pode usar o mesmo caminho após a adição do sufixo. Neste exemplo, eu usaria level1/assets/character-textures/ sem sufixos.

Se estiver usando o Unity

Para adicionar um pacote de recursos que usa a DTT, utilize os métodos AssetPackConfig abaixo:

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

Por exemplo, digamos que você tenha três AssetBundles para seu personagem em vários níveis de detalhamento.

Se quiser mapear esses AssetBundles para o nível de dispositivo correspondente, use o snippet a seguir.

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

Como criar o Android App Bundle

Gradle

No arquivo build.gradle do seu projeto, configure as dependências para ter as versões anteriores (ou mais recentes) do Plug-in do Android para Gradle e da bundletool:

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

Também será necessário atualizar o Gradle para a versão 6.7.1 ou mais recente. Ele pode ser atualizado em gradle/wrapper/gradle-wrapper.properties no seu projeto.

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

Por fim, você vai precisar usar a biblioteca Play Asset Delivery. Se você ainda usa a Biblioteca Play Core monolítica, atualize-a para a versão 1.8.3 ou mais recente. Recomendamos mudar para a biblioteca Play Asset Delivery e atualizar para a versão mais recente.

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

No arquivo build.gradle do módulo principal do app, ative a divisão de DTT:

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

Você já pode criar o Android App Bundle (AAB).

Bundletool

Crie seu pacote com a bundletool e, na etapa para personalizar o AAB, adicione o seguinte ao arquivo BundleConfig.pb.

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

Unity

Depois de configurar a classe AssetPackConfig para incluir os pacotes DTT, transmita essa configuração a um dos métodos abaixo e crie seu 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)

Teste local

Antes de continuar, é recomendável testar localmente seu pacote de apps para conferir se tudo está configurado corretamente. Ao usar a bundletool (1.8.0 ou mais recente), você cria e testa localmente o app, especificando explicitamente o nível de dispositivo 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 qual nível quer instalar usando a sinalização de nível de dispositivo. Veja mais informações sobre esse método de teste local clicando neste link. Essa página ainda não foi atualizada para DTT e, portanto, não tem a flag device-tier.

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

Outra opção seria usar extract-apks para extrair um conjunto de APKs para um dispositivo específico. O uso de get-device-spec junto à especificação do nível para este dispositivo, entretanto, não vai funcionar em conjunto com a flag --local-testing. Isso significa que não será possível testar pacotes de recursos rápidos ou sob demanda.

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

Unity

A opção de menu Google -> Build and Run cria e executa seu jogo com a sinalização --local-testing ativada. No entanto, ela não permite especificar o nível do dispositivo transmitido para o comando install-apks.

Caso queira especificar um nível de dispositivo diferente de 0, faça o seguinte:

  1. Crie o AAB usando a opção de menu Google -> Build Android App Bundle.
  2. Siga as instruções na seção anterior para executar bundletool, build-apks e install-apks no AAB criado.

Como criar uma configuração de nível de dispositivo usando a API Google Play Developer

Introdução à API Google Play Developer (caso ainda não esteja concluída)

Para configurar a segmentação por nível de dispositivo (por exemplo, definição dos requisitos para cada nível), você vai precisar usar a API Android Publisher e fazer upload da configuração no Google Play. Saiba mais sobre a API no link acima. Há algumas etapas que você precisa seguir para começar:

  1. Crie (se necessário) e vincule o projeto de API ao Google Play Console.
  2. Configure um cliente de acesso à API.

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 de edição. Além disso, é recomendável ler esta página antes de usar a API.

Como usar a API para configuração de nível de dispositivo

Use a seguinte chamada de API para criar a configuração de nível de dispositivo:

Criar a configuração de nível de 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 nível de dispositivo
Corpo da resposta Configuração de nível de dispositivo
Objeto de configuração de nível de dispositivo

A definição dos níveis do dispositivo é composta por duas etapas:

  1. Definir um conjunto de grupos de dispositivos.
  2. Definir seu conjunto de níveis de dispositivo atribuindo uma posição aos seus grupos.

Um grupo de dispositivos é um conjunto que corresponde aos seletores definidos na configuração.

Os seletores podem definir requisitos de RAM e modelo do dispositivo.

Os grupos são identificados por um nome que você escolhe e podem se sobrepor.

Em seguida, é possível definir seu conjunto de níveis de dispositivo classificando os grupos: cada nível é definido pela própria posição e por um grupo de dispositivos.

Se um dispositivo corresponder a vários níveis, será enviado o conteúdo para o nível mais alto.

  {
    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]
        }
      ]
    }
  }

Campos:

  • device_confid_id (número inteiro): ID correspondente à configuração de nível de dispositivo.

  • device_groups (objeto): definições de grupo.

    • name (string): nome do grupo de dispositivos, que é um ID 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, inclusivo): mínimo de RAM necessária (em bytes).
      • max_bytes (número inteiro, exclusivo): máximo de RAM necessária (em bytes).
    • included_device_ids (objeto): os modelos de dispositivo serão incluídos nesse 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. Confira a observação acima 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 acima sobre a combinação de 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.

  • device_tiers (objeto): definições de nível.

    • level (int): a posição do nível.
    • group_name (matriz de strings): o nome dos grupos de dispositivos que pertencem a esse nível.

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

    Página do Pixel 4a no catálogo de dispositivos

    Página do Pixel 4a no catálogo de dispositivos

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

Este é um exemplo de configuração com três níveis: o nível 2 usa o grupo de dispositivos elevado, que inclui todos os dispositivos com mais de 7 GB e o Pixel 4. O nível 1 usa o grupo de dispositivos médio, que inclui todos os dispositivos entre 4 e 7 GB. O nível 0 é definido implicitamente como o grupo abrangente.

{
  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'
        ]
      }
    ]
  }
}

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 nível de dispositivo por ID

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

Solicitação HTTP GET https://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 nível de dispositivo

Acessar a lista de configurações de nível de dispositivo

Você pode ver as últimas 10 configurações de nível de 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 GET https://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, na sigla em inglês). Isso é útil se você criou mais de 10 DTCs e quer ver as DTCs criadas antes das 10 mais recentes.
Corpo da solicitação N/A
Corpo da resposta Lista de configurações de nível de 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 funciona 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 e níveis 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 e nível corresponderiam a um dispositivo específico. Conecte o dispositivo de destino à estação de trabalho e use a sinalização --connected-device. Você também pode compilar um arquivo JSON manualmente com as propriedades do dispositivo e fornecê-lo usando a sinalização --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 nível de 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 nível de dispositivo para sua versão, 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.

Para verificar se o pacote foi criado corretamente, acesse o Explorador de pacotes de apps (com o build correto selecionado) > Envio e clique em cada pacote de recursos. Você verá os N níveis criados. Neste exemplo, serão mostrados os níveis 0, 1 e 2 para o pacote de recursos main_asset.

Pacote de recursos com três níveis

Como verificar se o nível correto está sendo enviado

Use o método a seguir para garantir que apenas o nível correto seja enviado ao dispositivo

adb shell pm path {packageName}

Você verá um código como este:

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

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 nível de 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 nível de dispositivo, definir a configuração de rastreamento/versão e confirmar a edição. Isso torna 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 nível de dispositivo e anote o deviceTierConfigId que você vai receber em uma chamada bem-sucedida.

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

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 nível de dispositivo 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="{dttConfigID}"

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}'</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}

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