إضافة فلاتر الأهداف لروابط التطبيقات

"روابط التطبيقات" هي روابط عميقة تستخدم مخطط HTTP أو HTTPS ويتأكّد نظام التشغيل Android من أنّها مرتبطة بموقعك الإلكتروني. للتسجيل لمعالجة روابط التطبيقات، اتّبِع الخطوات التالية:

أضِف فلتر هدف واحدًا أو أكثر إلى بيان التطبيق لتحديد نطاق موقعك الإلكتروني أو عناوين URL.
أضِف autoVerify="true"attribute إلى عناصر intent filter. يشير ذلك إلى النظام بأنّه يجب محاولة التحقّق من المخطط والنطاقات المضيفة استنادًا إلى إعدادات assetlinks.json لموقعك الإلكتروني.
تحديد المواقع الإلكترونية المرتبطة

في ما يلي مثال على بيان App Link يتضمّن المخططات والمضيفين بالإضافة إلى autoVerify="true":

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- Make sure you explicitly set android:autoVerify to "true". -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- If a user clicks on a link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

        <!-- Include one or more domains that should be verified. -->
        <data android:host="www.example.com" />
        <data android:host="*.example.com" />
    </intent-filter>
</activity>

النقاط الرئيسية حول الرمز

AutoVerify: السمة android:autoVerify="true" مطلوبة لروابط التطبيقات. ويشير إلى النظام بأنّه يجب محاولة التحقّق من الربط بين تطبيقك والمخططات والنطاقات المحدّدة في علامات <data>. يُنصح بإضافة autoVerify="true إلى كل فلتر Intent تريد أن يكون قابلاً للتحقّق.
عناصر البيانات: يجب أن يتضمّن كل فلتر أهداف لروابط التطبيقات عنصرًا واحدًا أو أكثر من عناصر <data> التي تحدّد المخططات وتنسيقات المضيف التي تتطابق مع نطاق موقعك الإلكتروني القابل للإثبات.
المخططات: يجب أن يتضمّن فلتر intent عناصر <data> لكل من المخططين http وhttps.
المضيفون: يمكنك اختياريًا إضافة عناصر <data> لمطابقة مضيف واحد أو أكثر. استخدِم حرف بدل (*) لمطابقة نطاقات فرعية متعددة (مثل *.example.com). سيحاول النظام التحقّق من كل مضيف باستخدام ملف assetlinks.json على موقعك الإلكتروني. يُرجى العِلم أنّه يجب أن يتولّى ملف assetlinks.json معالجة أي توجيه على مستوى المسار (راجِع قسم أفضل الممارسات أدناه).
مضيفات متعددة: إذا أعلنت عن نطاقات مضيفة متعددة، سيحاول النظام (على Android 12 والإصدارات الأحدث) إثبات ملكية كل منها. إذا تم إثبات ملكية أي مضيف، سيصبح التطبيق هو المعالج التلقائي للروابط من هذا المضيف الذي تم إثبات ملكيته. في نظام التشغيل Android 11 والإصدارات الأقدم، يتعذّر التحقّق من صحة الشهادة إذا تعذّر التحقّق من صحة شهادة مضيف واحد على الأقل.
فلاتر Intent المتعددة: من المهم إنشاء فلاتر منفصلة عندما يكون هدفك هو تعريف عناوين URL فريدة (مثل مجموعة معيّنة من المخطط والمضيف)، لأنّه يتم دمج عناصر <data> المتعددة في فلتر Intent نفسه معًا لاحتساب جميع أشكال سماتها المجمّعة.

اعتبارات لقواعد فلترة البيان

إذا كنت بصدد إعداد فلاتر لاستخدامها مع "روابط التطبيق الديناميكية" في نظام التشغيل Android 15 والإصدارات الأحدث، من المهم تذكُّر أنّ القواعد الديناميكية المحدّدة في ملف assetlinks.json من جهة الخادم لا يمكنها توسيع نطاق قواعد عناوين URL التي تحدّدها بشكل ثابت في بيان تطبيقك.

لهذا السبب، ننصحك باتّباع هذا النهج:

في بيان التطبيق، اضبط النطاق الأوسع قدر الإمكان، مثلاً من خلال تعريف المخطط والنطاق فقط
الاعتماد على قواعد ملف assetlinks.json من جهة الخادم لإجراء المزيد من التحسينات، مثل التوجيه على مستوى المسار

