רישום שמות חבילות באמצעות Android Developer Console API

‫Android Developer Console API הוא ממשק ציבורי שמאפשר למפיצי אפליקציות ולמפתחים פרטיים לרשום שמות של חבילות ב-Android Developer Console באופן פרוגרמטי.

היכולות שלכם בשרת-אל-שרת בתור:

מפיץ האפליקציה	מפתח פרטי
לרשום מפתח של שם חבילה בשם המפתח שמפרסם אפליקציה בחנות. לרשום שם חבילה עם מפתח שמנוהל על ידי החנות. להוכיח בעלות על מפתח שמשויך לשם חבילה.	רישום של שם חבילה – מפתח בתהליכי העבודה של הפריסה הרציפה. להוכיח בעלות על מפתח שמשויך לשם חבילה.

לפני שמתחילים

לפני שמתחילים, צריך:

1. הרשאת אדמין לפרויקט בענן ב-Google Cloud.
2. הבנה בסיסית של:
   • ממשקי API בארכיטקטורת REST
   • מבנה ה-APK
   • חתימת אפליקציות ל-Android
   • יצירת תמציות SHA-256

כדאי גם להכיר את המונחים הבאים:

מונח	הגדרה
חשבון מפתח	מייצג חשבון ב-Android Developer Console שיכול להיות הבעלים של שם חבילה אחד או יותר. הוא מכיל סטטוס אימות (NOT_VERIFIED או VERIFIED).
שם חבילה	שם חבילה ספציפי ל-Android (לדוגמה, com.example.app) בחשבון פיתוח, שאפשר לשייך למפתח אחד או יותר. הוא מכיל סטטוס רישום (DRAFT,‏ IN_REVIEW,‏ REGISTERED או PENDING_TRANSFER).
מפתח	האישור או המפתח הציבורי הספציפי שמשמש לחתימה על שם חבילה ב-Android. כולל את גיבוב (hash) ה-SHA-256 ואת מצב הרישום הנוכחי (DRAFT,‏ OWNERSHIP_VERIFIED,‏ IN_REVIEW,‏ REGISTERED או PENDING_TRANSFER).

שנתחיל?

כדי לגשת ל-Android Developer Console API, צריך לבצע את הפעולות הבאות:

יצירת פרויקט של Google Cloud

1. אם עדיין אין לכם חשבון Google Cloud, צרו חשבון.
2. פותחים את מסוף Google Cloud.
3. יוצרים פרויקט ב-Google Cloud.

הפעלת ה-API בפרויקט בענן ב-Google Cloud

1. פותחים את מסוף Google Cloud.
2. בתפריט הניווט (☰), בוחרים באפשרות APIs & Services > Library.
3. בתפריט הנפתח של הפרויקטים, בוחרים את הפרויקט בענן ב-Google Cloud שבו רוצים להפעיל את ה-API.
4. בסרגל החיפוש של APIs & Services, בוחרים באפשרות Android Developer Console API.
5. מפעילים את ה-API:
   1. עוברים לדף הסקירה הכללית של ה-API על ידי בחירה שלו מתוצאות החיפוש.
   2. לוחצים על הכפתור הכחול "הפעלה". ‫Google Cloud מפעילה את ה-API בפרויקט שבחרתם. בדרך כלל זה לוקח רק רגע. אחרי שמפעילים את התכונה, אפשר להתחיל להשתמש בה.

אימות ה-API

כדי לשלוח קריאות ל-Android Developer Console API, צריך לאמת את הבקשות באמצעות OAuth 2.0.

אימות באמצעות OAuth 2.0

כדי לקבל גישה למשאבים ולשמות החבילות בחשבון הפיתוח, צריך לאמת את Android Developer Console API באמצעות OAuth 2.0. הנתונים בחשבון הפיתוח מקושרים לחשבון Google של המשתמש ולא לפרויקט ב-Google Cloud, ולכן אי אפשר להשתמש בחשבונות שירות, באיחוד זהויות של עומסי עבודה (WIF) ובמפתחות API כדי לאמת בקשות API.

היקף ההרשאות של OAuth 2.0

ההיקף הבא נדרש לכל הפעולות:

היקף הרשאות OAuth 2.0	תיאור
https://www.googleapis.com/auth/androiddeveloperconsole	קריאה וניהול של שמות החבילות והנתונים שלהן בחשבונות שלך ב-Android Developer Console

הטמעת תהליך OAuth 2.0 לשרת אינטרנט

