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 versus 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 de como você pode lidar com isso:
- Assinatura de apps do Google Play (altamente recomendado): o Google vai gerenciar e proteger 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 particular. Você usa a chave de upload para assinar o app e fazer o 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. No momento, 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 do seu app e o instala, 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, se você perder a chave de assinatura do app, não será mais possível 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
inseridas porque 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 que o Bubblewrap
gerou e usou para assinar o app 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 a confirmação do controle de versões. 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 o upload dele para seu site em .well-known/assetlinks.json (relativo à raiz). Seu 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 ter
essa distinção em mente, 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
Se você ativar ou não a Assinatura de apps do Google Play, poderá ter uma ou duas chaves. Para recuperar a impressão digital SHA256 adequada 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 do 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 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 de
init). Essa pode ser a chave de assinatura do app instalado localmente, mas na verdade se torna a "chave de upload" quando 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 é usada para a chave de assinatura local e, 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 vinculação 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 pela 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 de antes com as chaves de assinatura ou de upload. Se você instalou o app pela Google Play Store, a ferramenta Asset Link vai receber 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 gerada pelo Bubblewrap.
Garantir que o arquivo do link de recurso esteja 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]
Como 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, use 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.