Si vous êtes un développeur Web qui ne connaît pas encore Android et Google Play, vous devez prendre en compte certains points. De nombreuses ressources et documentations existent déjà à ce sujet (merci à l'équipe Android), mais nous allons ici mettre en avant certains concepts importants et leur lien avec Bubblewrap.
Clé d'importation ou clé de signature
Si vous prévoyez d'utiliser Bubblewrap pour générer un Android App Bundle (remarque: à partir d'août 2021, Google Play exigera que toutes les nouvelles applications utilisent le format Android App Bundle) ou un APK à importer et publier sur Google Play, vous devrez signer votre application avec une clé de signature. Google Play vous propose deux options pour gérer ce problème:
- Signature d'application Play (recommandée): Google gère et protège la clé de signature de votre application à votre place. Il l'utilise pour signer vos APK en vue de leur distribution. La signature d'application Play utilise deux clés. La "clé de signature d'application" que Google gérera pour vous et la "clé d'importation" que vous conservez et qui doit rester privée. Vous utilisez la clé d'importation pour signer votre application afin de l'importer dans la Play Console. Ce système vous permet de réinitialiser votre clé d'importation si elle est perdue ou compromise en contactant l'équipe d'assistance Play. Actuellement, Google Play vous permet d'importer votre application en tant qu'AAB ou APK :
- Android App Bundle (AAB): lorsque vous importez un AAB dans la Play Console, vous différez la compilation et la génération d'APK vers le Google Play Store. Lorsqu'un utilisateur télécharge et installe votre application, Google Play la lui distribue sous la forme d'un APK signé. Par conséquent, la signature des APK doit également être effectuée par Google Play. Par défaut, si vous importez votre application en tant qu'AAB dans la Play Console, vous devrez utiliser la signature d'application Play.
- APK: avec les APK, vous pouvez choisir d'activer la signature d'application Play. Nous vous recommandons vivement d'activer Play App Signing, car cela renforce la sécurité de votre clé de signature. Comme indiqué précédemment, Google Play exigera bientôt que toutes les nouvelles applications soient importées au format AAB. Nous vous recommandons donc de le faire au lieu d'importer des APK.
- Gérer votre propre clé de signature: si vous choisissez de gérer votre propre clé et de ne pas activer la signature d'application Play, vous êtes entièrement responsable de la clé de signature de votre application. Contrairement à la signature d'application Play, vous ne pouvez pas la réinitialiser si vous perdez la clé. Par conséquent, si vous perdez la clé de signature de votre application, vous ne pourrez plus la mettre à jour.
Lors de la configuration de bubblewrap init, lorsque vous arrivez à la section Informations sur la clé de signature (5/5)", vous êtes invité à saisir un emplacement de magasin de clés et un nom de clé, ou à utiliser les valeurs par défaut. L'emplacement par défaut du keystore est le fichier android.keystore dans le répertoire de votre projet, et le nom de clé par défaut est android. Si Bubblewrap ne trouve pas de keystore existant avec ce nom de clé à l'emplacement, il en crée un pour vous et vous demande également des mots de passe. Notez les mots de passe que vous avez saisis, car vous en aurez besoin lors du processus de compilation (bubblewrap build), où la clé sera utilisée pour signer votre application. Si vous activez la signature d'application Play, la clé de signature générée et utilisée par Bubblewrap pour signer votre application devient la "clé d'importation". Que vous choisissiez d'utiliser la clé générée par Bubblewrap comme clé de signature ou d'importation, vous devez la protéger et la conserver de manière privée.
Nous vous déconseillons de l'ajouter au contrôle des versions. Limitez plutôt le nombre de personnes qui y ont accès.
Digital Asset Links
Les liens d'éléments numériques sont nécessaires pour déclarer la relation entre votre site Web et votre application Android. Pour vous assurer que votre application Android générée par Bubblewrap est correctement validée et lancée en tant qu'activité Web fiable (plutôt qu'en tant qu'onglet personnalisé Chrome), vous devez ajouter la clé appropriée à votre fichier assetlinks.json. Importez-le ensuite sur votre site Web à l'adresse .well-known/assetlinks.json (par rapport à la racine). Votre fichier assetlinks.json doit respecter le format suivant:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.your.package_name",
"sha256_cert_fingerprints": [
"XX:XX:XX:..."
]
}
}]
Obtenir l'empreinte du certificat SHA-256
Pour créer le fichier assetlinks.json, vous avez besoin de l'empreinte du certificat SHA 256 associée à la clé de signature de votre application. Il est important de noter que les empreintes digitales associées à vos clés de signature et d'importation seront différentes. Il est important de garder cette distinction à l'esprit, en particulier si vous observez le lancement de votre application en tant qu'onglet personnalisé pour Chrome (avec la barre du navigateur visible). Il est alors probable que votre fichier assetlinks.json ne contienne pas l'empreinte qui correspond à la clé appropriée.
Il est utile d'inclure l'empreinte de votre certificat de signature et d'importation dans votre fichier assetlinks.json pour déboguer plus facilement votre application en local. Pour savoir comment ajouter les deux clés au fichier assetlinks.json, consultez la section Ajouter d'autres clés ci-dessous.
Il existe plusieurs façons d'obtenir l'empreinte, qui sont détaillées dans les sections suivantes. Ils devraient tous vous donner les mêmes empreintes. N'hésitez donc pas à choisir la méthode la plus pratique.
Via la Play Console
Selon que vous activez ou non la signature d'application Play, vous pouvez avoir une ou deux clés. Pour récupérer l'empreinte SHA256 appropriée pour chaque clé:
- Accédez à la Play Console.
- Sélectionner l'application qui vous intéresse
- Dans le menu de navigation de gauche, sous Version, accédez à Configuration -> Intégrité de l'application.
- Copiez le SHA-256 de la clé appropriée:
Clé de signature: copiez l'empreinte SHA256 du "Certificat de clé de signature d'application". Cette empreinte correspond à votre application si vous la téléchargez depuis le Google Play Store, car Google Play distribue votre application signée avec la clé de signature.
Clé d'importation: copiez l'empreinte SHA-256 du certificat de clé d'importation. Cette empreinte correspondra à votre application si vous l'installez en local (via ADB via USB, par exemple). Cet APK (sur votre machine locale) a été créé par Bubblewrap et est donc également signé par la clé qu'il a créée pour vous (lors de la configuration de
init). N'oubliez pas qu'il peut s'agir de la clé de signature de votre application installée localement, mais qu'elle devient en réalité la "clé d'importation" une fois que vous publiez votre application via Play.
Via keytool
keytool est un outil de gestion des clés et des certificats. Vous pouvez utiliser keytool pour extraire l'empreinte SHA-256 associée à l'APK ou à l'AAB Bubblewrap généré. Notez que cette empreinte est destinée à la clé de signature locale. Si vous importez votre application sur Play et activez la Signature d'application Play, cette clé devient la "clé d'importation".
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
Via l'outil de liaison des composants
Vous pouvez également obtenir le bon fichier Digital Asset Links pour votre application à l'aide de l'outil Asset Link:
- Installez l'outil Asset Link depuis le Play Store.
- Sur le même appareil, téléchargez votre application depuis le Google Play Store ou installez-la localement.
- Ouvrez l'application Asset Link Tool. La liste de toutes les applications installées sur votre appareil s'affiche par nom de package. Filtrez la liste par ID d'application que vous avez choisi précédemment lors de
bubblewrap init, puis cliquez sur cette entrée. - Une page s'affiche, sur laquelle figurent la signature de votre application et un Digital Asset Link généré. Cliquez sur les boutons "Copier" ou "Partager" en bas pour l'exporter comme vous le souhaitez (par exemple, l'enregistrer dans Google Keep ou vous l'envoyer par e-mail).
Le même principe s'applique qu'avec les clés de signature ou d'importation. Si vous avez installé votre application depuis le Google Play Store, l'outil Asset Link vous fournira l'empreinte de la clé de signature de votre application. Si vous avez installé l'application directement à partir de votre ordinateur local, l'empreinte correspond à la clé générée par Bubblewrap.
Assurez-vous que votre fichier de lien d'éléments est accessible
Maintenant que vous l'avez importé, assurez-vous d'y accéder dans un navigateur.
Vérifiez que https://example.com/.well-known/assetlinks.json renvoie le fichier que vous venez d'importer.
Sites Web basés sur Jekyll
Si votre site Web est généré par Jekyll (comme GitHub Pages), vous devez ajouter une ligne de configuration pour que le répertoire .well-known soit inclus dans la sortie.
Pour en savoir plus, consultez l'aide GitHub.
Créez un fichier nommé _config.yml à la racine de votre site (ou ajoutez-y un fichier s'il existe déjà) et saisissez:
# Folders with dotfiles are ignored by default.
include: [.well-known]
Ajouter des clés
Un fichier Digital Asset Link peut contenir plusieurs applications, et pour chaque application, il peut contenir plusieurs clés. Par exemple, pour ajouter une deuxième clé, il vous suffit d'utiliser l'outil Asset Link pour déterminer la clé et l'ajouter en tant que deuxième entrée. Le code de Chrome qui analyse ce JSON est assez strict. Veillez donc à ne pas ajouter accidentellement une virgule supplémentaire à la fin de la liste.
[{
"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:..."
]
}
}]
Dépannage
Chrome consigne la raison pour laquelle la validation Digital Asset Links échoue. Vous pouvez consulter les journaux sur un appareil Android avec adb logcat.
Si vous développez sur Linux/Mac, vous pouvez afficher les journaux pertinents d'un appareil connecté avec:
> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links
Par exemple, si le message Statement failure matching fingerprint. s'affiche, vous devez utiliser l'outil Asset Link pour afficher la signature de votre application et vous assurer qu'elle correspond à celle de votre fichier assetlinks.json.