باستخدام هذا الإعداد المثالي، ستتمكّن من إضافة مسارات جديدة لروابط التطبيق بشكل ديناميكي في الملف assetlinks.json حسب الحاجة، مع العلم أنّها ستندرج ضمن النطاق الواسع الذي حدّدته في بيان التطبيق.

إتاحة روابط التطبيقات لمضيفين متعدّدين

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

على سبيل المثال، سيجتاز تطبيق يتضمّن فلاتر الأهداف التالية عملية التحقّق فقط بالنسبة إلى https://www.example.com إذا تم العثور على ملف assetlinks.json في https://www.example.com/.well-known/assetlinks.json وليس https://www.example.net/.well-known/assetlinks.json:

<application>

  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name="SecondActivity">
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

إتاحة ربط التطبيق بنطاقات فرعية متعددة

يتعامل بروتوكول روابط تنقل إلى مواد عرض رقمية مع النطاقات الفرعية في intent filter على أنّها مضيفات فريدة ومنفصلة. لذلك، إذا كانت قائمة intent filter تتضمّن مضيفين متعدّدين بنطاقات فرعية مختلفة، عليك نشر ملف assetlinks.json صالح على كل نطاق. على سبيل المثال، يتضمّن intent filter التالي www.example.com وmobile.example.com كمضيفَين مقبولَين لعنوان URL الخاص بـ intent. لذلك، يجب نشر assetlinks.json صالح في كل من https://www.example.com/.well-known/assetlinks.json وhttps://mobile.example.com/.well-known/assetlinks.json.

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

بدلاً من ذلك، إذا حدّدت اسم المضيف باستخدام حرف بدل (مثل *.example.com)، عليك نشر ملف assetlinks.json في اسم المضيف الجذر (example.com). على سبيل المثال، سيتجاوز التطبيق الذي يتضمّن intent filter التالي عملية التحقّق لأي اسم فرعي من example.com (مثل foo.example.com) طالما تم نشر ملف assetlinks.json في https://example.com/.well-known/assetlinks.json:

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

التحقّق من وجود تطبيقات متعدّدة مرتبطة بالنطاق نفسه

إذا نشرت تطبيقات متعددة يرتبط كل منها بالنطاق نفسه، يمكن إثبات ملكية كل تطبيق بنجاح. ومع ذلك، إذا كانت التطبيقات يمكنها تحديد المضيف والمسار نفسهما بالضبط للنطاق، كما هو الحال مع الإصدارَين المخفّف والكامل من التطبيق، لن يتمكّن سوى التطبيق الذي تم تثبيته مؤخرًا من تحديد طلبات البحث على الويب لهذا النطاق.

في مثل هذه الحالة، تحقَّق من التطبيقات التي قد تتعارض مع بعضها على جهاز المستخدم، وذلك إذا كان لديك إذن الوصول إلى حزمة التطبيق اللازم. بعد ذلك، في تطبيقك، اعرض مربّع حوار مخصّصًا لاختيار التطبيق يتضمّن النتائج التي تم الحصول عليها من خلال طلب queryIntentActivities. يمكن للمستخدم اختيار التطبيق المفضّل لديه من قائمة التطبيقات المتطابقة التي تظهر في مربّع الحوار.

التوافق مع الأنظمة القديمة لـ "روابط التطبيق الديناميكية" على الإصدار 14 من نظام التشغيل Android والإصدارات الأقدم

لا تتوفّر ميزات "روابط التطبيقات الديناميكية"، بما في ذلك قواعد المطابقة المتقدّمة في assetlinks.json واستخدام <uri-relative-filter-group>، بشكل كامل إلا على الإصدار 15 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 35) والإصدارات الأحدث.

في الإصدار 14 من نظام التشغيل Android (المستوى 34 لواجهة برمجة التطبيقات) والإصدارات الأقدم، لا يأخذ النظام في الاعتبار سوى scheme وhost المحدّدتَين في عناصر <data> في ملف البيان لإثبات ملكية App Link. لا يتم تطبيق القواعد والاستثناءات والتعديلات الديناميكية الخاصة بالمسار من ملف assetlinks.json.

