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

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

היכולות שלכם להעברת נתונים משרת לשרת בתור:

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

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

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

1. גישת אדמין לפרויקט בענן ב-Google Cloud.
2. הבנה בסיסית של:
   • ממשקי API של RESTful
   • מבנה ה-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).

שנתחיל?

כדי לגשת ל-API של Android Developer Console:

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

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

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

1. פותחים את מסוף Google Cloud.
2. בתפריט הניווט (☰), בוחרים באפשרות APIs & Services > Library (ממשקי API ושירותים > ספרייה).
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

כדי לאשר גישה למשאבים של חשבון מפתח ולשמות של חבילות, צריך לבצע אימות OAuth 2.0 ב-Android Developer Console API. הנתונים בחשבון המפתחים משויכים לחשבון Google של המשתמש ולא לפרויקט ב-Google Cloud, ולכן אי אפשר להשתמש בחשבונות שירות, באיחוד זהויות של עומסי עבודה ובמפתחות 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, תהליך העבודה האוטומטי משתמש באסימון הרענון המאוחסן כדי לקבל אסימון גישה חדש לטווח קצר על פי דרישה, בלי להציג הנחיות להתחברות ידנית או לאימות דו-שלבי.

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

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

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

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

ניהול מפתחות

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

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

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

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

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

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

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

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

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

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

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

כדי לשלוח את ההצדקה הזו, צריך להפעיל את JustifyAndroidPackageKeyRegistration API method. חשוב לוודא שבממשק המשתמש של האפליקציה יש אזור ייעודי להזנת טקסט, שבו המפתחים יכולים להזין את ההצדקה. בנוסף, צריך להודיע למפתחים שנדרש נימוק לפני שליחת בקשת רישום המפתח. ‫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.

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

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

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