Compatibilidade com vários APKs

Se você publicar seu app no Google Play, será necessário criar e fazer upload de um Android App Bundle. Quando você faz isso, o Google Play gera e exibe automaticamente APKs otimizados para a configuração do dispositivo de cada usuário para que eles façam o download apenas do código e dos recursos necessários para executar o app. A publicação de vários APKs é útil se você não está publicando no Google Play, mas precisa criar, assinar e gerenciar cada APK.

O suporte a vários APKs é um recurso do Google Play que permite a publicação de diferentes APKs para seu aplicativo, sendo que cada um deles pode ser voltado para uma configuração de dispositivo diferente. Cada APK é uma versão completa e independente do aplicativo, mas eles compartilham as mesmas informações de produto no Google Play e precisam compartilhar o mesmo nome de pacote e ser assinados com a mesma chave de versão. Esse recurso é útil nos casos em que um único APK não é o suficiente para que seu aplicativo chegue a todos os dispositivos desejados.

Dispositivos com tecnologia Android podem variar de diversas maneiras, e é importante para o sucesso do seu aplicativo que ele seja disponibilizado para o maior número de dispositivos possível. Aplicativos para Android geralmente são executados com um único APK na maioria dos dispositivos com suporte, com recursos alternativos para configurações diferentes, por exemplo, diferentes layouts para diferentes tamanhos de tela. O sistema Android seleciona os recursos adequados para o dispositivo durante a execução. No entanto, em alguns casos, um único APK não é compatível com todas as configurações de dispositivos. Isso porque os recursos alternativos tornam o arquivo grande demais ou outros desafios técnicos impedem que um único APK funcione em todos os dispositivos.

Para ajudar você a publicar seu aplicativo para o maior número de dispositivos possível, o Google Play permite que você publique vários APKs com as mesmas informações de produto. Então, o Google Play entrega cada APK aos dispositivos adequados com base no suporte de configuração declarada no arquivo de manifesto do APK.

Ao publicar seu aplicativo com vários APKs, você pode:

• oferecer compatibilidade com diferentes formatos de compactação de textura do OpenGL;
• oferecer suporte a diferentes tamanhos e densidades de tela;
• oferecer suporte a diferentes conjuntos de recursos do dispositivo;
• oferecer suporte a diferentes versões da plataforma;
• oferecer suporte a diferentes arquiteturas de CPU, como ARM ou x86, quando o app usa o Android NDK.
• Otimização para dispositivos básicos, como os que executam o Android (edição Go).

Atualmente, essas são as únicas características de dispositivo disponíveis no Google Play para a publicação de vários APKs como o mesmo aplicativo.

Observação:para saber como preparar e publicar APKs no Google Play, consulte o artigo de suporte Preparar e lançar versões.

Como funciona a publicação de vários APKs

O conceito do uso de vários APKs no Google Play é que existe apenas uma entrada para o aplicativo no Google Play, mas dispositivos diferentes podem fazer o download de APKs diferentes. O que isso significa:

• Você mantém apenas um conjunto de detalhes do produto (descrição do app, ícones, capturas de tela etc.). Isso também significa que não é possível cobrar um preço diferente por APKs diferentes.
• Todos os usuários veem apenas uma versão do aplicativo no Google Play. Assim, eles não ficam confusos com as diferentes versões publicadas "para tablets" ou "para smartphones".
• Todas as avaliações são aplicadas às mesmas informações do produto, mesmo que usuários em dispositivos diferentes tenham APKs diferentes.
• Se você publicar APKs diferentes para versões diferentes do Android (para diferentes níveis de API), quando um dispositivo do usuário receber uma atualização do sistema qualificada para outro APK, o Google Play vai atualizar o aplicativo com o APK projetado para a versão mais recente do Android. Todos os dados do sistema associados ao aplicativo serão mantidos, o mesmo que acontece com as atualizações normais de um único APK.

Filtros compatíveis