כדי לשלב את Android Developer Console API, האפליקציות צריכות להשתמש בתהליך שרת האינטרנט של OAuth 2.0. בהתאם לסוג האפליקציה ולצורכי האוטומציה, אתם יכולים לבחור בין שתי אסטרטגיות עיקריות לניהול פרטי כניסה:

אפשרות א' (מומלצת): גישה אוטומטית או אופליין (שילוב של CI/CD ושרת)

אפשרות ב': גישה זמנית או אינטראקטיבית

האסטרטגיה הזו מאפשרת לתהליכים אוטומטיים (כמו צינורות עיבוד נתונים של CI/CD) לפעול ברקע בלי התערבות אנושית: הגדרה חד-פעמית של הסכמת המשתמש: במהלך ההגדרה הראשונית, מפתח או בעל החשבון משלימים תהליך הסכמה חד-פעמי בדפדפן שלהם. האפליקציה מבקשת גישה אופליין (access_type=offline) יחד עם היקף ההרשאות של ה-API. ‫Google מחזירה קוד הרשאה, והאפליקציה מחליפה אותו באסימון גישה ראשוני ובאסימון רענון לטווח ארוך. הפעלה ברקע: מאחסנים באופן מאובטח את refresh_token בסביבת הפריסה או במנהל הסודות (לדוגמה, GitHub Actions Secrets, ‏ Google Secret Manager). בקריאות הבאות ל-API, תהליך העבודה האוטומטי משתמש בטוקן הרענון ששמור כדי לקבל טוקן גישה חדש לטווח קצר לפי דרישה, בלי להציג בקשות להתחברות ידנית או ל-2FA.

אם אתם מעדיפים להימנע מאחסון של אסימוני רענון לטווח ארוך בסביבה שלכם, או אם האפליקציה פועלת בהקשר של משתמש אינטראקטיבי: הצגת בקשה בזמן ההפעלה: אל תבקשו גישה אופליין ואל תאחסנו אסימון רענון. בכל פעם שהכלי או האפליקציה מופעלים, המשתמשים מתבקשים לבצע אימות על ידי הפניה לדף ההסכמה של Google OAuth בדפדפן שלהם. גישה לטווח קצר: המשתמש מתחבר ומביע הסכמה, והאפליקציה מקבלת אסימון גישה לטווח קצר באופן ישיר (או באמצעות המרת קוד הרשאה). טוקן הגישה הזה משמש לביצוע קריאות ל-API ונמחק אחרי הביצוע. כדי להפעיל את הסקריפט בעתיד, המשתמש יצטרך לבצע אימות מחדש.

רישום של שם חבילה

רישום של שם חבילה הוא תהליך שבו משייכים מפתח לשם חבילה. אופן הרישום של המפתח תלוי בשאלה אם אתם רושמים מפתח לשם חבילה חדש או קיים ב-Android.

רישום של שם חבילה חדש

אם שם החבילה חדש ולא הופיע אף פעם ב-Android, אתם יכולים לספק את האישור של המפתח הציבורי מזוג מפתחות החתימה של האפליקציה.

רישום של שם חבילה קיים

כדי לרשום שם חבילה קיים, צריך להוכיח בעלות על מפתח חתימה פרטי מוכר. בניגוד לרישום חדש, ה-API מחזיר רשימה של טביעות אצבע לאישורים ציבוריים מוכרים שאפשר לרשום. אפשר להשתמש במפתחות האלה לרישום ישיר.

אם המפתח שאתם רושמים מופיע ברשימה כ "נדרש הסבר", אתם עדיין יכולים לרשום אותו, אבל בנוסף להוכחת הבעלות, המפתח נדרש גם לשלוח הסבר לשימוש בשם החבילה.

כללי הזכאות העיקריים

רשימת המפתחות שעומדים בדרישות נקבעת לפי כללי הזכאות של שם החבילה, שנועדו לצמצם את השיתוף של שם החבילה (הוצגו כחלק מהאימות למפתחי Android).

בתרחישים שבהם כמה מפתחים משתמשים באותו שם חבילה או שיש כמה מפתחות חתימה, הזכאות נקבעת באופן הבא:

