نام بسته‌ها را با API کنسول توسعه‌دهندگان اندروید ثبت کنید

رابط برنامه‌نویسی کنسول توسعه‌دهندگان اندروید (Android Developer Console API) یک رابط عمومی است که به توزیع‌کنندگان اپلیکیشن و توسعه‌دهندگان انفرادی اجازه می‌دهد تا نام بسته‌ها را به صورت برنامه‌نویسی در کنسول توسعه‌دهندگان اندروید ثبت کنند.

قابلیت‌های سرور به سرور شما به عنوان:

قبل از اینکه شروع کنی

قبل از شروع، باید موارد زیر را داشته باشید:

1. دسترسی مدیریتی به یک پروژه Google Cloud.
2. درک اولیه از:
   • API های RESTful
   • ساختار APK
   • امضای برنامه اندروید
   • تولید دایجست‌های SHA-256

همچنین باید با اصطلاحات زیر آشنا باشید:

شروع کنید

برای دسترسی به API کنسول توسعه‌دهندگان اندروید، مراحل زیر را انجام دهید:

ایجاد یک پروژه گوگل کلود

1. اگر از قبل حساب کاربری گوگل کلود ندارید، یک حساب کاربری ایجاد کنید .
2. کنسول گوگل کلود را باز کنید.
3. یک پروژه گوگل کلود ایجاد کنید .

فعال کردن API در پروژه Google Cloud شما

1. کنسول گوگل کلود را باز کنید.
2. در منوی پیمایش (☰)، APIها و خدمات > کتابخانه را انتخاب کنید.
3. پروژه گوگل کلود مورد نظر برای فعال کردن API را از منوی کشویی پروژه انتخاب کنید.
4. از نوار جستجوی APIها و خدمات (APIs & Services) برای انتخاب Android Developer Console API استفاده کنید.
5. فعال کردن API:
   1. با انتخاب API از نتایج جستجو، به صفحه نمای کلی آن بروید.
   2. روی دکمه آبی رنگ فعال‌سازی کلیک کنید. گوگل کلود API مربوط به پروژه انتخابی شما را فعال می‌کند که معمولاً فقط چند لحظه طول می‌کشد. پس از فعال‌سازی، می‌توانید از آن استفاده کنید.

احراز هویت API

برای برقراری تماس با API کنسول توسعه‌دهندگان اندروید، باید درخواست‌های خود را با استفاده از OAuth 2.0 تأیید اعتبار کنید.

احراز هویت با OAuth 2.0

رابط برنامه‌نویسی کاربردی (API) کنسول توسعه‌دهندگان اندروید (Android Developer Console API) برای تأیید دسترسی به منابع حساب توسعه‌دهندگان و نام بسته‌ها، به احراز هویت OAuth 2.0 نیاز دارد. از آنجا که داده‌های حساب توسعه‌دهندگان به جای یک پروژه Google Cloud به حساب Google کاربر گره خورده است، نمی‌توان از حساب‌های سرویس، فدراسیون هویت بار کاری و کلیدهای API برای تأیید اعتبار درخواست‌های API استفاده کرد.

دامنه OAuth 2.0

برای کلیه عملیات، رعایت موارد زیر الزامی است:

پیاده‌سازی جریان وب سرور OAuth 2.0

برای ادغام با API کنسول توسعه‌دهندگان اندروید، برنامه‌ها باید از جریان وب سرور OAuth 2.0 استفاده کنند. بسته به نوع برنامه و نیازهای اتوماسیون شما، می‌توانید از بین دو استراتژی اصلی مدیریت اعتبارنامه انتخاب کنید:

ثبت نام بسته

ثبت نام بسته (Package name registration) فرآیندی است که در آن یک کلید (key) به نام یک بسته (package name) مرتبط می‌شود. نحوه ثبت یک کلید بستگی به این دارد که آیا شما در حال ثبت کلید برای یک نام بسته جدید یا یک نام بسته موجود در اندروید هستید.

ثبت نام بسته جدید

برای نام بسته جدیدی که هرگز در اندروید دیده نشده است، می‌توانید گواهی کلید عمومی را از جفت کلید امضای برنامه ارائه دهید.

ثبت نام یک بسته موجود

برای ثبت نام یک بسته موجود، باید مالکیت یک کلید امضای خصوصی شناخته شده را اثبات کنید. برخلاف ثبت نام جدید، API لیستی از اثر انگشت‌های گواهی عمومی شناخته شده را که واجد شرایط ثبت هستند، برمی‌گرداند. این کلیدها را می‌توان برای ثبت مستقیم استفاده کرد.