Os dispositivos que recebem cada APK são determinados por filtros do Google Play especificados por elementos do arquivo de manifesto do APK. No entanto, o Google Play só permite a publicação de vários APKs quando cada um usa filtros compatíveis com uma variação das seguintes características do dispositivo:

• Formatos de compactação de textura do OpenGL

  Isso é baseado nos elementos <supports-gl-texture> do seu arquivo de manifesto.

  Por exemplo, ao desenvolver um jogo que usa o OpenGL ES, você pode fornecer um APK para dispositivos que ofereçam suporte a compactação de textura de ATI e um APK separado para dispositivos que ofereçam suporte a compactação PowerVR, entre outros.

• Tamanho da tela (e, opcionalmente, densidade da tela)

  Isso é baseado no elemento <supports-screens> ou <compatible-screens> do arquivo de manifesto. Nunca use os dois elementos juntos e use apenas <supports-screens> quando possível.

  Por exemplo, você pode fornecer um APK que oferece suporte a telas de tamanho pequeno e normal e outro APK compatível com telas grandes e extra grandes. Para saber mais sobre como gerar APKs separados com base no tamanho ou na densidade da tela, acesse Desenvolver vários APKs.

  Considere as seguintes práticas recomendadas para oferecer suporte a todos os tamanhos de tela:

  • O sistema Android oferece todo o suporte para que os aplicativos sejam compatíveis com todas as configurações de tela com um único APK. A menos que seja absolutamente necessário, evite criar vários APKs para oferecer suporte a telas diferentes. Em vez disso, siga o guia Suporte a várias telas para que seu aplicativo seja flexível e possa se adaptar a todas as configurações de tela com um único APK.
  • Por padrão, todos os atributos de tamanho de tela no elemento <supports-screens> são "true" se você não os declarar de outra forma. No entanto, como o atributo android:xlargeScreens foi adicionado ao Android 2.3 (API de nível 9), o Google Play entende como "false" se o aplicativo não define android:minSdkVersion ou android:targetSdkVersion como "9" ou mais.
  • Não combine os elementos <supports-screens> e <compatible-screens> no arquivo de manifesto. Usar os dois aumenta as chances de um erro de conflito entre eles. Se quiser ajuda para decidir qual usar, leia Distribuição para telas específicas. Se precisar usar os dois ao mesmo tempo, saiba que "falso" vence qualquer conflito de um determinado tamanho.
• Conjuntos de recursos do dispositivo

  Isso é baseado nos elementos <uses-feature> do arquivo de manifesto.

  Por exemplo, você pode fornecer um APK para dispositivos compatíveis com multitoque e outro para dispositivos não compatíveis com multitoque. Consulte a Referência de recursos para ver uma lista de recursos compatíveis com a plataforma.

• Android (versão Go)

  Para segmentar dispositivos que executam o Android (versão Go), seu APK precisa declarar <uses-feature android:name="android.hardware.ram.low" android:required="true">, direcionar pelo menos para o nível 26 da API e ter um código de versão mais recente do que o APK da edição não Go.

