Si vous êtes un développeur Web et que vous débutez sur Android et Google Play, voici quelques informations à prendre en compte. Il existe déjà de nombreuses ressources et documentation à ce sujet (grâce à l'équipe Android), mais nous allons ici souligner certains concepts importants et leur lien avec le papier bulle.
Clé d'importation ou de signature
Si vous prévoyez d'utiliser Bubblewrap pour générer un Android App Bundle (AAB) (remarque: à partir d'août 2021, toutes les nouvelles applications devront utiliser le format Android App Bundle sur Google Play) ou l'APK pour l'importer et la publier sur Google Play, vous devrez signer votre application avec une clé de signature. Google Play vous propose deux options pour gérer cela:
- Signature d'application Play (fortement recommandé): 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 ne doit pas être privée. La clé d'importation vous permet de 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 au format AAB ou APK :
- Android App Bundle (AAB): lorsque vous importez un AAB dans la Play Console, vous reportez la compilation et la génération des APK au 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. Ainsi, si vous importez votre application dans la Play Console en tant qu'AAB, par défaut, vous devrez utiliser la signature d'application Play.
- APK: avec les APK, vous avez la possibilité d'activer la signature d'application Play. Nous vous recommandons vivement d'activer la signature d'application Play, car elle 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, il n'est pas possible de 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 accédez à la partie Informations sur la clé de signature (5/5), vous êtes invité à saisir un emplacement du keystore et un nom de clé, ou à utiliser les valeurs par défaut. L'emplacement par défaut du magasin de clés est le fichier android.keystore qui se trouve dans le répertoire de votre projet. Le nom de clé par défaut est android. Si Bubblewrap ne trouve pas de keystore existant portant ce nom de clé à l'emplacement, il en crée un pour vous et vous invite également à saisir des mots de passe. Prenez note des mots de passe que vous avez saisis, car vous en aurez besoin lors du processus de compilation (bubblewrap build), qui utilisera la clé pour signer votre application. Si vous activez la signature d'application Play, la clé de signature générée par Bubblewrap et utilisée pour signer votre application deviendra la "clé d'importation". Que vous choisissiez d'utiliser la clé générée par wrapper comme clé de signature ou d'importation, vous devez la protéger et la garder privée.
Nous vous déconseillons de l'activer pour le contrôle des versions. Limitez plutôt le nombre de personnes qui y ont accès.
Digital Asset Links
Vous devez utiliser Digital Asset Links 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 validée correctement et se lance en tant qu'activité Web sécurisée (au lieu d'un onglet personnalisé Chrome), vous devez ajouter la clé appropriée à votre fichier assetlinks.json. Ensuite, importez-la sur votre site Web à l'adresse .well-known/assetlinks.json (par rapport à la racine). Votre fichier assetlinks.json doit se présenter comme suit:
[{
"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 SHA256
Pour créer le fichier assetlinks.json, vous devez disposer de l'empreinte du certificat SHA 256 associée à la clé de signature de votre application. Il est important de noter que les empreintes associées à vos clés de signature et d'importation sont différentes. Il est important de garder cette distinction à l'esprit, en particulier si vous constatez que votre application se lance dans un onglet personnalisé Chrome (avec la barre du navigateur visible). Dans ce cas, il est probable que votre fichier assetlinks.json ne contienne pas l'empreinte correspondant à la touche 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 localement. Consultez la section Ajouter des clés ci-dessous pour en savoir plus sur l'intégration des deux clés dans le fichier assetlinks.json.
Vous pouvez obtenir l'empreinte de différentes manières, qui sont détaillées dans les sections suivantes. Elles devraient toutes 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 le service Signature d'application Play, vous pouvez disposer d'une ou deux clés. Pour récupérer l'empreinte SHA256 appropriée pour chaque clé, procédez comme suit:
- Accédez à la Play Console.
- Sélectionnez l'application qui vous intéresse.
- Dans le menu de navigation de gauche, sous Publier, accédez à Configuration -> Intégrité de l'appli.
- Copiez le SHA256 de la clé appropriée:
Clé de signature: copiez l'empreinte SHA256 du certificat de la 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 SHA256 du certificat de clé d'importation. Cette empreinte correspond à votre application si vous l'installez en local (via ADB sur USB, par exemple). Cet APK (sur votre ordinateur local) a été créé par Bubblewrap et a donc été signé par la clé qu'il a également 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 fait la "clé d'importation" une fois votre application publiée 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 au Bubblewrap APK ou AAB généré. Notez que cette empreinte est destinée à la clé de signature locale. Si vous importez votre application sur Play et que vous activez le service Signature d'application Play, cette clé devient la "clé d'importation".
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
Via l'outil Asset Links
Vous pouvez également obtenir le fichier Digital Asset Links qui correspond à votre application à l'aide de l'outil Asset Links:
- 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. Vous obtiendrez la liste de toutes les applications installées sur votre appareil par nom de package. Filtrez la liste en fonction de l'ID application que vous avez choisi précédemment lors de
bubblewrap init, puis cliquez sur cette entrée. - Une page affiche la signature de votre application ainsi qu'un lien Digital Asset Link généré. Cliquez sur les boutons "Copier" ou "Partager" en bas pour exporter le document comme vous le souhaitez (par exemple, l'enregistrer dans Google Keep ou l'envoyer à vous-même par e-mail).
Le même principe s'applique qu'auparavant avec les clés de signature ou d'importation. Si vous avez installé votre application à partir du Google Play Store, l'outil Asset Link vous fournit 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é Bubblewrap générée.
S'assurer que le fichier des liens d'éléments est accessible
Maintenant que vous l'avez importé, vérifiez que vous pouvez accéder à votre fichier Asset Links dans un navigateur.
Vérifiez que https://example.com/.well-known/assetlinks.json est résolu dans le fichier que vous venez d'importer.
Sites Web basés sur Jekyll
Si votre site Web est généré par Jekyll (par exemple, des pages GitHub), vous devez ajouter une ligne de configuration afin que le répertoire .well-known soit inclus dans le résultat.
L'aide GitHub contient plus d'informations à ce sujet.
Créez un fichier nommé _config.yml à la racine de votre site (ou ajoutez-le 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 Links peut contenir plusieurs applications, voire plusieurs clés pour chaque application. Par exemple, pour ajouter une deuxième clé, utilisez simplement l'outil Asset Link pour déterminer la clé et l'ajouter en tant que deuxième entrée. Le code qui analyse ce fichier JSON dans Chrome est assez strict. Vous devez donc vous assurer de 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 enregistre la raison de l'échec de la validation Digital Asset Links. Vous pouvez afficher les journaux sur un appareil Android avec adb logcat.
Si vous développez sous Linux ou Mac, vous pouvez afficher les journaux pertinents à partir d'un appareil connecté à l'aide de la commande suivante:
> 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 Links pour afficher la signature de votre application et vous assurer qu'elle correspond à celle indiquée dans votre fichier assetlinks.json.