اگر کلیدی که ثبت می‌کنید به عنوان «نیازمند توجیه» ذکر شده باشد، همچنان می‌توانید آن را ثبت کنید، اما علاوه بر تکمیل اثبات مالکیت، توسعه‌دهنده موظف است توجیهی برای استفاده از نام بسته نیز ارائه دهد.

قوانین کلیدی واجد شرایط بودن

فهرست کلیدهای واجد شرایط توسط قوانین مربوط به نام بسته تعیین می‌شود که برای به حداقل رساندن اشتراک‌گذاری نام بسته طراحی شده‌اند (که به عنوان بخشی از تأیید توسعه‌دهنده اندروید معرفی شده است).

در سناریوهایی که نام یک بسته توسط چندین توسعه‌دهنده استفاده می‌شود یا چندین کلید امضا دارد، واجد شرایط بودن به شرح زیر تعیین می‌شود:

تأیید مالکیت کلید

برای تکمیل تأیید نام بسته موجود، API یک رشته تأیید ارائه می‌دهد. این رشته تأیید باید در داخل یک فایل جدید به نام adi-registration.properties در پوشه assets برنامه قرار گیرد. سپس باید APK را با استفاده از کلید خصوصی مربوط به کلید عمومی که ثبت می‌کنید، امضا و آپلود کنید.

توجیه ثبت کلید

اگر ثبت کلید نیاز به توجیه داشته باشد، توسعه‌دهندگان باید توجیه تجاری دقیقی ارائه دهند. گوگل این توجیه را بررسی می‌کند و تأیید ثبت نام بسته می‌تواند تا ۲۴ ساعت طول بکشد.

بهترین شیوه‌های تجربه کاربری

توصیه می‌شود برنامه‌هایی که از API کنسول توسعه‌دهندگان اندروید استفاده می‌کنند، برای اطمینان از یکپارچه‌سازی بی‌نقص، از این الگوها پیروی کنند.

ایجاد زمینه‌ی مجوزدهی OAuth واضح

ارائه توضیحات واضح قبل از درخواست مجوز OAuth به توسعه‌دهندگان کمک می‌کند تا دلیل نیاز به دسترسی به حساب کاربری را درک کنند. برای راهنمایی مؤثر کاربران، قبل از اجرای صفحه رضایت OAuth، توضیح روشنی از عملکرد مورد انتظار ارائه دهید.

زمینه احراز هویت را با استفاده از قالب زیر ساختاردهی کنید:

• عنوان: "حساب کنسول توسعه‌دهنده اندروید خود را لینک کنید"
• خلاصه: "مدیریت ثبت نام بسته برای تأیید توسعه‌دهنده اندروید در [application-name]"
• دکمه اقدام: دکمه «ادامه با گوگل» یا «ورود با گوگل»

شناسایی حساب‌های توسعه‌دهندگان

1. با متد API مربوط ListDeveloperAccounts ادغام می‌شود تا تمام حساب‌های توسعه‌دهنده‌ای که دسترسی به آنها مجاز شده است را بازیابی و فهرست کند.
2. یک انتخابگر حساب کاربری ارائه دهید تا به توسعه‌دهنده اجازه دهد حساب کاربری توسعه‌دهنده مورد نظر خود را انتخاب کند.
3. با استفاده از شماره حساب از فیلد name به عنوان اطلاعات ثانویه، به طور برجسته نام حساب displayName نمایش دهید.
4. نمایش وضعیت‌های تأیید حساب ( verificationState ):
   • VERIFIED : هویت توسعه‌دهنده‌ی تأیید شده را با یک نشانه‌ی بصری مثبت (مثلاً یک تیک سبز) تأیید کنید.
   • NOT_VERIFIED : نشان می‌دهد که تأیید ناقص است و ثبت بسته برای حساب را محدود می‌کند. در صورت تمایل، یک دکمه فراخوان اصلی ارائه دهید که توسعه‌دهندگان را پس از انتخاب حساب به کنسول توسعه‌دهندگان اندروید هدایت کند.

اگر به دلیل عدم ارتباط حساب‌های توسعه‌دهنده با حساب گوگل، پاسخی خالی دریافت شد، توسعه‌دهندگان را با استفاده از یک دکمه فراخوان اصلی به کنسول توسعه‌دهندگان اندروید هدایت کنید.