• Nível da API

  Isso é baseado no elemento <uses-sdk> do arquivo de manifesto. Você pode usar os atributos android:minSdkVersion e android:maxSdkVersion para especificar o suporte a diferentes níveis de API.

  Por exemplo, você pode publicar seu aplicativo com um APK compatível com os níveis de API 16 a 19 (Android 4.1.x a 4.4.4) usando apenas APIs disponíveis desde o nível 16 ou anteriores e outro APK compatível com os níveis de API 21 e mais recentes (Android 5.0+) usando APIs disponíveis desde o nível 21 ou anteriores. Para saber como criar APKs separados para um intervalo diferente de APIs, acesse Configurar variações de produtos.

  Se você usar essa característica como fator para distinguir vários APKs, o arquivo com um valor android:minSdkVersion maior precisará ter um valor android:versionCode maior. Isso também acontece quando dois APKs se sobrepõem à compatibilidade do dispositivo com base em um filtro compatível diferente. Isso garante que, quando um dispositivo receber uma atualização do sistema, o Google Play possa oferecer ao usuário uma atualização do aplicativo, já que atualizações são baseadas no aumento do código da versão do app. Esse requisito é descrito mais detalhadamente na seção abaixo sobre as Regras para vários APKs.

  Em geral, evite usar android:maxSdkVersion, já que, desde que você desenvolva corretamente o aplicativo com APIs públicas, ele sempre vai ser compatível com futuras versões do Android. Mesmo que você queira publicar um APK diferente para níveis de API maiores, não é necessário especificar a versão máxima, já que, se android:minSdkVersion é "16" em um APK e "21" em outro, os dispositivos compatíveis com a API de nível 21 ou posterior sempre recebem o APK com o maior código de versão, conforme observado acima.



• Arquitetura de CPU (ABI)

  Algumas bibliotecas nativas fornecem pacotes separados para arquiteturas de CPU específicas ou Interfaces binárias de aplicativo (ABIs). Em vez de empacotar todas as bibliotecas disponíveis em um APK, você pode criar um APK separado para cada ABI e incluir apenas as bibliotecas necessárias para ela. Para saber mais sobre como gerar APKs separados com base em uma ABI, consulte Desenvolver vários APKs.

Os outros elementos do manifesto que ativam filtros do Google Play, mas não estão listados acima, ainda são aplicados para cada APK, como de costume. No entanto, não é permitido publicar APKs separados com base nas variações dessas características do dispositivo no Google Play. Assim, não é possível publicar vários APKs se os filtros listados acima são os mesmos para cada um deles, mesmo que os APKs tenham diferenças em outras características no manifesto ou no arquivo. Por exemplo, não é possível fornecer APKs que diferem apenas pelas características de <uses-configuration>.

Regras para vários APKs

Antes de publicar vários APKs para seu aplicativo, é necessário entender as seguintes regras:

• Todos os APKs publicados para o mesmo aplicativo precisam ter o mesmo nome de pacote e ser assinados com a mesma chave de certificado.
• Cada APK precisa ter um código de versão diferente especificado pelo atributo android:versionCode.
• Um APK não pode corresponder exatamente ao suporte de configuração de outro APK.

  Ou seja, cada APK precisa declarar um suporte ligeiramente diferente a pelo menos um dos filtros aos quais o Google Play tem suporte listados acima.

  Normalmente, os APKs são diferenciados com base em uma característica específica, como os formatos compatíveis de compactação de textura, e, assim, cada um declara compatibilidade com diferentes dispositivos. No entanto, não há problema em publicar vários APKs que se sobrepõem um pouco em relação ao suporte. Quando dois APKs se sobrepõem (oferecem suporte a algumas das mesmas configurações), o dispositivo que se enquadra nesse intervalo de sobreposição recebe o APK com o maior código de versão (definido por android:versionCode).

