Android Developer Console API یک میانای عمومی است که برای توزیعکنندگان برنامه و توسعهدهندگان مستقل طراحی شده است تا بتوانند نام بستهها را بهصورت برنامهنویسیشده در Android Developer Console ثبت کنند.
قابلیتهای سرور به سرور شما بهعنوان:
| توزیعکننده برنامه | توسعهدهنده فردی |
|---|---|
| ثبت کردن نام بسته - کلید ازطرف توسعهدهندهای که برنامه را در فروشگاه منتشر میکند. ثبت کردن نام بسته با کلید مدیریتشده توسط فروشگاه. مالکیت کلید منسوب به نام بسته را اثبات کنید. | نام بسته - کلید را در گردشهای کاری استقرار مداوم خود ثبت کنید. مالکیت کلید منسوب به نام بسته را اثبات کنید. |
قبلاز شروع
قبلاز شروع، باید موارد زیر را داشته باشید:
- دسترسی سرپرست به پروژه Google Cloud.
- درک پایهای از:
همچنین باید با اصطلاحات زیر آشنا باشید:
| مدت | تعریف |
|---|---|
| حساب برنامهنویس | نشاندهنده حساب Android Developer Console است که میتواند مالک یک یا چند نام بسته باشد. این پیام حاوی وضعیت درستیسنجی (NOT_VERIFIED یا VERIFIED) است. |
| نام بسته | نام بسته Android خاص (برای مثال، com.example.app) در حساب توسعهدهنده که میتواند با یک یا چند کلید مرتبط باشد. این مقدار حاوی وضعیت ثبتنام (DRAFT، IN_REVIEW، REGISTERED، یا PENDING_TRANSFER) است. |
| کلید | گواهی/کلید عمومی خاصی که برای امضا کردن نام بسته Android استفاده میشود. شامل درهمسازی SHA-256 و وضعیت ثبت فعلی (DRAFT، OWNERSHIP_VERIFIED، IN_REVIEW، REGISTERED، یا PENDING_TRANSFER). |
شروع کنید
برای دسترسی به Android Developer Console API، مراحل زیر را تکمیل کنید:
ایجاد پروژه Google Cloud
- اگر ازقبل حساب Google Cloud ندارید، حسابی ایجاد کنید.
- کنسول Google Cloud را باز کنید.
- پروژه Google Cloud ایجاد کنید.
میانای برنامهسازی کاربردی را در پروژه Google Cloud خود فعال کنید
- کنسول Google Cloud را باز کنید.
- در منو پیمایش (☰)، APIs & Services (میاناهای برنامهسازی کاربردی و سرویسها) > Library (کتابخانه) را انتخاب کنید.
- پروژه Google Cloud را که میخواهید میانای برنامهسازی کاربردی در آن فعال شود از منوِ کرکرهای پروژه انتخاب کنید.
- از نوار جستجوی APIs & Services (میاناهای برنامهسازی کاربردی و سرویسها) برای انتخاب Android Developer Console API (میانای برنامهسازی کاربردی Android Developer Console) استفاده کنید.
- فعال کردن میانای برنامهسازی کاربردی:
- با انتخاب کردن API از نتایج جستجو، به صفحه نمای کلی آن بروید.
- روی دکمه آبی «فعال کردن» کلیک کنید. Google Cloud میانای برنامهسازی کاربردی را برای پروژه انتخابی شما فعال میکند که معمولاً فقط چند لحظه طول میکشد. پساز فعال شدن، میتوانید استفاده از آن را شروع کنید.
اصالتسنجی کردن میانای برنامهسازی کاربردی
برای برقراری تماس با Android Developer Console API، باید درخواستهایتان را بااستفاده از OAuth 2.0 اصالتسنجی کنید.
اصالتسنجی با OAuth 2.0
Android Developer Console API برای مجاز کردن دسترسی به منابع حساب توسعهدهنده و نام بستهها به اصالتسنجی OAuth 2.0 نیاز دارد. چون دادههای حساب توسعهدهنده به «حساب Google» کاربر مرتبط است و نه به پروژه Google Cloud، نمیتوان از «حسابهای سرویس»، Workload Identity Federation، و کلیدهای میانای برنامهسازی کاربردی برای اصالتسنجی درخواستهای میانای برنامهسازی کاربردی استفاده کرد.
حوزه 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) را بههمراه گستره میانای برنامهسازی کاربردی درخواست میکند. Google یک کد مجوز برمیگرداند که برنامه شما آن را با یک کد دسترسی اولیه و یک ژتون بازآوری طولانیمدت معاوضه میکند.اجرای پسزمینه: refresh_token را بهطور ایمن در محیط استقرار یا مدیر محرمانه (برای مثال، GitHub Actions Secrets، «مدیر محرمانه Google») ذخیره کنید. برای فراخوانیهای بعدی میانای برنامهسازی کاربردی، گردش کار خودکارشده شما از ژتون بازآوری ذخیرهشده برای دریافت کد دسترسی کوتاهمدت جدید درصورت درخواست استفاده میکند و هرگونه درخواست ورود به سیستم دستی یا احراز هویت دومرحلهای را دور میزند.
|
اگر ترجیح میدهید از ذخیره کردن ژتونهای بازآوری با عمر طولانی در محیط خود اجتناب کنید، یا اگر برنامهتان در بافت کاربر تعاملی اجرا میشود: درخواست در زمان اجرا: دسترسی آفلاین درخواست نکنید یا ژتون بازآوری ذخیره نکنید. هر بار که ابزار یا برنامه اجرا میشود، با هدایت کردن کاربر به صفحه موافقت Google OAuth در مرورگرش، از او بخواهید اصالتسنجی کند. دسترسی کوتاهمدت: کاربر به سیستم وارد میشود و رضایت میدهد، و برنامه مستقیماً (یا بااستفاده از تبادل کد مجوز) کد دسترسی کوتاهمدت دریافت میکند. از این کد دسترسی برای برقراری تماسهای میانای برنامهسازی کاربردی استفاده میشود و پساز اجرا دور انداخته میشود. اجراهای بعدی مستلزم اصالتسنجی مجدد کاربر است. |
ثبت کردن نام بسته
ثبت کردن نام بسته فرایند مرتبط کردن کلید با نام بسته است. نحوه ثبت کلید به این بستگی دارد که آیا کلید را برای نام بسته جدیدی ثبت میکنید یا نام بسته موجودی در Android.
ثبت کردن نام بسته جدید
برای نام بسته جدیدی که قبلاً هرگز در Android استفاده نشده است، میتوانید گواهینامه کلید عمومی را از جفت کلید امضای برنامه ارائه دهید.
ثبت کردن نام بسته موجود
برای ثبت نام بسته موجود، باید مالکیت کلید امضای خصوصی شناختهشدهای را اثبات کنید. برخلاف ثبت جدید، API فهرستی از اثر انگشتهای گواهینامه عمومی شناختهشده را که واجدشرایط ثبت هستند برمیگرداند. از این کلیدها میتوان برای ثبتنام مستقیم استفاده کرد.
اگر کلیدی که ثبت میکنید بهعنوان «نیازمند توجیه» فهرست شده است، همچنان میتوانید آن را ثبت کنید، اما علاوهبر تکمیل اثبات مالکیت، توسعهدهنده باید توجیهی برای استفاده از نام بسته نیز ارسال کند.
قوانین اصلی واجدشرایط بودن
فهرست کلیدهای واجدشرایط براساس قوانین واجدشرایط بودن نام بسته تعیین میشود که برای بهحداقل رساندن همرسانی نام بسته (معرفیشده بهعنوان بخشی از درستیسنجی توسعهدهنده نرمافزار Android) طراحی شده است.
در سناریوهایی که نام بسته توسط چند توسعهدهنده استفاده میشود یا چند کلید امضا دارد، واجدشرایط بودن بهصورت زیر تعیین میشود:
| سناریو | قانون ثبت مستقیم | قانون برای توسعهدهندگان دیگر |
|---|---|---|
| دارنده کلید اکثریت | کلیدی که بیشاز ۵۰٪ از کل نصبهای شناختهشده را به خود اختصاص میدهد اولویت دارد. | همه توسعهدهندگان دیگر باید توجیهی ارائه دهند. |
| بیشاز ۵۰ نصب | اگر هیچ کلیدی بهتنهایی بیشاز ۵۰٪ نصبها را نداشته باشد، همه کلیدهایی که ۵۰ نصب یا بیشتر داشته باشند واجدشرایط هستند. | توسعهدهندگانی که کلیدهایشان کمتر از ۵۰ نصب دارد باید توجیهی ارائه دهند. |
| کمتر از ۵۰ نصب | اگر هیچ کلیدی به آستانه ۵۰ نصب نرسد، هر کلیدی میتواند براساس اولویت اقدام استفاده شود | وقتی یک توسعهدهنده ثبتنام میکند، دیگران باید توجیهی ارائه دهند. |
درستیسنجی مالکیت کلید
برای تکمیل درستیسنجی نام بسته موجود، API رشته درستیسنجی ارائه میدهد. این رشته درستیسنجی باید در فایل جدیدی با نام adi-registration.properties در پوشه داراییهای برنامه گنجانده شود. سپس باید بااستفاده از کلید خصوصی همخوان با کلید عمومیای که ثبت میکنید، فایل APK را امضا و بارگذاری کنید.
توجیه ثبت کلید
اگر ثبت کلید نیاز به توجیه داشته باشد، توسعهدهندگان باید منطق کسبوکار دقیقی ارسال کنند. Google این توجیه را بازبینی میکند و تأیید ثبت نام بسته ممکن است تا ۲۴ ساعت طول بکشد.
روالهای مطلوب تجربه کاربری
توصیه میشود برنامههایی که از Android Developer Console API استفاده میکنند این الگوها را دنبال کنند تا از ادغام یکپارچه مطمئن شوند.
ایجاد بافتار واضح برای مجوز OAuth
ارائه بافت صریح قبلاز درخواست مجوز OAuth به توسعهدهندگان کمک میکند تا متوجه شوند چرا دسترسی به حساب لازم است. برای راهنمایی مؤثر کاربران، پیشاز راهاندازی صفحه کسب رضایت OAuth، توضیح واضحی از عملکرد موردانتظار ارائه دهید.
بافت مجوز را بااستفاده از قالب زیر ساختاربندی کنید:
- عنوان: «پیوند دادن حساب Android Developer Console»
- خلاصه: «مدیریت ثبت نام بسته برای درستیسنجی توسعهدهنده Android در [application-name]»
- دکمه کنش: دکمه «ادامه با Google» یا «ورود به سیستم با Google»
شناسایی حسابهای توسعهدهنده
- با روش میانای برنامهسازی کاربردی
ListDeveloperAccountsادغام کنید تا همه حسابهای توسعهدهندهای را که دسترسی به آنها مجاز شده است بازیابی و فهرست کنید. - انتخابگر حسابی ارائه دهید تا توسعهدهنده بتواند حساب توسعهدهنده دلخواهش را انتخاب کند.
- حساب
displayNameرا بهطور برجسته نشان دهید و از شماره حساب فیلدnameبهعنوان اطلاعات ثانویه استفاده کنید. - نمایش وضعیتهای درستیسنجی حساب (
verificationState):VERIFIED: هویت توسعهدهنده درستیسنجیشده را با یک نشانه بصری مثبت (مثلاً علامت تیک سبز) تأیید کنید.-
NOT_VERIFIED: نشان میدهد که درستیسنجی ناقص است و ثبت بسته را برای حساب محدود میکند. درصورت تمایل، دکمه دعوت به اقدام اصلیای ارائه دهید که توسعهدهندگان را پساز انتخاب حساب به Android Developer Console هدایت کند.
اگر پاسخ خالی دریافت شد چون هیچ حساب توسعهدهندهای با «حساب Google» مرتبط نیست، توسعهدهندگان را بااستفاده از دکمه دعوت به اقدام اصلی به Android Developer Console راهنمایی کنید.
مدیریت نام بستهها
- با نقطه پایانی میانای برنامهسازی کاربردی
ListAndroidPackagesادغام کنید تا همه نامهای بسته منسوب به حساب توسعهدهنده را بازیابی کنید. رابط متمرکزی مثل فهرست یا جدول به توسعهدهندگان ارائه دهید تا بتوانند وضعیت بستههایشان را بهطور مؤثر پایش کنند. packageNameرا در کنار وضعیت ثبت فعلی آن (DRAFT،IN_REVIEW،REGISTERED، یاPENDING_TRANSFER) نمایش دهید و نشانگرهای دیداری متمایزی برای هر وضعیت اعمال کنید. اگر «نام آشنایی» درطول ایجاد ارائه و ذخیره شده باشد، میتوانید آن را بهصورت اختیاری در نمایشگر اضافه کنید.
مدیریت کلیدها
- نقطه پایانی میانای برنامهسازی کاربردی
ListAndroidPackageKeysرا فراخوانی کنید تا همه کلیدهای مرتبط با نام بسته را واکشی کنید و نمای کلی ساختاریافتهای (مانند جدول یا فهرست) به توسعهدهندگان ارائه دهید تا وضعیت ثبت خود را نظارت کنند. certificateFingerprintSha256را برای هر کلید درکنار وضعیت ثبت آن (DRAFT،OWNERSHIP_VERIFIED،IN_REVIEW،REGISTERED_ACTIVE، یاPENDING_TRANSFER) ارائه دهید و از نشانگرهای بصری متمایز برای تشخیص وضعیتها استفاده کنید.
- به توسعهدهندگان امکان میدهد کلیدهای اضافی را تحت نام بسته موجود
با ادغام با روش
CreateAndroidPackageKeyAPI ثبت کنند.
ثبت کردن نام بسته
- از چیدمان فرممحور استفاده کنید که در آن توسعهدهندگان نام بسته خود را در فیلد نوشتاری وارد میکنند، مشروط بر اینکه این اطلاعات قبلاً توسط برنامه شما جمعآوری نشده باشد (مثلاً ازطریق پیامواره قبلی).
- برای ثبتنام نام بسته تحت حساب توسعهدهنده، روش میانای برنامهسازی کاربردی
CreateAndroidPackageرا فراخوانی کنید و برای تعیین قوانین واجدشرایط بودن کلید مربوطه، روش میانای برنامهسازی کاربردیGetAndroidPackageRegistrationPolicyرا فراخوانی کنید. - براساس
keySelectionStrategyتعیینشده برای نام بسته، از توسعهدهنده بخواهید یکی از کارهای زیر را انجام دهد:- اگر
keySelectionStrategyرویSELECT_KEY_FROM_LISTتنظیم شده است: از توسعهدهنده بخواهید کلیدی را برای ثبت از فهرستknownKeysارائهشده (حاوی اثر انگشتهای گواهینامه SHA-256) انتخاب کند، مثلاً بااستفاده از دکمههای رادیویی. این جریان به درستیسنجی مالکیت کلید نیاز دارد (به درستیسنجی مالکیت کلید در زیر مراجعه کنید). - اگر
keySelectionStrategyرویUSE_ANY_KEYتنظیم شده است: از توسعهدهنده بخواهید کلید را مستقیماً ارائه دهد. درستیسنجی مالکیت کلید در این مورد لازم نیست.
- اگر
- برای مرتبط کردن کلید انتخابشده با نام بسته جدید،
روش
CreateAndroidPackageKeyAPI را فراخوانی کنید.
یا اینکه برنامه شما میتواند بهطور خودکار نام بسته یا کلید را مستقیماً از برنامه بارگذاریشده شناسایی و استخراج کند.
درستیسنجی کردن مالکیت کلید
وقتی keySelectionStrategy روی SELECT_KEY_FROM_LIST تنظیم شده باشد، توسعهدهندگان باید
مالکیت کلید امضای خصوصیشان را اثبات کنند. برای اثبات مالکیت باید
فایل APK امضاشدهای ارسال کنید که حاوی verificationToken تولیدشده توسط API باشد.
برای پشتیبانی از درستیسنجی مالکیت کلید، روش
VerifyAndroidPackageKeyOwnership API را ادغام کنید و مؤلفههای میانای کاربر زیر را
بسازید:
- مؤلفه نمایش کد:
verificationTokenرا بهطور برجسته در داخل بلوک تکهکد نمایش دهید، ازجمله دکمه کاربردی «کپی در بریدهدان». - دستورالعملهای راهاندازی برای توسعهدهنده: دستورالعملهای دقیقی ارائه دهید که
توسعهدهنده را راهنمایی کند تا فایل
adi-registration.propertiesحاویverificationTokenرا در پوشه داراییهای برنامه قرار دهد. - منطقه رها کردن ارسال APK: منطقه رها کردن اختصاصی برای بارگذاری فایل ارائه دهید تا APK امضاشده را دریافت کنید.
توجیه کردن ثبت کلید
وقتی فیلد justificationRequired کلید شناختهشدهای روی REQUIRED تنظیم شده باشد،
ثبت آن کلید در کنار نام بسته مستلزم آن است که توسعهدهندگان
توجیه کسبوکار کاملی ارسال کنند.
این توجیه را با فراخوانی روش میانای برنامهسازی کاربردی JustifyAndroidPackageKeyRegistration
ارسال کنید. مطمئن شوید میانای کاربر برنامهتان دارای بخش اختصاصی برای وارد کردن نوشتار باشد تا بتوانید توجیه توسعهدهنده را دریافت کنید و به او اطلاع دهید که ارائه دلیل منطقی قبلاز ارسال درخواست ثبت کلید الزامی است. Google توجیه ارسالشده را بررسی میکند، فرایندی که ممکن است تا ۲۴ ساعت طول بکشد تا تأیید شود و ثبت نام بسته تکمیل شود.
خودکارسازی درستیسنجی کلید برای کلیدهای مدیریتشده
اگر برنامه شما کلید امضای توسعهدهنده را مدیریت میکند، توسعهدهنده نمیتواند
بهصورت دستی APK را برای درستیسنجی مالکیت امضا کند. درعوض، باید فراخوانی میانای برنامهسازی کاربردی
VerifyAndroidPackageKeyOwnership را بهطور خودکار ازطرف آنها اجرا کنید.
با مدیریت خودکار فرایند گنجاندن کد و بارگذاری APK، برنامهتان این مراحل دستی را حذف میکند. حتماً به توسعهدهندگان اطلاع دهید که درستیسنجی مالکیت کلید بهطور یکپارچه توسط برنامه شما بااستفاده از کلید ذخیرهشده در سیستم شما مدیریت میشود.
رعایت رهنمودهای نمانام
برای حفظ اعتماد کاربر و اطمینان از شفافیت، همه برنامههایی که با Android Developer Console API ادغام میشوند باید از رهنمودهای نمانام زیر پیروی کنند.
اصطلاحات و بزرگنویسی
هنگام ارجاع به محصول در مطالب یا اسناد سَمت کاربر، همیشه از نام کامل Android Developer Console استفاده کنید. از مخفف «ADC» استفاده نکنید.
این برنامه باید با نام «درستیسنجی توسعهدهنده نرمافزار Android» ارجاع داده شود. در همه بافتها، دقیقاً از همین حروف بزرگ و املا استفاده کنید.
برای جلوگیری از ابهام با APK یا AAB، بهطور خاص از اصطلاح «نام بسته» استفاده کنید نه فقط «بسته».
هنگام توصیف فرایند افزودن نام بسته، از عبارت «ثبت نام بسته» بهجای «ادعای مالکیت نام بسته» استفاده کنید.
استفاده از دعوت به اقدام «ورود به سیستم»
اصالتسنجی OAuth 2.0 با Android Developer Console به «سرویسهای مدیریت هویتسنجی Google» متکی است. برای رعایت رهنمودهای نمانامسازی سرویسهای مدیریت هویتسنجی Google، باید از دعوت به اقدام «ادامه دادن با Google» یا «ورود به سیستم با Google» در دکمه صدور مجوز استفاده کنید. این نوشتار اجباری است و نمیتوان آن را اصلاح کرد، زیرا این نوشتار تضمین میکند که کاربران متوجه میشوند که از اطلاعات کاربری Google خود برای مجاز کردن برنامه شما جهت دسترسی به «حساب Google» خود استفاده میکنند.
حفظ هویت و یکپارچگی نمانام
هنگام ادغام کردن نشانواره Android Developer Console در میانای برنامه، باید این مشخصات را دنبال کنید تا هویت بصری و تمامیت نمانام حفظ شود:
- جایگذاری و سلسلهمراتب نشانواره: فقط از نشانواره رسمی و تأییدشده Android Developer Console استفاده کنید. نشانواره باید همیشه نسبتبه عناصر نمانامسازی اصلی برنامه شما در جایگاه دوم قرار داشته باشد تا از معرفی نادرست برنامه بهعنوان محصول رسمی Google جلوگیری شود.
- سبک دیداری و اعوجاج: دارایی باید همیشه با نسبت ابعادی کاملاً محدودشده ارائه شود. هرگز نباید اجزای نشانواره را تحریف، کشیده، کج، برش، وارونه، یا اصلاح کنید. پالت رنگ رسمی را تغییر ندهید، رنگهای پیشزمینه یا پسزمینه را جابهجا نکنید، یا سایه، جلوههای درخشش، یا گرادیانهای تزئینی اعمال نکنید.
- محدودیتهای استفاده: هیچیک از عناصر نمانامسازی تحت مالکیت Google را در داراییهای برنامه خودتان ادغام نکنید. دارایی نشانواره Android Developer Console فقط میتواند در بافت چیدمان برنامه استفاده شود تا بهطور صریح نشاندهنده ادغام فعال باشد.
منابع بیشتر
- مرجع میانای برنامهسازی کاربردی Android Developer Console
- بررسی وضعیت ثبت برنامه با Android Developer ID Status API
- ثبتنام در Android Developer Console
- ثبتنام در «کنسول Google Play»
- امضا کردن برنامه