Se você é um desenvolvedor da Web novo no Android e no Google Play, há alguns detalhes que 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 x 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 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 recomendado): o Google vai gerenciar e proteger a chave de assinatura do seu app
para você. Ele é usado 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 continuar
privada para você. Use a chave de upload para assinar os apps durante os uploads para o Play Console. Esse
sistema permite que você redefina sua chave de upload se ela for perdida ou comprometida
entrando 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 fizer o download e instalar seu app, o Google Play o distribuirá como um APK assinado. Portanto, a assinatura dos APKs também precisará ser feita pelo Google Play. Portanto, 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ê tem a opção de ativar a Assinatura de apps do Google Play. A ativação da Assinatura de apps do Google Play é altamente recomendada porque aumenta a segurança da sua chave de assinatura. Conforme observado antes, em breve o Google Play exigirá que todos os novos apps sejam enviados no formato AAB. Por isso, recomendamos fazer isso em vez de fazer o upload de APKs.
- Gerenciar sua própria chave de assinatura: se optar por gerenciar sua própria chave e não ativar a Assinatura de apps do Google Play, você será totalmente responsável pela chave de assinatura do seu app. Ao contrário da Assinatura de apps do Google Play, não é possível redefini-la caso você perca a chave. Portanto, a perda da chave de assinatura significa que você também não pode mais atualizar o app.
Durante a configuração do bubblewrap init, ao chegar à seção "Informações da chave de assinatura (5/5)",
você vai precisar inserir um "Local de armazenamento da chave" e "Nome da chave" ou usar o padrão. O
local padrão de armazenamento da chave é o arquivo android.keystore no diretório do projeto, e o nome
padrão da chave é 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
inseridas 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 pelo Bubblewrap
e usada para assinar seu app se tornará a "chave de upload". Se você optar por usar a
chave gerada pelo Bubblewrap como sua chave de assinatura ou de upload, é necessário proteger e manter a chave privada.
Não recomendamos a confirmação para controle de versões. Em vez disso, limite o número de pessoas com acesso a ele.
Digital Asset Links
O Digital Asset Links é necessário para declarar a relação entre o site e o app
Android. Para garantir que o app Android gerado pelo Bubblewrap seja verificado corretamente e seja iniciado como uma
atividade confiável na Web (em vez de uma guia personalizada do Chrome), será necessário adicionar a chave adequada ao
arquivo assetlinks.json. Em seguida, faça upload dele no seu site em .well-known/assetlinks.json (em relação à 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:..."
]
}
}]
Receber a impressão digital do certificado SHA256
Para criar o arquivo assetlinks.json, você precisa da impressão digital do certificado SHA 256 associada
à chave de assinatura do app. É importante observar que as impressões digitais associadas às suas chaves de assinatura e de upload serão diferentes. É importante ter
essa distinção em mente, especialmente se você observar seu app sendo iniciado como uma guia personalizada do Chrome (com
a barra do navegador visível). É 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 de upload no assetlinks.json
para depurar o app localmente com mais facilidade. Consulte Como adicionar mais chaves abaixo para mais
informações sobre como ter ambas as chaves no arquivo assetlinks.json.
Há algumas maneiras diferentes de conseguir a impressão digital, que serão detalhadas nas próximas seções. Todos eles precisam fornecer as mesmas impressões digitais, então você pode escolher o método mais conveniente.
Pelo Play Console
Dependendo da ativação ou não da Assinatura de apps do Google Play, talvez você tenha uma ou duas chaves. Para recuperar a impressão digital SHA256 apropriada para cada chave:
- Acesse o Play Console.
- Selecione o app do 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 para o Certificado da chave de assinatura do app. Essa impressão digital vai corresponder ao seu app se você fizer o download dele na Google Play Store, já que o Google Play distribui o app assinado com a chave de assinatura.
Chave de upload: copie a impressão digital SHA256 para o Certificado da chave de upload. Essa impressão digital vai corresponder ao seu app se você o instalar localmente (via adb via USB, por exemplo). Esse APK (na máquina local) foi criado pelo Bubblewrap e, portanto, assinado pela chave que ele criou para você também durante a configuração do
init. Essa pode ser a chave de assinatura do app instalado localmente, mas, na verdade, ela se torna a "chave de upload" quando o app é publicado pelo 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 APK ou ao AAB Bubblewrap gerado. 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 se tornará a "chave de upload".
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
Pela ferramenta de link de recursos
Outra maneira de gerar o arquivo Digital Asset Links correto para seu app é usar a Asset Link Tool:
- Instale a Ferramenta de link de recursos pela Play Store.
- No mesmo dispositivo, faça o download do app pela Google Play Store ou instale-o localmente.
- Abra o app Asset Link Tool para ver uma lista de todos os apps instalados no
dispositivo pelo nome do pacote. Filtre a lista pelo ID do aplicativo que você escolheu anteriormente durante
bubblewrap inite clique nessa entrada. - Você verá uma página listando a assinatura do app e um Digital Asset Link gerado. Clique nos botões "Copiar" ou "Compartilhar" na parte inferior para exportar como quiser (por exemplo, salvar no Google Keep, enviar para seu próprio e-mail).
A mesma ideia é aplicada com as chaves de assinatura ou de upload. Se você instalou o app pela Google Play Store, a Asset Link Tool receberá a impressão digital da chave de assinatura dele. Se você instalou o app diretamente na máquina local, a impressão digital é da chave Bubblewrap gerada.
Como garantir que o arquivo do link de recursos esteja acessível
Depois de fazer o upload, verifique se é possível acessar o arquivo do link de recursos em um navegador.
Verifique se https://example.com/.well-known/assetlinks.json resulta no arquivo que você acabou de enviar.
Sites baseados em Jekyll
Se o site for gerado pelo Jekyll (como as Páginas do GitHub), será necessário adicionar uma linha de configuração para que o diretório .well-known seja incluído na saída.
Consulte a ajuda do GitHub mais informações sobre esse tópico.
Crie um arquivo chamado _config.yml na raiz do seu site (ou adicione-o, se ele já existir) e insira:
# Folders with dotfiles are ignored by default.
include: [.well-known]
Adicionar mais chaves
Um arquivo do Digital Asset Link pode conter mais de um app e, para cada app, pode conter mais de uma chave. Por exemplo, para adicionar uma segunda chave, basta usar a Asset Link Tool 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 acidentalmente uma vírgula extra 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 permite visualizar os registros em um
dispositivo Android com adb logcat.
Se você está desenvolvendo no Linux/Mac, pode ver 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 link de recursos para conferir a assinatura do app e verificar se ela corresponde a ela no arquivo
assetlinks.json.