• Não é possível ativar um novo APK com um código menor de versão do que o daquele que está sendo substituído. Por exemplo, digamos que você tenha um APK ativo para tamanhos de tela pequeno e normal com código de versão 0400 e tente substituí-lo por um APK para os mesmos tamanhos de tela com código de versão 0300. Isso gera um erro, já que os usuários do APK anterior não poderão atualizar o aplicativo.
• Um APK que requer um nível de API maior tem que ter um código de versão maior.

  Isso só acontece quando os APKs são diferentes apenas nos níveis de API compatíveis (nenhum outro filtro compatível distingue os APKs entre si) ou quando os APKs usam outro filtro compatível, mas há uma sobreposição entre os APKs nesse filtro.

  Isso é importante porque um dispositivo de usuário recebe uma atualização de aplicativo do Google Play somente quando o código da versão do APK no Play é maior do que o do APK presente no dispositivo. Isso garante que, caso um dispositivo receba uma atualização do sistema que o qualifique para instalar o APK para níveis maiores de API, ele recebe uma atualização devido ao aumento no código da versão.

  Observação: o tamanho do aumento no código da versão é irrelevante. Ele só precisa ser maior na versão compatível com níveis maiores de API.

  Veja alguns exemplos:

  • Se um APK carregado para API de nível 16 e mais recentes (Android 4.1.x+) tiver um código de versão de 0400, um APK para API de nível 21 e mais recentes (Android 5.0+) vai precisar ser de 0401 ou mais recente. Nesse caso, o nível da API é o único filtro com suporte usado. Por isso, os códigos da versão precisam aumentar em correlação com o suporte ao nível da API para cada APK para que os usuários recebam uma atualização.
  • Se você tem um APK para API de nível 16 e mais recentes e telas pequenas e grandes e outro APK para API de nível 21 e posteriores e telas grandes e extra grandes, os códigos de versão precisam aumentar em correlação com os níveis de API. Nesse caso, o filtro de nível da API é usado para distinguir cada APK, mas o tamanho da tela também é. Como os tamanhos de tela se sobrepõem (os dois APKs são compatíveis com telas grandes), os códigos de versão ainda precisam estar em ordem. Isso garante que um dispositivo de tela grande que recebe uma atualização do sistema para a API de nível 21 receba uma atualização para o segundo APK.
  • Se você tem um APK para API de nível 16 e mais recentes e telas pequenas e normais e outro APK para API de nível 21 e mais recentes e telas grandes e extra grandes, os códigos de versão não precisam aumentar em correlação com os níveis de API. Como não há sobreposição no filtro de tamanho de tela, não há dispositivos que poderiam alternar entre esses dois APKs. Portanto, não é necessário aumentar os códigos da versão do menor nível de API para o maior.
  • Se você tiver um APK para API de nível 16 e mais recentes e CPUs ARMv7 e outro APK para API de nível 21 e posteriores e CPUs ARMv5TE, os códigos de versão precisam aumentar em correlação com os níveis de API. Nesse caso, o filtro de nível da API é usado para distinguir cada APK, assim como a arquitetura da CPU. Como um APK com bibliotecas ARMv5TE oferece suporte a dispositivos que têm uma CPU ARMv7, os APKs se sobrepõem nessa característica. Dessa forma, o código de versão do APK compatível com o nível 21 da API e posteriores precisa ser maior. Isso garante que um dispositivo com uma CPU ARMv7 que recebe uma atualização do sistema para a API de nível 21 receba uma atualização para o segundo APK, que foi projetado para a API de nível 21. No entanto, como esse tipo de atualização faz com que o dispositivo ARMv7 use um APK que não foi completamente otimizado para a CPU dele, você precisa fornecer um APK para as arquiteturas ARMv5TE e ARMv7 em cada nível de API para otimizar a performance de cada CPU. Observação: isso se aplica apenas à comparação de APKs com as bibliotecas ARMv5TE e ARMv7, e não à comparação de outras bibliotecas nativas.

Deixar de seguir as regras acima causa um erro no Google Play Console ao ativar os APKs. Assim, não será possível publicar o aplicativo até que esse erro seja solucionado.

Há outros conflitos que podem ocorrer durante a ativação dos seus APKs, mas eles geram alertas e não erros. Os alertas podem ser causados pelos seguintes motivos:

• Quando você modifica um APK para "encolher" o suporte a características de um dispositivo, e nenhum outro APK oferece suporte aos dispositivos que, assim, ficam de fora do intervalo com suporte. Por exemplo, quando um APK oferece suporte a telas pequenas e de tamanho normal, mas você o muda para oferecer suporte apenas a telas pequenas, é necessário diminuir o número de dispositivos com suporte, e o aplicativo não fica mais disponível para alguns dispositivos no Google Play. Para resolver esse problema, adicione outro APK que tenha suporte a telas de tamanho normal para que todos os dispositivos continuem com suporte.
• Quando há "sobreposição" entre dois ou mais APKs. Por exemplo, se um APK oferece suporte a tamanhos de tela pequeno, normal e grande, enquanto outro oferece suporte a tamanhos grande e extra grande, há sobreposição, já que ambos têm suporte a telas grandes. Se você não resolver isso, os dispositivos qualificados para os dois APKs (dispositivos de tela grande) vão receber o que tiver o maior código de versão.

  Observação: se você estiver criando APKs separados para arquiteturas de CPU diferentes, tenha em mente que haverá sobreposição entre um APK para ARMv5TE e um APK para ARMv7. Isso significa que um APK projetado para ARMv5TE oferece suporte a um dispositivo ARMv7, mas o inverso não é verdadeiro, ou seja, um APK que tem apenas as bibliotecas ARMv7 não oferece suporte a um dispositivo ARMv5TE.

Quando conflitos como esses ocorrerem, você verá uma mensagem de alerta, mas ainda poderá publicar o aplicativo.

Como criar vários APKs

Depois de decidir publicar vários APKs, você provavelmente terá que criar projetos do Android diferentes para cada um deles para que possa desenvolvê-los separadamente de forma adequada. Para fazer isso, duplique seu projeto existente e atribua um novo nome a ele. Você também pode usar um sistema de compilação que gere recursos diferentes, como texturas, com base na configuração da compilação.

Dica: uma maneira de evitar a duplicação de partes grandes do código do aplicativo é usar um projeto de biblioteca. Um projeto de biblioteca contém código e recursos compartilhados, que você pode incluir nos seus projetos de aplicativos.

Ao criar vários projetos para o mesmo aplicativo, é recomendável identificar cada um com um nome que indique as restrições de dispositivo que serão inseridas no APK, para uma identificação mais fácil. Por exemplo, "HelloWorld_21" pode ser um bom nome para um aplicativo desenvolvido para a API de nível 21 e mais recentes.

Observação: todos os APKs publicados para o mesmo aplicativo precisam ter o mesmo nome de pacote e ser assinados com a mesma chave de certificado. Além disso, é importante entender cada uma das Regras para vários APKs.

Atribuir códigos de versão

Cada APK para o mesmo aplicativo precisa ter um código de versão exclusivo especificado pelo atributo android:versionCode. Tenha cuidado ao atribuir códigos de versão durante a publicação de vários APKs. Cada um precisa ser diferente, mas, em alguns casos, o código precisa ser definido em uma ordem específica com base nas configurações compatíveis com cada APK.

Ordenar códigos de versão

Um APK que precisa de um nível de API maior geralmente precisa ter um código de versão maior. Por exemplo, se você cria dois APKs compatíveis com níveis diferentes de API, o APK para os maiores níveis tem o maior código de versão. Isso garante que, caso um dispositivo receba uma atualização do sistema que o qualifique para instalar o APK para níveis maiores de API, o usuário recebe uma notificação para atualizar o aplicativo. Para saber mais sobre a aplicação desse requisito, consulte a seção acima sobre as Regras para vários APKs.

Considere também como a ordem dos códigos de versão pode afetar o APK recebido pelos usuários devido à sobreposição entre a cobertura de diferentes APKs ou às futuras modificações que você pode fazer nos arquivos.

Por exemplo, se você tem APKs diferentes com base no tamanho da tela, como um para telas pequenas e normais e um para telas grandes e extra grandes, mas pretende mudar os APKs para telas normais e extra grandes, programe o código de versão para que o APK para telas grandes e extra grandes seja maior. Assim, um dispositivo de tamanho normal vai receber a atualização adequada quando você fizer a mudança, já que o código da versão aumenta do APK existente para o novo, que agora oferece suporte ao dispositivo.