مدیریت نام بسته‌ها

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. با ادغام با متد CreateAndroidPackageKey API، به توسعه‌دهندگان امکان می‌دهد کلیدهای اضافی را تحت نام یک بسته موجود ثبت کنند.

ثبت نام بسته

1. از یک طرح‌بندی مبتنی بر فرم استفاده کنید که در آن توسعه‌دهندگان نام بسته خود را در یک فیلد متنی وارد کنند، مشروط بر اینکه این اطلاعات قبلاً توسط برنامه شما جمع‌آوری نشده باشد (مثلاً از طریق یک درخواست قبلی).
2. برای ثبت نام یک بسته در حساب توسعه‌دهنده، متد CreateAndroidPackage API را فراخوانی کنید و برای تعیین قوانین واجد شرایط بودن کلید مربوطه، متد GetAndroidPackageRegistrationPolicy API را فراخوانی کنید.
3. بر اساس keySelectionStrategy تعیین‌شده برای نام بسته، از توسعه‌دهنده بخواهید یکی از موارد زیر را انجام دهد:
   • اگر keySelectionStrategy روی SELECT_KEY_FROM_LIST تنظیم شده باشد: از توسعه‌دهنده بخواهید که یک کلید را برای ثبت از لیست knownKeys ارائه‌شده (حاوی اثر انگشت‌های گواهی SHA-256) انتخاب کند، مانند استفاده از دکمه‌های رادیویی. این جریان نیاز به تأیید مالکیت کلید دارد ( به تأیید مالکیت یک کلید در زیر مراجعه کنید).
   • اگر keySelectionStrategy روی USE_ANY_KEY تنظیم شده باشد: از توسعه‌دهنده بخواهید که مستقیماً یک کلید ارائه دهد. در این مورد تأیید مالکیت کلید لازم نیست.
4. برای مرتبط کردن کلید انتخاب شده با نام بسته جدید، متد CreateAndroidPackageKey API را فراخوانی کنید.

از طرف دیگر، برنامه شما می‌تواند به طور خودکار نام یا کلید بسته را مستقیماً از یک برنامه آپلود شده شناسایی و استخراج کند.

تأیید مالکیت یک کلید

وقتی keySelectionStrategy روی SELECT_KEY_FROM_LIST تنظیم شده باشد، توسعه‌دهندگان باید مالکیت کلید امضای خصوصی خود را اثبات کنند. اثبات مالکیت مستلزم ارسال یک APK امضا شده است که شامل verificationToken تولید شده توسط API باشد.

برای پشتیبانی از تأیید مالکیت کلید، متد VerifyAndroidPackageKeyOwnership API را ادغام کرده و اجزای رابط کاربری زیر را بسازید:

• کامپوننت نمایش توکن: verificationToken به طور برجسته درون یک بلوک قطعه کد نمایش می‌دهد، از جمله یک دکمه‌ی مفید «کپی در کلیپ‌بورد».
• دستورالعمل‌های راه‌اندازی توسعه‌دهنده: دستورالعمل‌های دقیقی ارائه دهید که به توسعه‌دهنده راهنمایی می‌کند تا فایل adi-registration.properties حاوی verificationToken را در پوشه assets برنامه قرار دهد.
• منطقه‌ی رهاسازی ارسال APK: یک منطقه‌ی رهاسازی آپلود فایل اختصاصی برای دریافت APK امضا شده ارائه دهید.

توجیه ثبت یک کلید

وقتی فیلد justificationRequired برای یک کلید شناخته‌شده روی REQUIRED تنظیم شده باشد، ثبت آن کلید در کنار نام بسته، توسعه‌دهندگان را ملزم به ارائه یک دلیل تجاری کامل می‌کند.

این توجیه را با فراخوانی متد JustifyAndroidPackageKeyRegistration API ارسال کنید. اطمینان حاصل کنید که رابط کاربری برنامه شما دارای یک قسمت ورودی متن اختصاصی برای دریافت توجیه از توسعه‌دهنده است و قبل از ارسال درخواست ثبت کلید، به آنها اطلاع دهید که ارائه دلیل لازم است. گوگل توجیه ارسالی را بررسی می‌کند، فرآیندی که تأیید آن می‌تواند تا ۲۴ ساعت طول بکشد تا ثبت نام بسته تکمیل شود.

خودکارسازی تأیید کلید برای کلیدهای مدیریت‌شده