وهذا يعني أنّه إذا كان ملف البيان يحدّد scheme وhost فقط، قد يلتقط تطبيقك بشكل غير متوقّع جميع المسارات للنطاق الذي تم إثبات ملكيته على الإصدار 14 من نظام التشغيل Android والإصدارات الأقدم، بغض النظر عن القواعد الخاصة بالمسار المحدّدة في assetlinks.json للإصدار 15 من نظام التشغيل Android والإصدارات الأحدث.

استراتيجية احتياطية لإعداد إصدارات Android الأقدم بدون روابط لصفحات في التطبيق

لمنع تطبيقك من التعامل مع جميع الروابط الخاصة بنطاق معيّن على الإصدار 14 من نظام التشغيل Android والإصدارات الأقدم عندما تريد استخدام "روابط التطبيق الديناميكية" لمسارات أكثر تحديدًا على الإصدار 15 من نظام التشغيل Android والإصدارات الأحدث، عليك تضمين مسار غير مطابق في فلتر الأهداف في البيان. أضِف عنصر <data> مع سمة android:path من غير المحتمل أن تكون مسارًا صالحًا للروابط. يضمن ذلك عدم تطابق intent filter مع جميع المسارات في الإصدارات الأقدم.

مثال:

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

من خلال إضافة <data android:path="/no_match_for_older_android_versions" />، يمكنك التأكّد من أنّ فلتر الأهداف هذا لا يتطابق مع أي روابط واردة على الإصدار 14 من نظام التشغيل Android والإصدارات الأقدم، مع السماح في الوقت نفسه بالتحقّق من صحة النطاق لاستخدامه مع "روابط التطبيقات الديناميكية" على الإصدار 15 من نظام التشغيل Android والإصدارات الأحدث استنادًا إلى قواعد المطابقة المتقدّمة في قواعد assetlinks.json.

تحذير: إذا ضبطت <uri-relative-filter-group> في ملف البيان على الإصدار 15 من نظام التشغيل Android أو الإصدارات الأحدث، تأكَّد من إمكانية الوصول إلى ملف assetlinks.json صالح على المضيف المحدّد. في حال كان ملف assetlinks.json مفقودًا أو غير صالح، لن يتم إثبات ملكية روابط التطبيقات على الإصدار 15 من نظام التشغيل Android والإصدارات الأحدث، ولن يتعامل تطبيقك مع أي روابط لهذا النطاق. في حالات أخرى، يكون فيها ملف assetlinks.json صالحًا ولكنّه لا يتضمّن الإعدادات الديناميكية، قد يفتح التطبيق جميع المسارات على الإصدار 15 من نظام التشغيل Android والإصدارات الأحدث استنادًا إلى بيان التطبيق الثابت.

نقل روابط التطبيق الحالية

إذا كانت لديك روابط تطبيقات تتضمّن قواعد مسار محدّدة (مثل android:pathPrefix) في البيان الخاص بك وأردت البدء في استخدام "روابط التطبيقات الديناميكية" على نظام التشغيل Android 15 والإصدارات الأحدث، يمكنك إضافة العنصر <uri-relative-filter-group> بأمان مباشرةً إلى فلاتر الأهداف الحالية.

بما أنّ الإصدار 14 من نظام التشغيل Android والإصدارات الأقدم تتجاهل العنصر <uri-relative-filter-group>، ستستمر روابط التطبيق الحالية في العمل تمامًا كما تعمل الآن على الأجهزة التي تعمل بإصدارات أقدم من Android.

ومع ذلك، يجب التفكير بعناية في كيفية تقييم الإصدار 15 من نظام التشغيل Android والإصدارات الأحدث للإعداد "المختلط":

الفلترة على مستويَين: في نظام التشغيل Android 15 والإصدارات الأحدث، يقيّم النظام فلاتر الأهداف كمجموعة. يجتاز عنوان URL عملية التحقّق من ملف البيان إذا كان يستوفي إما علامات <data> الثابتة القديمة أو القواعد العامة في <uri-relative-filter-group>. بعد أن يجتاز عنوان URL عملية التحقّق الأولية من ملف البيان، يطبّق النظام القواعد الديناميكية المحدّدة في ملف assetlinks.json كطبقة ثانية من الفلترة الدقيقة. وهذا يعني أنّ قواعد JSON من جهة الخادم هي التي تحدّد في النهاية عناوين URL المطابِقة التي تفتح التطبيق.

مثال على إعدادات مختلطة:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" />
    <data android:host="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>