Além disso, ao criar vários APKs diferentes com base no suporte a diferentes formatos de compactação de textura do OpenGL, lembre-se de que muitos dispositivos oferecem suporte a vários formatos. Como um dispositivo recebe o APK com o maior código de versão quando há sobreposição na cobertura de dois APKs, organize os códigos de versão entre os APKs para que o APK com o formato de compactação preferido tenha o maior código de versão. Por exemplo, é interessante criar versões diferentes para seu app usando os formatos de compactação PVRTC, ATITC e ETC1. Se você preferir esses formatos nessa ordem, o APK que usa o PVRTC precisará ter o maior código de versão, enquanto o APK que usa o ATITC terá um código menor de versão, e a versão com o ETC1 terá o menor código. Assim, se um dispositivo tem suporte a PVRTC e ETC1, ele recebe o APK com PVRTC, que tem o maior código de versão.

Caso a Google Play Store não consiga identificar o APK correto a ser instalado em um dispositivo, crie um APK universal com recursos para todas as variações de dispositivos que você pretende alcançar. Se você fornecer um APK universal, atribua a ele o menor versionCode. Como a Google Play Store instala a versão do app que é compatível com o dispositivo de destino e tem o maior versionCode, atribuir um versionCode menor ao APK universal garante que a Google Play Store tente instalar um dos seus outros APKs antes do APK universal.

Usar um esquema de código de versão

Para permitir que APKs diferentes atualizem os códigos de versão independentemente de outros (por exemplo, quando você corrige um bug em apenas um APK, então não é necessário atualizar todos), use um esquema para seus códigos de versão com espaço suficiente entre cada APK para aumentar o código de um sem exigir um aumento nos outros. Inclua também o nome da versão real no código (ou seja, a versão visível do usuário atribuída a android:versionName) para facilitar a associação do código de versão ao nome da versão.

Observação: quando você aumenta o código da versão de um APK, o Google Play solicita que os usuários da versão anterior atualizem o aplicativo. Assim, para evitar atualizações desnecessárias, não é recomendado aumentar o código de versão dos APKs que não incluem modificações.

Sugerimos usar um código de versão com pelo menos 7 dígitos: números inteiros que representam as configurações compatíveis nos bits de ordem superior, enquanto o nome da versão (de android:versionName) nos bits de ordem inferior. Por exemplo, quando o nome da versão do aplicativo é 3.1.0, os códigos de versão para um APK para API de nível 4 e um APK para API de nível 11 seriam parecidos com 0400310 e 1100310, respectivamente. Os dois primeiros dígitos são reservados para o nível da API (4 e 11, respectivamente), os dois dígitos do meio são para os tamanhos de tela ou formatos de textura de GL (não usados nesses exemplos) e os três últimos são para o nome da versão do aplicativo (3.1.0). A Figura 1 mostra dois exemplos que se dividem com base na versão da plataforma (nível da API) e no tamanho da tela.

Figura 1. Um esquema sugerido para seus códigos de versão, usando os dois primeiros dígitos para o nível da API, o segundo e o terceiro para os tamanhos mínimo e máximo de tela (1 a 4, indicando cada um dos quatro tamanhos) ou para indicar os formatos de textura e os últimos três dígitos para a versão do app.

Esse esquema para códigos de versão é apenas uma sugestão para estabelecer um padrão escalável à medida que o aplicativo evolui. Esse esquema em particular não demonstra uma solução para identificar diferentes formatos de compactação de textura. Uma opção pode ser definir sua própria tabela para especificar um número inteiro diferente para cada formato de compactação compatível com o aplicativo (por exemplo, 1 pode corresponder a ETC1, 2 a ATITC etc.).

Você pode usar qualquer esquema, mas considere cuidadosamente como versões futuras do seu aplicativo vão precisar aumentar os códigos de versão correspondentes e como os dispositivos vão poder receber atualizações quando a configuração do dispositivo mudar (por exemplo, devido a uma atualização do sistema) ou quando você modificar o suporte de configuração de um ou mais APKs.