Se você é um desenvolvedor da Web que está começando a usar o Android e o Google Play, há alguns detalhes que você precisa conhecer. Já existem muitos recursos e documentação para isso (graças à equipe do Android), mas aqui vamos destacar alguns conceitos importantes e como eles se relacionam com o Bubblewrap.
Chave de upload e chave de assinatura
Se você planeja usar o Bubblewrap para gerar um Android App Bundle (AAB) (Observação: a partir de agosto de 2021, o Google Play vai exigir que todos os novos apps usem o formato Android App Bundle) ou APK para fazer upload e publicar no Google Play, será necessário assinar seu app com uma chave de assinatura. O Google Play oferece duas opções para lidar com isso:
- Assinatura de apps do Google Play (altamente recomendada): o Google gerencia e protege a chave de assinatura do app
para você. Ela é usada para assinar seus APKs para distribuição. A Assinatura de apps do Google Play usa duas chaves. A "chave de assinatura
do app", que o Google vai gerenciar para você, e a "chave de upload", que você mantém e precisa permanecer
privada. Você usa a chave de upload para assinar o app e fazer upload dele no Play Console. Esse
sistema permite que você redefina a chave de upload se ela for perdida ou comprometida. Para isso, entre em contato com a equipe de suporte do Google Play. Atualmente, o Google Play
permite fazer upload do app como um AAB ou APK:
- Android App Bundle (AAB): ao fazer upload de um AAB para o Play Console, você adia a criação e a geração de APKs para a Google Play Store. Quando um usuário faz o download e instala seu app, o Google Play o distribui como um APK assinado. Portanto, a assinatura dos APKs também precisa ser feita pelo Google Play. Por padrão, se você fizer upload do app como um AAB no Play Console, será necessário usar a Assinatura de apps do Google Play.
- APK: com os APKs, você pode ativar a Assinatura de apps do Google Play. É altamente recomendável ativar a Assinatura de apps do Google Play, porque ela aumenta a segurança da chave de assinatura. Como observado anteriormente, em breve o Google Play vai exigir que todos os novos apps sejam enviados no formato AAB. Recomendamos fazer isso em vez de enviar APKs.
- Gerenciar sua própria chave de assinatura: se você optar por gerenciar sua própria chave e não ativar a Assinatura de apps do Google Play, será totalmente responsável pela chave de assinatura do app. Ao contrário da Assinatura de apps do Google Play, não é possível redefinir a chave se você a perder. Portanto, perder a chave de assinatura do app significa que você também não poderá mais atualizá-lo.
Durante a configuração do bubblewrap init, quando você chegar à parte "Informações da chave de assinatura (5/5)",
será necessário inserir um "Local do keystore" e "Nome da chave" ou usar os padrões. O
local padrão do repositório de chaves é o arquivo android.keystore no diretório do projeto, e o nome de chave
padrão é android. Se o Bubblewrap não encontrar um keystore com esse nome de chave no
local, ele vai criar um e solicitar senhas. Anote as senhas
que você inseriu, porque elas serão necessárias durante o processo de build (bubblewrap build), em que a chave
será usada para assinar o app. Se você ativar a Assinatura de apps do Google Play, a chave de assinatura gerada e usada pelo Bubblewrap
para assinar o app vai se tornar a "chave de upload". Se você optar por usar a
chave gerada pelo Bubblewrap como chave de assinatura ou upload, proteja e mantenha a chave em segredo.
Não recomendamos fazer o commit dele no controle de versão. Em vez disso, limite o número de pessoas com
acesso a ele.
Digital Asset Links
Os links de recursos digitais são necessários para declarar a relação entre seu site e o app
Android. Para garantir que o app Android gerado pelo Bubblewrap seja verificado corretamente e iniciado como uma
atividade da Web confiável (em vez de uma guia personalizada do Chrome), adicione a chave adequada ao
arquivo assetlinks.json. Em seguida, faça upload dele no seu site em .well-known/assetlinks.json
(relativo à raiz). O arquivo assetlinks.json precisa seguir este formato:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.your.package_name",
"sha256_cert_fingerprints": [
"XX:XX:XX:..."
]
}
}]
Acessar a impressão digital do certificado SHA256
Para criar o arquivo assetlinks.json, você vai precisar da impressão digital do certificado SHA 256 associada
à chave de assinatura do app. É importante observar que as impressões digitais associadas às
chaves de assinatura e upload são diferentes. É importante manter
essa distinção, especialmente se você observar o app sendo iniciado como uma guia personalizada do Chrome (com
a barra do navegador visível). Nesse caso, é provável que o arquivo assetlinks.json não tenha a
impressão digital que corresponde à chave adequada.
É útil ter a impressão digital do certificado de assinatura e upload no arquivo assetlinks.json
para depurar o app localmente com mais facilidade. Consulte Adicionar mais chaves abaixo para mais
informações sobre como ter as duas chaves no arquivo assetlinks.json.
Há algumas maneiras diferentes de conseguir a impressão digital, que são detalhadas nas próximas seções. Todos eles vão gerar as mesmas impressões digitais. Escolha o método mais conveniente.
Pelo Play Console
Dependendo se você ativar ou não a Assinatura de apps do Google Play, você pode ter uma ou duas chaves. Para recuperar a impressão digital SHA256 adequada para cada chave:
- Acesse o Play Console.
- Selecione o app de seu interesse
- No menu de navegação à esquerda, em Versão, acesse Configuração -> Integridade do app.
- Copie o SHA256 para a chave apropriada:
Chave de assinatura: copie a impressão digital SHA256 do "Certificado da chave de assinatura do app". Esse impresso digital vai corresponder ao seu app se você fizer o download dele na Google Play Store, já que o Google Play distribui seu app assinado com a chave de assinatura.
Chave de upload: copie a impressão digital SHA256 para o "Certificado de chave de upload". Essa impressão digital vai corresponder ao seu app se você o instalar localmente (por exemplo, pelo ADB por USB). Esse APK (na sua máquina local) foi criado pelo Bubblewrap e, portanto, assinado pela chave criada para você (durante a configuração
init). Lembre-se de que essa pode ser a chave de assinatura do app instalado localmente, mas ela se torna a "chave de upload" depois que você publica o app no Google Play.
Via keytool
O keytool é uma ferramenta de gerenciamento de chaves e certificados. É possível usar o keytool para extrair a impressão digital SHA 256 associada ao Bubblewrap gerado pelo APK ou AAB. Essa impressão digital é para a chave de assinatura local. Se você fizer upload do app no Google Play e ativar a Assinatura de apps do Google Play, essa chave vai se tornar a "chave de upload".
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
Na ferramenta de link de recursos
Outra maneira de conseguir o arquivo Digital Asset Links correto para seu app é usar a Ferramenta de vinculação de recursos:
- Instale a Ferramenta de vinculação de recursos na Play Store.
- No mesmo dispositivo, faça o download do app na Google Play Store ou instale-o localmente.
- Abra o app Asset Link Tool e confira uma lista de todos os aplicativos instalados no
dispositivo por nome de pacote. Filtre a lista pelo ID do aplicativo escolhido anteriormente durante
bubblewrap inite clique na entrada. - Uma página vai aparecer com a assinatura do app e um Link de recursos digitais gerado. Clique nos botões "Copiar" ou "Compartilhar" na parte de baixo para exportar da maneira que quiser (por exemplo, salvar no Google Keep ou enviar para você mesmo por e-mail).
A mesma ideia se aplica às chaves de assinatura ou de upload. Se você instalou o app na Google Play Store, a ferramenta de vinculação de recursos vai gerar a impressão digital da chave de assinatura do app. Se você instalou o app diretamente na máquina local, a impressão digital é da chave Bubblewrap gerada.
Como garantir que o arquivo de link de recurso seja acessível
Depois de fazer o upload, verifique se você consegue acessar o arquivo de link de recursos em um navegador.
Verifique se https://example.com/.well-known/assetlinks.json resolve para o arquivo que você acabou de enviar.
Sites baseados em Jekyll
Se o site for gerado pelo Jekyll (como o GitHub Pages), será necessário adicionar uma linha de
configuração para que o diretório .well-known seja incluído na saída.
A Ajuda do GitHub tem mais informações sobre esse assunto.
Crie um arquivo chamado _config.yml na raiz do seu site (ou adicione a ele se ele já existir) e
digite:
# Folders with dotfiles are ignored by default.
include: [.well-known]
Adicionar mais chaves
Um arquivo Digital Asset Link pode conter mais de um app e, para cada app, mais de uma chave. Por exemplo, para adicionar uma segunda chave, basta usar a Ferramenta de vinculação de recursos para determinar a chave e adicioná-la como uma segunda entrada. O código no Chrome que analisa esse JSON é bastante rigoroso. Portanto, não adicione uma vírgula extra acidentalmente no final da lista.
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.your.package_name",
"sha256_cert_fingerprints": [
"XX:XX:XX:..."
]
}
},{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.your.package_name",
"sha256_cert_fingerprints": [
"XX:XX:XX:..."
]
}
}]
Solução de problemas
O Chrome registra o motivo da falha na verificação do Digital Asset Links, e você pode conferir os registros em um
dispositivo Android com adb logcat.
Se você estiver desenvolvendo no Linux/Mac, poderá conferir os registros relevantes de um dispositivo conectado
com:
> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links
Por exemplo, se você receber a mensagem Statement failure matching fingerprint., use a
Ferramenta de vinculação de recursos para conferir a assinatura do app e garantir que ela corresponda à do arquivo
assetlinks.json.