תרחיש	כלל לרישום ישיר	כלל למפתחים אחרים
בעל רוב המפתחות	המפתח שאחראי ליותר מ-50% מסך ההתקנות הידועות מקבל עדיפות.	כל שאר המפתחים צריכים לספק הצדקה.
יותר מ-50 התקנות	אם אין מפתח אחד עם יותר מ-50% מההתקנות, כל המפתחות עם 50 התקנות או יותר עומדים בדרישות.	מפתחים עם מפתחות שיש להם פחות מ-50 התקנות צריכים לספק הצדקה.
פחות מ-50 התקנות	אם אין מפתחות שעומדים בסף של 50 התקנות, אפשר להשתמש בכל מפתח על בסיס "כל הקודם זוכה"	אחרי שמפתח אחד נרשם, מפתחים אחרים צריכים לספק הצדקה.

אימות הבעלות על המפתח

כדי להשלים את האימות של שם חבילה קיים, ה-API מספק מחרוזת אימות. צריך לכלול את מחרוזת האימות הזו בקובץ חדש בשם adi-registration.properties בתיקיית הנכסים של האפליקציה. לאחר מכן, צריך לחתום על ה-APK ולהעלות אותו באמצעות המפתח הפרטי שתואם למפתח הציבורי שאתם רושמים.

הצדקת רישום המפתח

אם נדרש נימוק לרישום מפתח, המפתחים צריכים לשלוח הסבר עסקי מפורט. ‫Google בודקת את ההצדקה, ותהליך האישור של רישום שם החבילה יכול להימשך עד 24 שעות.

שיטות מומלצות לחוויית המשתמש

כדי להבטיח שילוב חלק, מומלץ שאפליקציות שמשתמשות ב-Android Developer Console API יפעלו לפי הדפוסים האלה.

הגדרת הקשר ברור להרשאת OAuth

הצגת הקשר ברור לפני בקשת הרשאת OAuth עוזרת למפתחים להבין למה נדרשת גישה לחשבון. כדי להדריך את המשתמשים בצורה יעילה, צריך להציג הסבר ברור על הפונקציונליות הצפויה לפני שמפעילים את מסך ההסכמה של OAuth.

מבנה הקשר ההרשאה צריך להיות בפורמט הבא:

• כותרת: "קישור החשבון ב-Android Developer Console"
• סיכום: "ניהול הרישום של שמות החבילות לצורך אימות מפתחי Android ב-[שם האפליקציה]"
• כפתור פעולה: הכפתור "המשך באמצעות חשבון Google" או "כניסה באמצעות חשבון Google"

תרשים 1. מקשרים את החשבון ב-Android Developer Console.

זיהוי חשבונות הפיתוח

1. משלבים את השיטה ListDeveloperAccounts של ה-API כדי לאחזר את כל חשבונות הפיתוח שקיבלו הרשאת גישה ולהציג אותם ברשימה.
2. כלי לבחירת חשבון שמאפשר למפתח לבחור את חשבון הפיתוח המועדף עליו.
3. להציג באופן בולט את החשבון displayName, ולהשתמש במספר החשבון מהשדה name כמידע משני.
4. הצגת מצבי האימות של החשבון (verificationState):
   • ‫VERIFIED: אישור זהות המפתח המאומתת באמצעות סימן חזותי חיובי (למשל, סימן וי ירוק).
   • ‫NOT_VERIFIED: מציינים שהאימות לא הושלם ומגבילים את רישום החבילות בחשבון. אפשר גם להוסיף כפתור קריאה לפעולה (CTA) ראשי שמעביר את המפתחים ל-Android Developer Console אחרי שהם בוחרים את החשבון.

איור 2. בורר חשבונות שמוצגים בו חשבונות פיתוח וסטטוס האימות.

אם מתקבלת תשובה ריקה כי אין חשבונות פיתוח שמשויכים לחשבון Google, צריך להפנות את המפתחים ל-Android Developer Console באמצעות כפתור קריאה לפעולה (CTA) ראשי.

ניהול שמות של חבילות

1. משלבים את נקודת הקצה ל-API‏ ListAndroidPackages כדי לאחזר את כל שמות החבילות שמשויכים לחשבון הפיתוח. לספק למפתחים ממשק מרכזי, כמו רשימה או טבלה, כדי לעקוב ביעילות אחרי מצבי החבילות.
2. מציגים את packageName לצד סטטוס הרישום הנוכחי שלו (DRAFT,‏ IN_REVIEW,‏ REGISTERED או PENDING_TRANSFER), ומשתמשים באינדיקטורים חזותיים שונים לכל סטטוס. אם סיפקתם "שם ידידותי" ושמרתם אותו במהלך היצירה, אתם יכולים לכלול אותו בתצוגה.

תרשים 3. ממשק לניהול שמות של חבילות וסטטוסים של רישום.

ניהול מפתחות

