عیب‌یابی «پیوندهای برنامه»

این راهنما مشکلات رایج و نحوه عیب‌یابی آن‌ها را شرح می‌دهد. همچنین می‌توانید از ابزارهای عیب‌یابی در صفحه «پیوندهای عمیق» در «کنسول Play» یا «دستیار پیوندهای برنامه» در «استودیو Android» استفاده کنید. برای اطلاعات بیشتر، به ابزارهای توسعه‌دهنده App Links مراجعه کنید.

  • مشکل: روی پیوندی کلیک می‌کنید که باید برنامه‌تان را باز کند، اما در مرورگر وب باز می‌شود یا کادر گفتگوی ابهام‌زدایی نشان می‌دهد.
  • راه‌حل:
    • بررسی assetlinks.json: مطمئن شوید فایل JSON معتبر است، در https://<your-domain>/.well-known/assetlinks.json قابل‌دسترسی است، و ازطریق HTTPS بدون تغییر مسیر ارائه می‌شود. از اعتبارسنج آنلاین استفاده کنید.
    • درستی‌سنجی اثر انگشت SHA-256: دوباره بررسی کنید که sha256_cert_fingerprints در assetlinks.json دقیقاً با اثر انگشت کلید امضا برای انتشار برنامه‌تان مطابقت داشته باشد (اگر از «امضای برنامه» Play استفاده می‌کنید، از اثر انگشت موجود در «کنسول Play» استفاده کنید). امضا باید با حروف بزرگ باشد.
    • درستی‌سنجی autoVerify: مطمئن شوید <intent-filter> در AndroidManifest.xml شامل android:autoVerify="true باشد.
    • بررسی تغییر مسیرهای سمت سرور: تغییر مسیر از http به https یا از دامنه غیر www به www می‌تواند باعث ناموفق بودن درستی‌سنجی شود.
    • درستی‌سنجی مجدد اجباری: فرمان‌های ADB را در راهنمای آزمایش کردن پیوندهای برنامه اجرا کنید تا نتیجه درستی‌سنجی جدیدی دریافت کنید.
    • تشخیص وضوح پیوند (Android 17+): adb shell am start --debug-link -a android.intent.action.VIEW -d "<URL>" را اجرا کنید تا بررسی کنید کدام برنامه‌های نامزد، فیلترهای قصد مانیفست، و قوانین Dynamic App Link با نشانی وب مطابقت دارند. برای جزئیات، تشخیص وضوح پیوند با پرچم debug-link را ببینید.

قوانین پویا در Android نسخه ۱۵ و بالاتر به‌روز نمی‌شود

  • مشکل: قوانین را در فایل assetlinks.json به‌روز کرده‌اید، اما پیوندهای جدید توسط برنامه مدیریت نمی‌شوند.
  • راه‌حل:
    • درستی‌سنجی مجدد اجباری: مطمئن‌ترین راه برای آزمایش تغییرات، اجبار به واکشی مجدد با adb shell pm verify-app-links --re-verify <your-package-name> است.
    • بررسی غلط‌های املایی: مطابقت‌دهنده‌های الگو را در قوانینتان به‌دقت بررسی کنید تا خطای نحوی نداشته باشند.
    • بررسی قوانین فیلتر مانیفست: قوانین فیلتر قصد را در مانیفست برنامه بازبینی کنید تا مطمئن شوید مسیر پیوند فیلتر نشده باشد. اگر پیوند فیلتر می‌شود، فیلتر هدف را در مانیفست برنامه با محدودیت کمتری تنظیم کنید.
    • قوانین مطابقت عیب‌یابی (Android 17+): adb shell am start --debug-link -a android.intent.action.VIEW -d "<URL>" را اجرا کنید تا بررسی کنید کدام قوانین ارزیابی شده‌اند و تعیین کنید آیا قانون استثنایی (allow = 1) مانع از باز شدن برنامه شده است یا نه. به تشخیص وضوح پیوند با پرچم debug-link مراجعه کنید.

رفع خطاهای رایج پیاده‌سازی

اگر نمی‌توانید «پیوندهای برنامه Android» خود را به‌تأیید برسانید، خطاهای رایج زیر را بررسی کنید. این بخش از example.com به‌عنوان نام دامنه جای‌بان استفاده می‌کند؛ هنگام انجام این بررسی‌ها، example.com را با نام دامنه واقعی سرورتان جایگزین کنید.

راه‌اندازی فیلتر قصد نادرست است
بررسی کنید که آیا نشانی وبی را که متعلق به برنامه‌تان نیست در عنصر <intent-filter> گنجانده‌اید یا نه.
پیکربندی سرور نادرست است

پیکربندی JSON سرورتان را بررسی کنید و مطمئن شوید مقدار SHA درست باشد.

همچنین، بررسی کنید که example.com. (با نقطه پایانی) همان محتوای example.com را ارائه می‌دهد.

هدایت‌های مجدد سمت سرور

اگر بازهدایت‌هایی مثل موارد زیر راه‌اندازی کنید، سیستم هیچ‌کدام از «پیوندهای برنامه Android» را برای برنامه‌تان درستی‌سنجی نمی‌کند:

  • http://example.com تا https://example.com
  • example.com تا www.example.com

این رفتار از امنیت برنامه‌تان محافظت می‌کند.

استحکام سرور

بررسی کنید که آیا برنامه‌های کارخواه شما می‌توانند به سرورتان متصل شوند یا نه.

پیوندهای درستی‌سنجی‌نشدنی

برای اهداف آزمایشی، ممکن است عمداً پیوندهای غیرقابل‌تأیید اضافه کنید. به‌خاطر داشته باشید که در Android نسخه ۱۱ و پایین‌تر، این پیوندها باعث می‌شوند سیستم همه «پیوندهای برنامه Android» را برای برنامه‌تان درستی‌سنجی نکند.

امضا در assetlinks.json نادرست است

تأیید کنید که امضایتان درست است و با امضای استفاده‌شده برای امضا کردن برنامه‌تان مطابقت دارد. اشتباهات رایج عبارتند از:

  • امضای برنامه با گواهینامه اشکال‌زدایی و داشتن فقط امضای نسخه پخش در assetlinks.json.
  • داشتن امضای حروف کوچک در assetlinks.json. امضا باید با حروف بزرگ باشد.
  • اگر از «امضای برنامه» Play استفاده می‌کنید، مطمئن شوید از امضایی استفاده می‌کنید که Google برای امضای هریک از نسخه‌های پخش شما استفاده می‌کند. با دنبال کردن دستورالعمل‌های مربوط به اعلام کردن وابستگی‌های وب‌سایت، می‌توانید این جزئیات را (ازجمله قطعه JSON کامل) به‌تأیید برسانید.

ضبط گزارش اشکال

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