مفاهیم اندروید (برای توسعه دهندگان وب)

Peter Conn

Joyce Toh

اگر یک توسعه دهنده وب هستید که به تازگی با اندروید و گوگل پلی آشنا شده اید، باید از برخی جزئیات آگاه باشید. در حال حاضر منابع و مستندات زیادی برای این کار وجود دارد (با تشکر از تیم Android) اما در اینجا به برخی از مفاهیم مهم و نحوه ارتباط آنها با Bubblewrap اشاره خواهیم کرد.

بارگذاری در مقابل کلید امضا

اگر قصد دارید از Bubblewrap برای تولید یک بسته نرم افزاری Android (AAB) استفاده کنید (توجه: از اوت 2021، Google Play تمام برنامه های جدید را ملزم می کند از قالب Android App Bundle استفاده کنند ) یا APK برای آپلود و انتشار در Google Play، باید برنامه خود را با یک کلید امضا امضا کنید. Google Play دو گزینه در اختیار شما می‌گذارد که چگونه می‌توانید این موضوع را مدیریت کنید:

• Play App Signing (به شدت توصیه می‌شود) : Google کلید امضای برنامه شما را مدیریت و محافظت می‌کند. از آن برای امضای APK های شما برای توزیع استفاده می کند. Play App Signing از دو کلید استفاده می کند. "کلید امضای برنامه" که Google برای شما مدیریت می کند و "کلید آپلود" که نگه می دارید و باید برای شما خصوصی بماند. از کلید آپلود برای امضای برنامه خود برای آپلود در کنسول Play استفاده می کنید. این سیستم این امکان را برای شما فراهم می کند که در صورت گم شدن یا به خطر افتادن کلید آپلود خود، با تماس با تیم پشتیبانی Play، آن را بازنشانی کنید. در حال حاضر، Google Play به شما امکان می دهد برنامه خود را به صورت AAB یا APK آپلود کنید:
  • Android App Bundle (AAB): وقتی یک AAB را در Play Console آپلود می کنید، ساخت و تولید APK ها را به فروشگاه Google Play موکول می کنید. وقتی کاربر برنامه شما را دانلود و نصب می‌کند، Google Play آن را به‌عنوان یک APK امضا شده در بین او توزیع می‌کند. بنابراین، امضای APK ها نیز باید توسط گوگل پلی انجام شود. بنابراین، به‌طور پیش‌فرض، اگر برنامه‌تان را به‌عنوان AAB در کنسول Play آپلود کنید، باید از Play App Signing استفاده کنید.
  • APK: با فایل‌های APK، می‌توانید در Play App Signing شرکت کنید. شرکت در Play App Signing بسیار توصیه می‌شود زیرا امنیت کلید امضای شما را افزایش می‌دهد. همانطور که قبلاً ذکر شد، Google Play به زودی نیاز خواهد داشت که همه برنامه‌های جدید در قالب AAB آپلود شوند، بنابراین توصیه می‌کنیم به جای آپلود APK این کار را انجام دهید.
• کلید امضای خود را مدیریت کنید : اگر تصمیم دارید کلید خود را مدیریت کنید و در Play App Signing شرکت نکنید، مسئولیت کامل کلید امضای برنامه خود را بر عهده دارید. برخلاف Play App Signing، در صورت گم شدن کلید، امکان بازنشانی آن وجود ندارد. بنابراین، از دست دادن کلید امضای برنامه به این معنی است که توانایی به روز رسانی برنامه خود را نیز از دست می دهید.

در طول راه‌اندازی bubblewrap init ، وقتی به بخش «اطلاعات کلید امضا (5/5)» رسیدید، از شما خواسته می‌شود «مکان ذخیره کلید» و «نام کلید» را وارد کنید یا از پیش‌فرض‌ها استفاده کنید. محل ذخیره کلید پیش‌فرض فایل android.keystore در فهرست پروژه شما است و نام کلید پیش‌فرض android است. اگر Bubblewrap یک فروشگاه کلید موجود با آن نام کلید در محل پیدا نکند، برای شما یک ذخیره‌سازی ایجاد می‌کند و همچنین از شما رمز عبور می‌خواهد. به گذرواژه‌هایی که وارد کرده‌اید توجه داشته باشید زیرا در طول فرآیند ساخت ( bubblewrap build ) به آن‌ها نیاز خواهید داشت، جایی که از کلید برای امضای برنامه شما استفاده می‌کند. اگر در Play App Signing شرکت کنید، کلید امضایی که Bubblewrap ایجاد کرده و برای امضای برنامه شما استفاده می‌کند به «کلید آپلود» تبدیل می‌شود. چه بخواهید از کلید Bubblewrap تولید شده به عنوان کلید امضا یا بارگذاری استفاده کنید، باید از کلید محافظت کرده و خصوصی نگه دارید. ما توصیه نمی کنیم آن را به کنترل نسخه متعهد کنید. در عوض، تعداد افرادی را که به آن دسترسی دارند محدود کنید.

پیوندهای دارایی دیجیتال

پیوندهای دارایی دیجیتال برای اعلام رابطه بین وب سایت و برنامه اندروید شما مورد نیاز است. برای اطمینان از اینکه برنامه 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

بسته به اینکه در Play App Signing شرکت کنید یا نه، ممکن است یک یا دو کلید داشته باشید. برای بازیابی اثر انگشت SHA256 مناسب برای هر کلید:

1. به کنسول Play بروید
2. برنامه مورد علاقه خود را انتخاب کنید
3. در منوی پیمایش در سمت چپ، در بخش Release ، به Setup -> App Integrity بروید.
4. SHA256 را برای کلید مناسب کپی کنید:

• کلید امضا : اثر انگشت SHA256 را برای "گواهینامه کلید امضای برنامه" کپی کنید. اگر آن را از فروشگاه Google Play دانلود کنید، این اثر انگشت با برنامه شما مطابقت دارد زیرا Google Play برنامه شما را با امضای کلید امضا توزیع می کند.

• کلید آپلود : اثر انگشت SHA256 را برای "گواهینامه کلید آپلود" کپی کنید. اگر آن را به صورت محلی (مثلاً از طریق ADB از طریق USB) نصب کنید، این اثر انگشت با برنامه شما مطابقت دارد. آن APK (در دستگاه محلی شما) توسط Bubblewrap ساخته شده است، و بنابراین، با کلیدی که برای شما ایجاد کرده است (در طول راه اندازی init ) امضا شده است. به یاد داشته باشید که این ممکن است کلید امضای برنامه نصب شده محلی شما باشد، اما در واقع زمانی که برنامه خود را از طریق Play منتشر می کنید، به "کلید آپلود" تبدیل می شود.

از طریق keytool

keytool یک ابزار مدیریت کلید و گواهی است. می توانید از ابزار کلید برای استخراج اثر انگشت SHA 256 مرتبط با APK یا AAB Bubblewrap تولید شده استفاده کنید. توجه داشته باشید که این اثر انگشت برای کلید امضای محلی است و اگر برنامه خود را در Play آپلود کنید و در Play App Signing شرکت کنید، این کلید به "کلید آپلود" تبدیل می شود.

keytool -printcert -jarfile [path to APK or AAB] | grep SHA256

از طریق ابزار پیوند دارایی

راه دیگر برای دریافت فایل پیوند دارایی دیجیتال صحیح برای برنامه خود، استفاده از ابزار پیوند دارایی است:

1. ابزار Asset Link Tool را از Play Store نصب کنید.
2. در همان دستگاه، برنامه خود را از فروشگاه Google Play دانلود کنید یا آن را به صورت محلی نصب کنید.
3. برنامه Asset Link Tool را باز کنید، و لیستی از همه برنامه های نصب شده بر روی دستگاه شما بر اساس نام بسته به شما داده می شود. لیست را با شناسه برنامه‌ای که قبلاً در bubblewrap init انتخاب کرده‌اید فیلتر کنید و روی آن ورودی کلیک کنید.
4. صفحه‌ای را مشاهده می‌کنید که امضای برنامه شما و پیوند دارایی دیجیتال ایجاد شده را فهرست می‌کند. روی دکمه‌های کپی یا اشتراک‌گذاری در پایین کلیک کنید تا هر طور که دوست دارید صادر کنید (مثلاً در Google Keep ذخیره کنید، آن را برای خودتان ایمیل کنید).

همان ایده قبلی در مورد کلیدهای امضا یا آپلود اعمال می شود. اگر برنامه خود را از فروشگاه Google Play نصب کرده باشید، ابزار پیوند دارایی اثر انگشت کلید امضای برنامه را در اختیار شما قرار می دهد. اگر برنامه را مستقیماً از دستگاه محلی خود نصب کرده اید، اثر انگشت مربوط به کلید Bubblewrap تولید شده است.

اطمینان حاصل کنید که فایل پیوند دارایی شما در دسترس است

اکنون که آن را آپلود کردید، مطمئن شوید که می توانید به فایل پیوند دارایی خود در مرورگر دسترسی داشته باشید. بررسی کنید که https://example.com/.well-known/assetlinks.json به فایلی که اخیراً آپلود کرده اید حل شود.

وب سایت های مبتنی بر جکیل

اگر وب سایت شما توسط Jekyll (مانند صفحات GitHub) تولید شده است، باید یک خط پیکربندی اضافه کنید تا فهرست .well-known در خروجی گنجانده شود. راهنمای GitHub اطلاعات بیشتری در مورد این موضوع دارد. فایلی به نام _config.yml در ریشه سایت خود ایجاد کنید (یا اگر از قبل وجود داشت به آن اضافه کنید) و وارد کنید:

# Folders with dotfiles are ignored by default.
include: [.well-known]

اضافه کردن کلیدهای بیشتر

یک فایل پیوند دارایی دیجیتال می تواند بیش از یک برنامه داشته باشد و برای هر برنامه می تواند بیش از یک کلید داشته باشد. به عنوان مثال، برای افزودن کلید دوم، کافی است از ابزار Asset Link Tool برای تعیین کلید استفاده کنید و آن را به عنوان ورودی دوم اضافه کنید. کد موجود در کروم که این 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 دلیل عدم موفقیت در تأیید پیوندهای دارایی دیجیتال را ثبت می‌کند و می‌توانید گزارش‌ها را در دستگاه Android با adb logcat مشاهده کنید. اگر در حال توسعه در Linux/Mac هستید، می‌توانید گزارش‌های مربوطه را از یک دستگاه متصل با موارد زیر مشاهده کنید:

> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

برای مثال، اگر پیغام Statement failure matching fingerprint. ، باید از ابزار Asset Link Tool برای دیدن امضای برنامه خود استفاده کنید و مطمئن شوید که با فایل assetlinks.json مطابقت دارد.