اگر برنامه شما کلید امضای توسعه‌دهنده را مدیریت می‌کند، توسعه‌دهنده نمی‌تواند به صورت دستی یک APK را برای تأیید مالکیت امضا کند. در عوض، شما باید فراخوانی API مربوط به VerifyAndroidPackageKeyOwnership را به طور خودکار از طرف او اجرا کنید.

با مدیریت خودکار فرآیند گنجاندن توکن و آپلود APK، برنامه شما این مراحل دستی را حذف می‌کند. حتماً به توسعه‌دهندگان اطلاع دهید که تأیید مالکیت کلید به طور یکپارچه توسط برنامه شما با استفاده از کلید ذخیره شده در سیستم شما مدیریت می‌شود.

دستورالعمل‌های برند را دنبال کنید

برای حفظ اعتماد کاربر و تضمین شفافیت، تمام برنامه‌هایی که با API کنسول توسعه‌دهندگان اندروید ادغام می‌شوند، ملزم به رعایت دستورالعمل‌های برند زیر هستند.

اصطلاحات و حروف بزرگ

هنگام ارجاع به محصول در مطالب یا مستندات مربوط به کاربر، همیشه از نام کامل Android Developer Console استفاده کنید. از مخفف "ADC" استفاده نکنید.

این برنامه باید به عنوان تأیید توسعه‌دهنده اندروید (Android developer verification) شناخته شود. در تمام متن‌ها، این حروف بزرگ و کوچک و املای دقیق را رعایت کنید.

برای جلوگیری از ابهام در مورد APKها یا AABها، به جای استفاده از کلمه "package"، از عبارت "package name" به طور خاص استفاده کنید.

هنگام توصیف فرآیند افزودن نام بسته، به جای «درخواست نام بسته»، از عبارت «ثبت نام بسته» استفاده کنید.

از فراخوان «ورود» استفاده کنید

احراز هویت OAuth 2.0 با کنسول توسعه‌دهندگان اندروید به سرویس‌های هویت گوگل متکی است. برای رعایت دستورالعمل‌های برندسازی سرویس‌های هویت گوگل ، باید از دکمه‌ی «ادامه با گوگل» یا «ورود با گوگل» برای اقدام استفاده کنید. این متن اجباری است و قابل تغییر نیست، زیرا به کاربران اطمینان می‌دهد که از اعتبارنامه‌های گوگل خود برای تأیید دسترسی به حساب گوگل خود به برنامه‌ی شما استفاده می‌کنند.

حفظ هویت و یکپارچگی برند

هنگام ادغام لوگوی کنسول توسعه‌دهندگان اندروید در رابط کاربری برنامه خود، باید این مشخصات را برای حفظ هویت بصری و یکپارچگی برند دنبال کنید:

• قرار دادن لوگو و سلسله مراتب: فقط از لوگوی رسمی و تأیید شده‌ی کنسول توسعه‌دهندگان اندروید استفاده کنید. لوگو باید همیشه در کنار عناصر اصلی برندسازی برنامه‌ی شما، در درجه‌ی دوم اهمیت قرار گیرد تا از نمایش نادرست برنامه به عنوان یک محصول رسمی گوگل جلوگیری شود.

• سبک بصری و اعوجاج‌ها: تصویر باید همیشه با نسبت ابعاد کاملاً محدود رندر شود. هرگز نباید اجزای لوگو را تحریف، کشیده، کج، برش، وارونه یا اصلاح کنید. پالت رنگ رسمی را تغییر ندهید، رنگ‌های پیش‌زمینه یا پس‌زمینه را عوض نکنید، یا سایه‌های برجسته، جلوه‌های درخشش یا گرادیان‌های تزئینی اعمال نکنید.
• محدودیت‌های استفاده: هیچ یک از عناصر برند متعلق به گوگل را در فایل‌های برنامه خود وارد نکنید. فایل لوگوی کنسول توسعه‌دهندگان اندروید فقط می‌تواند در داخل زمینه طرح‌بندی برنامه استفاده شود تا به صراحت نشان‌دهنده یکپارچه‌سازی فعال باشد.

منابع اضافی

• وضعیت ثبت برنامه را با API وضعیت شناسه توسعه‌دهنده اندروید بررسی کنید
• ثبت نام در کنسول توسعه دهندگان اندروید
• ثبت نام در کنسول گوگل پلی
• برنامه خود را امضا کنید