אם אתם מפתחי אינטרנט שמתחילים לעבוד עם Android ו-Google Play, יש כמה פרטים שכדאי לדעת. כבר יש הרבה משאבים ומסמכי עזרה בנושא הזה (תודה לצוות Android), אבל כאן נתמקד במושגים חשובים מסוימים ובאופן שבו הם קשורים ל-Bubblewrap.
מפתח העלאה לעומת מפתח חתימה
אם אתם מתכננים להשתמש ב-Bubblewrap כדי ליצור קובץ Android App Bundle (AAB) (הערה: החל מאוגוסט 2021, Google Play תחייב את כל האפליקציות החדשות להשתמש בפורמט Android App Bundle) או קובץ APK כדי להעלות ולפרסם ב-Google Play, תצטרכו לחתום על האפליקציה באמצעות מפתח חתימה. ב-Google Play יש שתי אפשרויות לטיפול בבעיה הזו:
- חתימת אפליקציות ב-Play (מומלץ מאוד): Google מנהלת את חתימת האפליקציה שלכם ומגינה עליה. הוא משמש לחתימה על חבילות ה-APK להפצה. התכונה 'חתימת אפליקציה ב-Play' משתמשת בשני מפתחות. 'מפתח חתימת האפליקציה', ש-Google מנהלת בשבילכם, ו'מפתח ההעלאה', שנשאר אצלכם וצריך להישאר פרטי. משתמשים במפתח ההעלאה כדי לחתום על האפליקציה לפני ההעלאה ל-Play Console. המערכת הזו מאפשרת לכם לפנות לצוות התמיכה של Play כדי לאפס את מפתח ההעלאה אם הוא אבד או נחשף. נכון לעכשיו, ב-Google Play אפשר להעלות את האפליקציה כקובץ AAB או APK:
- Android App Bundle (AAB): כשאתם מעלים AAB ל-Play Console, אתם מעבירים את היצירה וההרצה של חבילות ה-APK לחנות Google Play. כשמשתמש מוריד ומתקין את האפליקציה, מערכת Google Play מפיצה אותה אליו כקובץ APK חתום. לכן, גם חתימת קובצי ה-APK תתבצע על ידי Google Play. לכן, כברירת מחדל, אם תעלו את האפליקציה כ-AAB ל-Play Console, תצטרכו להשתמש בחתימת אפליקציות Play.
- קובץ APK: בקובצי APK, יש לכם אפשרות להביע הסכמה לתוכנית 'חתימת אפליקציה ב-Play'. מומלץ מאוד להביע הסכמה לשימוש בתכונה 'חתימת אפליקציה ב-Play', כי היא מגבירה את האבטחה של מפתח החתימה. כפי שצוין למעלה, בקרוב יהיה צורך להעלות את כל האפליקציות החדשות בפורמט AAB ב-Google Play, לכן מומלץ לעשות זאת במקום להעלות חבילות APK.
- ניהול מפתח החתימה שלכם: אם תבחרו לנהל את המפתח שלכם ולא להביע הסכמה לשימוש בחתימת אפליקציה של Play, אתם תהיו אחראים באופן מלא למפתח החתימה של האפליקציה. בניגוד ל'חתימת אפליקציה ב-Play', אי אפשר לאפס את המפתח אם הוא אבד. לכן, אם מפתח החתימה של האפליקציה יאבד, לא תוכלו לעדכן את האפליקציה.
במהלך ההגדרה של bubblewrap init, כשמגיעים לקטע Signing key information (5/5), מופיעה בקשה להזין את Key store location ואת Key name, או להשתמש בערכי ברירת המחדל. המיקום שמוגדר כברירת מחדל למאגר המפתחות הוא הקובץ android.keystore בספריית הפרויקט, ושם המפתח שמוגדר כברירת מחדל הוא android. אם Bubblewrap לא ימצא מאגר מפתחות קיים עם שם המפתח הזה במיקום, הוא ייצור עבורכם מאגר מפתחות וישאל אתכם גם על סיסמאות. חשוב לשים לב לסיסמאות שהזנתם, כי תצטרכו אותן בתהליך ה-build (bubblewrap build), שבו המפתח ישמש לחתימה על האפליקציה. אם תבחרו להשתמש ב-Play App Signing, מפתח החתימה שנוצר על ידי Bubblewrap ומשמש לחתימה על האפליקציה יהפוך ל'מפתח העלאה'. בין אם בחרתם להשתמש במפתח שנוצר על ידי Bubblewrap כמפתח לחתימה או כמפתח העלאה, עליכם לשמור על הפרטיות של המפתח.
לא מומלץ לבצע השמירה במערכת בקרת הגרסאות. במקום זאת, כדאי להגביל את מספר האנשים שיש להם גישה אליו.
Digital Asset Links
קישורי נכסים דיגיטליים נדרשים כדי להצהיר על הקשר בין האתר לאפליקציה ל-Android. כדי לוודא שאפליקציית Android שנוצרה על ידי Bubblewrap מאומתת כראוי ופועלת כפעילות מהימנה באינטרנט (במקום ככרטיסייה מותאמת של Chrome), צריך להוסיף את המפתח המתאים לקובץ assetlinks.json. לאחר מכן, מעלים אותו לאתר בכתובת .well-known/assetlinks.json
(ביחס לשורש). קובץ assetlinks.json צריך להיות בפורמט הזה:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.your.package_name",
"sha256_cert_fingerprints": [
"XX:XX:XX:..."
]
}
}]
אחזור טביעת האצבע של אישור SHA256
כדי ליצור את הקובץ assetlinks.json, תצטרכו את טביעת האצבע של האישור ב-SHA 256 שמשויכת למפתח החתימה של האפליקציה. חשוב לציין שהטביעות האצבע שמשויכות למפתחות החתימה וההעלאה יהיו שונות. חשוב לזכור את ההבדל הזה, במיוחד אם האפליקציה מופעלת ככרטיסייה מותאמת ב-Chrome (כשסרגל הדפדפן גלוי). במקרה כזה, סביר להניח שבקובץ assetlinks.json אין את טביעת האצבע שתואמת למפתח המתאים.
כדאי לכלול את טביעת האצבע של אישור החתימה ושל אישור ההעלאה בקובץ assetlinks.json כדי לאפשר ניפוי באגים מקומי של האפליקציה בקלות רבה יותר. בקטע הוספת מפתחות בהמשך מוסבר איך לשמור את שני המפתחות בקובץ assetlinks.json.
יש כמה דרכים שונות לקבל את טביעת האצבע, שמפורטות בקטעים הבאים. כל השיטות אמורות לספק את אותן טביעות אצבע, כך שתוכלו לבחור את השיטה הכי נוחה לכם.
דרך Play Console
בהתאם להצטרפות שלכם לחתימת אפליקציות ב-Play, יכול להיות שתהיה לכם מפתח אחד או שניים. כדי לאחזר את טביעת האצבע המתאימה מסוג SHA256 לכל מפתח:
- עוברים אל Play Console.
- בוחרים את האפליקציה הרצויה
- בתפריט הניווט הימני, בקטע פרסום, עוברים אל הגדרה -> תקינות האפליקציה.
- מעתיקים את ה-SHA256 של המפתח המתאים:
מפתח חתימה: מעתיקים את טביעת האצבע מסוג SHA256 של "אישור מפתח החתימה של האפליקציה". טביעת האצבע הזו תואמת לאפליקציה אם מורידים אותה מחנות Google Play, כי Google Play מפיצה את האפליקציה החתומה באמצעות מפתח החתימה.
Upload key: מעתיקים את טביעת האצבע מסוג SHA256 של 'Upload key certificate'. טביעת האצבע הזו תתאים לאפליקציה אם תתקינו אותה באופן מקומי (לדוגמה, באמצעות ADB דרך USB). קובץ ה-APK הזה (במכונה המקומית) נוצר על ידי Bubblewrap, ולכן הוא חתום גם על המפתח שנוצר בשבילכם (במהלך ההגדרה של
init). חשוב לזכור שזה יכול להיות מפתח החתימה של האפליקציה שמותקנת באופן מקומי, אבל הוא הופך למפתח ההעלאה אחרי שמפרסמים את האפליקציה דרך Play.
דרך keytool
keytool הוא כלי לניהול מפתחות ואישורים. אפשר להשתמש ב-keytool כדי לחלץ את טביעת האצבע של SHA 256 שמשויכת לאפליקציית ה-APK או ה-AAB שנוצרה ב-Bubblewrap. חשוב לזכור שהטביעת האצבע הזו מיועדת למפתח החתימה המקומי. אם מעלים את האפליקציה ל-Play ומצטרפים לתוכנית 'חתימת אפליקציות ב-Play', המפתח הזה הופך למפתח ההעלאה.
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
באמצעות הכלי לקישור נכסים
דרך נוספת לקבל את קובץ Digital Asset Links הנכון לאפליקציה היא להשתמש בכלי לקישור נכסים:
- מתקינים את הכלי לקישור נכסים מחנות Play.
- באותו מכשיר, מורידים את האפליקציה מחנות Google Play או מתקינים אותה באופן מקומי.
- פותחים את האפליקציה Asset Link Tool, ומופיעה רשימה של כל האפליקציות שמותקנות במכשיר לפי שם החבילה. מסננים את הרשימה לפי מזהה האפליקציה שבחרתם קודם לכן במהלך
bubblewrap initולוחצים על הרשומה הזו. - יוצג דף עם החתימה של האפליקציה וקישור שנוצר לנכס דיגיטלי. לוחצים על הלחצנים 'העתקה' או 'שיתוף' בתחתית המסך כדי לייצא את הרשימה בדרך הרצויה (למשל, לשמור אותה ב-Google Keep או לשלוח אותה באימייל לעצמכם).
אותו רעיון רלוונטי גם למפתחות חתימת או העלאה. אם התקנתם את האפליקציה מחנות Google Play, כלי הקישור לנכסים יקבל את טביעת האצבע של מפתח החתימה של האפליקציה. אם התקנתם את האפליקציה ישירות מהמכונה המקומית, טביעת האצבע היא של המפתח שנוצר על ידי Bubblewrap.
מוודאים שאפשר לגשת לקובץ של קישור הנכס
אחרי ההעלאה, צריך לוודא שיש לכם גישה לקובץ הקישור לנכס בדפדפן.
בודקים ש-https://example.com/.well-known/assetlinks.json מפנה לקובץ שהעליתם עכשיו.
אתרים מבוססי Jekyll
אם האתר נוצר על ידי Jekyll (למשל, GitHub Pages), תצטרכו להוסיף שורת הגדרה כדי שספריית .well-known תהיה כלולה בפלט.
מידע נוסף בנושא הזה זמין במרכז העזרה של GitHub.
יוצרים קובץ בשם _config.yml ברמה הבסיסית (root) של האתר (או מוסיפים לקובץ שכבר קיים) ומזינים את הפרטים הבאים:
# Folders with dotfiles are ignored by default.
include: [.well-known]
הוספת מפתחות נוספים
קובץ קישור לנכס דיגיטלי יכול להכיל יותר מאפליקציה אחת, וכל אפליקציה יכולה להכיל יותר ממפתח אחד. לדוגמה, כדי להוסיף מפתח שני, פשוט משתמשים בכלי לקישור נכסים כדי לקבוע את המפתח ולהוסיף אותו כרשומה שנייה. הקוד ב-Chrome שמנתח את ה-JSON הזה הוא קפדני למדי, לכן חשוב לוודא שלא תוסיפו בטעות פסיק נוסף בסוף הרשימה.
[{
"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:..."
]
}
}]
פתרון בעיות
ב-Chrome מתועדת הסיבה לכך שהאימות של Digital Asset Links נכשל, וניתן להציג את היומנים במכשיר Android באמצעות adb logcat.
אם אתם מפתחים ב-Linux או ב-Mac, תוכלו לראות את היומנים הרלוונטיים ממכשיר מחובר באמצעות:
> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links
לדוגמה, אם מופיעה ההודעה Statement failure matching fingerprint., צריך להשתמש בכלי לקישור נכסים כדי לראות את החתימה של האפליקציה ולוודא שהיא תואמת לחתימה בקובץ assetlinks.json.