Segmentação de recurso por país

O que é a segmentação de recursos por país?

A segmentação de recursos por país permite que você entregue versões diferentes (por exemplo, resoluções) do mesmo recurso para dispositivos com base no país em que o usuário está localizado. Por exemplo, você pode optar por enviar recursos personalizados para diferentes países em que o app está disponível, tudo sem ter qualquer aumento no tamanho geral do jogo, enviando apenas 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 segmentação com até 20 conjuntos de países. Nesse contexto, o país do dispositivo é normalmente determinado pelo endereço de faturamento do usuário registrado na conta do Google Play.

Assim como o Play Asset Delivery, a segmentação por país tem suporte para o Android 4.1 (nível 16 da API) e versões mais recentes. No entanto, em dispositivos com o Android 4.4 (nível 19 da API) ou versões anteriores, o conjunto padrão é enviado independente da localização do usuário.

Jornada do desenvolvedor

Siga estas etapas para integrar a segmentação por país ao seu jogo:

1. Integre a segmentação por país (e o Play Asset Delivery) ao seu jogo
   • 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 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 segmentação ao Google Play.
   • Siga as etapas para criar a configuração.
3. Faça upload do AAB no Google Play e faça um teste para garantir que tudo esteja configurado corretamente.

O Gradle é o sistema de build recomendado para Java e jogos nativos. Para jogos criados com o Gradle, siga estas etapas para configurar o sistema de build e criar seu AAB com suporte à segmentação por país.

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

Como configurar a segmentação de recursos por país no 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 neste link para acessar uma visão geral sobre ele. Com a segmentação por país, o Google Play vai enviar o conteúdo dos seus pacotes de recursos com base nas configurações definidas para diferentes países. É 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 país.

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:

• Java
• Nativo
• Jogos do Unity exportados para Gradle (link em inglês)
  • Use bibliotecas Java via JNI, por exemplo, a integrada ao Unity (link em inglês).

Como criar diretórios específicos de um país

Se estiver usando o Gradle

Agora, você vai dividir seus recursos entre os conjuntos de países (máximo de 20) que serão definidos posteriormente. Crie seus diretórios segmentados pegando os diretórios de pacotes de recursos já existentes criados na última etapa. Adicione-os à pasta adequada (como descrito abaixo) com #countries_latam, #countries_na etc. Ao usar os pacotes de recursos no jogo, não é necessário tratar as pastas pela adição de sufixos. Em outras palavras, essa etapa é removida automaticamente durante o processo de build.

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

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

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.

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

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

distributionUrl=https://services.gradle.org/distributions/gradle-8.0-rc-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 segmentação por país:

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

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

• Android Studio
• CLI

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": "COUNTRY_SET",
        "negate": false,
        "suffixStripping": {
          "enabled": true,
        }
      }],
    }
  }
}

Teste local

Antes de continuar, é recomendável testar localmente seu pacote de apps para conferir se tudo está configurado corretamente. Com a ferramenta bundletool (1.14.0 ou mais recente), você cria e testa localmente o app, especificando de forma explícita o país 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 conjunto de países quer instalar usando a flag country-set. Saiba mais sobre esse método de teste local neste link. Essa página ainda não foi atualizada para segmentação por país e, portanto, não tem a flag 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

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

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

Como criar uma configuração de segmentação por 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 país (ou seja, definir os conjuntos de países), use a API Android Publisher para 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 de configuração de segmentação por dispositivo

Use 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

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

Campos:

• device_confid_id (número inteiro): ID correspondente à configuração de segmentação por dispositivo.
• user_country_sets (objeto): definições de conjuntos de países
  • name (string): nome do conjunto de países (um ID definido por você).
  • country_codes (string): países que pertencem a esse conjunto de países (formato: ISO 3166-1 alpha-2).

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

É possível recuperar uma configuração de segmentação por 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 segmentação por dispositivo

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

Acesse as últimas 10 configurações de segmentação por dispositivo considerando a seguinte chamada ou, de preferência, especifique 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 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 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.

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

Com bundletool evaluate-device-targeting-config, é possível avaliar qual conjunto de países corresponde a um dispositivo específico. Forneça o país do usuário usando a flag --country-code.

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

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 lançamento 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 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 é aplicada ao seu pacote de apps.

Como garantir que os recursos corretos estão sendo enviados

Use o método a seguir para garantir que apenas os recursos corretos sejam enviados 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.countries_latam.apk

Auxiliar

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

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

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 como parâmetro de consulta. Se a chamada for bem-sucedida, será exibido 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="{deviceTargetingConfigID}"

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