1. קוראים לנקודת הקצה ל-API‏ ListAndroidPackageKeys כדי לאחזר את כל המפתחות שקשורים לשם החבילה. כך המפתחים מקבלים סקירה כללית מובנית (כמו טבלה או רשימה) שמאפשרת להם לעקוב אחרי סטטוס הרישום שלהם.
2. מציגים את certificateFingerprintSha256 לכל מפתח לצד סטטוס הרישום שלו (DRAFT,‏ OWNERSHIP_VERIFIED,‏ IN_REVIEW,‏ REGISTERED_ACTIVE או PENDING_TRANSFER), ומשתמשים באינדיקטורים חזותיים שונים כדי להבדיל בין הסטטוסים.

איור 4. סקירה כללית של המפתחות וסטטוס הרישום שלהם.

1. לאפשר למפתחים לרשום מפתחות נוספים בשם חבילה קיים באמצעות שילוב עם ה-method של ה-API‏ CreateAndroidPackageKey.

רישום של שם חבילה

1. השתמשו בפריסה שמבוססת על טופס שבו המפתחים מזינים את שם החבילה שלהם בשדה טקסט, בתנאי שהמידע הזה עדיין לא נאסף על ידי האפליקציה (למשל, באמצעות בקשה קודמת).
2. מפעילים את ה-method‏ CreateAndroidPackage של ה-API כדי לרשום שם חבילה בחשבון הפיתוח, ומפעילים את ה-method‏ GetAndroidPackageRegistrationPolicy של ה-API כדי לקבוע את כללי הזכאות הרלוונטיים למפתח.
3. בהתאם ל-keySelectionStrategy שצוין לשם החבילה, מבקשים מהמפתח לבצע אחת מהפעולות הבאות:
   • אם הערך של keySelectionStrategy הוא SELECT_KEY_FROM_LIST: המפתח צריך לבחור מפתח לרישום מהרשימה knownKeys שסופקה (שמכילה טביעות אצבע לאישור SHA-256), למשל באמצעות כפתורי בחירה. התהליך הזה דורש אימות בעלות על המפתח (ראו אימות בעלות על מפתח בהמשך).
   • אם keySelectionStrategy מוגדר ל-USE_ANY_KEY: צריך לבקש מהמפתח לספק מפתח ישירות. במקרה כזה אין צורך לאמת את הבעלות על המפתח.
4. מפעילים את ה-method‏ CreateAndroidPackageKey ב-API כדי לשייך את המפתח שנבחר לשם החבילה החדש.

איור 5. תהליך הרישום של שם חבילה ובחירת מפתח.

לחלופין, האפליקציה יכולה לזהות ולחלץ באופן אוטומטי את שם החבילה או המפתח ישירות מאפליקציה שהועלתה.

אימות בעלות על מפתח

כשהמדיניות keySelectionStrategy מוגדרת כ-SELECT_KEY_FROM_LIST, המפתחים צריכים להוכיח בעלות על מפתח החתימה הפרטי שלהם. כדי להוכיח בעלות, צריך לשלוח קובץ APK חתום שכולל את ה-verificationToken שנוצר על ידי ה-API.

כדי לתמוך באימות הבעלות על המפתח, צריך לשלב את ה-method‏ VerifyAndroidPackageKeyOwnership ב-API וליצור את הרכיבים הבאים בממשק המשתמש:

• רכיב להצגת הטוקן: הצגת ה-verificationToken באופן בולט בתוך בלוק של קטע קוד, כולל כפתור נוח להעתקה ללוח.
• הוראות הגדרה למפתחים: הוראות מפורטות שמנחות את המפתח להוסיף קובץ adi-registration.properties שמכיל את verificationToken לתיקיית הנכסים של האפליקציה.
• אזור ייעודי להעלאת קובצי APK: צריך לספק אזור ייעודי להעלאת קבצים כדי לקבל את קובץ ה-APK החתום.

איור 6. רכיבי ממשק משתמש לאימות הבעלות על המפתח באמצעות העלאת APK חתום.

הצדקת הרישום של מפתח

כשמפתח מוכר מוגדר עם השדה justificationRequired כ-REQUIRED, כדי לרשום את המפתח הזה לצד שם החבילה, המפתחים צריכים לשלוח הסבר מפורט על הצורך העסקי.

