تحديد المشاكل في روابط التطبيقات وحلّها

يصف هذا الدليل المشاكل الشائعة وكيفية تحديدها وحلّها. يمكنك أيضًا استخدام أدوات تحديد المشاكل وحلّها في صفحة "الروابط لصفحات في التطبيق" في Play Console أو "مساعد روابط التطبيقات" في استوديو Android. لمزيد من المعلومات، يُرجى الاطّلاع على أدوات المطوّرين لروابط التطبيقات.

  • المشكلة: عند النقر على رابط من المفترض أن يفتح تطبيقك، يتم فتحه في متصفّح ويب أو يظهر مربّع حوار لإزالة الغموض.
  • الحلّ:
    • التحقّق من ملف assetlinks.json: تأكَّد من أنّ الملف هو ملف JSON صالح، ويمكن الوصول إليه في المسار https://<your-domain>/.well-known/assetlinks.json، ويتم عرضه عبر HTTPS بدون عمليات إعادة توجيه. استخدِم أداة تحقّق على الإنترنت.
    • التحقّق من صحة الملف المرجعي لمعيار SHA-256: تأكَّد من أنّ sha256_cert_fingerprints في assetlinks.json يتطابق تمامًا مع الملف المرجعي لمفتاح التوقيع الخاص بإصدار تطبيقك (استخدِم الملف المرجعي من Play Console إذا كنت تستخدم ميزة "توقيع التطبيق" من Play). يجب أن يكون التوقيع بالأحرف الكبيرة.
    • التحقّق من autoVerify: تأكَّد من أنّ <intent-filter> في AndroidManifest.xml يتضمّن android:autoVerify="true".
    • التحقّق من عمليات إعادة التوجيه من جهة الخادم: يمكن أن تؤدي عمليات إعادة التوجيه من http إلى https أو من نطاق لا يتضمّن www إلى www إلى تعذُّر إثبات الملكية.
    • فرض إعادة التحقّق: نفِّذ أوامر Android Debug Bridge (ADB) في دليل اختبار روابط التطبيق للحصول على نتيجة تحقّق جديدة.
    • تشخيص حلّ الروابط (الإصدار 17 من Android والإصدارات الأحدث): يمكنك تشغيل adb shell am start --debug-link -a android.intent.action.VIEW -d "<URL>" لفحص التطبيقات المرشحة وفلاتر الأهداف في ملف البيان وقواعد روابط التطبيقات الديناميكية التي تتطابق مع عنوان URL. لمعرفة التفاصيل، يُرجى الاطّلاع على تشخيص دقة الرابط باستخدام علامة debug-link.

عدم تعديل القواعد الديناميكية على الإصدار 15 أو الإصدارات الأحدث من نظام التشغيل Android

  • المشكلة: لقد عدّلت القواعد في ملف assetlinks.json، ولكن لا تتم معالجة الروابط الجديدة من خلال التطبيق.
  • الحلّ:
    • فرض إعادة التحقّق: الطريقة الأكثر موثوقية لاختبار التغييرات هي فرض عملية إعادة جلب باستخدام adb shell pm verify-app-links --re-verify <your-package-name>.
    • البحث عن الأخطاء الإملائية: راجِع بعناية مطابِقات الأنماط في قواعدك بحثًا عن أي أخطاء في البنية.
    • التحقّق من قواعد فلترة ملف البيان: راجِع قواعد intent filter في ملف بيان التطبيق للتأكّد من عدم فلترة مسار الرابط. إذا تمت فلترة الرابط، اجعل فلتر الأهداف في بيان التطبيق أقل تقييدًا.
    • تشخيص قواعد المطابقة (الإصدار 17 من Android والإصدارات الأحدث): يمكنك تشغيل adb shell am start --debug-link -a android.intent.action.VIEW -d "<URL>" لفحص القواعد التي تم تقييمها وتحديد ما إذا كانت قاعدة الاستبعاد (allow = 1) قد منعت فتح التطبيق. يُرجى الاطّلاع على تشخيص حلّ الروابط باستخدام علامة debug-link.

إصلاح أخطاء التنفيذ الشائعة

إذا لم تتمكّن من التحقّق من صحة Android App Links، تحقَّق من الأخطاء الشائعة التالية. يستخدم هذا القسم example.com كاسم نطاق نائب، وعند إجراء عمليات التحقّق هذه، استبدِل example.com باسم النطاق الفعلي للخادم.

إعداد intent filter غير صحيح
تحقَّق مما إذا كنت قد أدرجت عنوان URL لا يملكه تطبيقك في عنصر <intent-filter>.
إعدادات الخادم غير صحيحة

تحقَّق من إعدادات JSON في الخادم، وتأكَّد من صحة قيمة SHA.

وتأكَّد أيضًا من أنّ example.com. (مع النقطة اللاحقة) يعرض المحتوى نفسه الذي يعرضه example.com.

عمليات إعادة التوجيه من جهة الخادم

لا يتحقّق النظام من أي روابط تطبيقات Android لتطبيقك إذا أعددت عملية إعادة توجيه مثل ما يلي:

  • من http://example.com إلى https://example.com
  • من example.com إلى www.example.com

ويحمي هذا السلوك أمان تطبيقك.

متانة الخادم

تحقَّق مما إذا كان بإمكان تطبيقات العميل الاتصال بالخادم.

الروابط التي لا يمكن التحقّق منها

لأغراض الاختبار، يمكنك إضافة روابط غير قابلة للتحقّق منها عمدًا. يُرجى العِلم أنّ هذه الروابط على نظام التشغيل Android 11 والإصدارات الأقدم تؤدي إلى عدم تحقّق النظام من جميع روابط تطبيقات Android في تطبيقك.

التوقيع غير صحيح في ملف assetlinks.json

يُرجى التأكّد من صحة توقيعك ومطابقته للتوقيع المستخدَم لتوقيع تطبيقك. تشمل الأخطاء الشائعة ما يلي:

  • توقيع التطبيق باستخدام شهادة تصحيح الأخطاء وتوفير توقيع الإصدار فقط في assetlinks.json
  • توقيع بأحرف صغيرة في assetlinks.json يجب أن يكون التوقيع بالأحرف الكبيرة.
  • إذا كنت تستخدم ميزة "توقيع التطبيق" من Play، تأكَّد من استخدام التوقيع الذي تستخدمه Google لتوقيع كل إصدار من إصداراتك. يمكنك التحقّق من هذه التفاصيل، بما في ذلك مقتطف JSON الكامل، من خلال اتّباع التعليمات حول الإفصاح عن عمليات الربط بالمواقع الإلكترونية.

تسجيل تقرير خطأ

بالنسبة إلى المشاكل المعقّدة التي يصعب إعادة إنتاجها، يمكنك تسجيل تقرير خطأ وتحليله. يمكن أن يوفّر ذلك إحصاءات قيّمة حول عملية التحقّق وأي أخطاء على مستوى النظام.