כדי לשלוח את ההצדקה, צריך להפעיל את ה-method‏ JustifyAndroidPackageKeyRegistration ב-API. חשוב לוודא שבממשק המשתמש של האפליקציה יש אזור ייעודי להזנת טקסט, שבו המפתח יכול להזין את ההצדקה. צריך גם להודיע למפתח שהוא חייב לספק הסבר לפני שהוא שולח את הבקשה לרישום המפתח. ‫Google בודקת את ההצדקה שנשלחה. תהליך האישור יכול להימשך עד 24 שעות, ורק אחריו רישום שם החבילה יושלם.

אימות אוטומטי של מפתחות מנוהלים

אם האפליקציה שלכם מנהלת את מפתח החתימה של המפתח, המפתח לא יכול לחתום באופן ידני על APK לצורך אימות בעלות. במקום זאת, אתם צריכים להפעיל את הקריאה ל-API של VerifyAndroidPackageKeyOwnership באופן אוטומטי בשמם.

האפליקציה מטפלת בתהליך הכללת הטוקן והעלאת ה-APK באופן אוטומטי, וכך מסירה את השלבים הידניים האלה. חשוב להודיע למפתחים שהאפליקציה שלכם מנהלת את אימות הבעלות על המפתח בצורה חלקה באמצעות המפתח שמאוחסן במערכת שלכם.

הקפדה על הנחיות המיתוג

כדי לשמור על אמון המשתמשים ולהבטיח שקיפות, כל האפליקציות שמשתלבות עם Android Developer Console API נדרשות לפעול לפי ההנחיות הבאות בנושא מיתוג.

טרמינולוגיה ושימוש באותיות רישיות

כשמתייחסים למוצר בחומרים או במסמכים שגלויים למשתמשים, צריך תמיד להשתמש בשם המלא Android Developer Console. אל תשתמשו בקיצור "ADC".

התוכנית חייבת להיקרא "אימות למפתחי Android". הקפידו על האיות והשימוש באותיות רישיות בכל ההקשרים.

כדי למנוע בלבול עם קובצי APK או AAB, השתמשו במונח "שם החבילה" במקום "חבילה".

כשמתארים את התהליך של הוספת שם חבילה, צריך להשתמש בביטוי "רישום שם חבילה" במקום "הצהרת בעלות על שם חבילה".

שימוש בקריאה לפעולה "כניסה"

אימות OAuth 2.0 עם Android Developer Console מסתמך על Google Identity Services. כדי לעמוד בספר המותג של Google Identity Services, צריך להשתמש בקריאה לפעולה "המשך באמצעות חשבון Google" או "כניסה באמצעות חשבון Google" בכפתור ההרשאה. הטקסט הזה הוא חובה ואי אפשר לשנות אותו, כי הוא מבטיח שהמשתמשים יבינו שהם משתמשים בפרטי הכניסה שלהם ל-Google כדי לאשר לאפליקציה שלכם לגשת לחשבון Google שלהם.

שמירה על זהות המותג ועל התקינות שלו

כשמשלבים את הלוגו של Android Developer Console בממשק של האפליקציה, צריך לפעול לפי המפרטים הבאים כדי לשמור על הזהות החזותית ועל שלמות המותג:

• מיקום הלוגו וההיררכיה: השתמשו רק בלוגו הרשמי והמאושר של Android Developer Console. הלוגו תמיד צריך להיות משני לגורמי הייחודיות המיתוגיים הראשיים של האפליקציה, כדי למנוע מצג שווא שלפיו האפליקציה היא מוצר רשמי של Google.

איור 7. הלוגו הרשמי של Android Developer Console. לוחצים על התמונה כדי לשמור את הקובץ.

• סגנון חזותי ועיוותים: הנכס חייב תמיד להיות מוצג עם יחס גובה-רוחב מוגבל לחלוטין. אסור לעוות, למתוח, להטות, לחתוך, להפוך או לשנות את הרכיבים של הלוגו. אל תשנו את פלטת הצבעים הרשמית, אל תחליפו בין צבעי החזית והרקע ואל תוסיפו צלליות, אפקטים של זוהר או מעברי צבעים דקורטיביים.
• הגבלות שימוש: אל תשלבו אלמנטים של מיתוג בבעלות Google בנכסי האפליקציה שלכם. מותר להשתמש בנכס הלוגו של Android Developer Console רק בהקשר של פריסת האפליקציה, כדי לציין באופן מפורש שילוב פעיל.

מקורות מידע נוספים

• מאמרי העזרה של ה-API של Android Developer Console
• איך בודקים את סטטוס הרישום של האפליקציה באמצעות Android Developer ID Status API
• הרשמה ל-Android Developer Console
• הרשמה ב-Google Play Console
• חתימה על האפליקציה