إنشاء روابط لصفحات معيّنة في محتوى التطبيق

عندما يستدعي رابط تم النقر عليه أو طلب آلي غرضًا لمعرّف الموارد المنتظم (URI) على الويب، يحاول نظام Android تنفيذ جميع الإجراءات التالية بترتيب تسلسلي، إلى أن يتم تنفيذ الطلب بنجاح:

  1. افتح تطبيق المستخدم المفضَّل الذي يمكنه التعامل مع معرّف الموارد المنتظم (URI) إذا تم تحديده.
  2. افتح التطبيق الوحيد المتاح الذي يمكنه التعامل مع معرّف الموارد المنتظم (URI).
  3. تسمح للمستخدم باختيار تطبيق من مربّع حوار.

اتّبِع الخطوات أدناه لإنشاء روابط تؤدي إلى المحتوى واختبارها. يمكنك أيضًا استخدام مساعد روابط التطبيقات في "استوديو Android" لإضافة "روابط تطبيقات Android".

ملاحظة: بدءًا من نظام التشغيل Android 12 (المستوى 31 من واجهة برمجة التطبيقات)، يتم تحويل الهدف العام على الويب إلى نشاط في تطبيقك فقط في حال الموافقة على تطبيقك للنطاق المحدّد المضمّن في هدف الويب هذا. إذا لم تتم الموافقة على تطبيقك في النطاق، ينتقل الغرض من الويب إلى تطبيق المتصفح التلقائي للمستخدم بدلاً من ذلك.

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

لإنشاء رابط إلى محتوى تطبيقك، أضِف فلتر أهداف يحتوي على العناصر التالية وقيم السمات في البيان:

<action>
حدِّد إجراء الهدف ACTION_VIEW ليكون بالإمكان الوصول إلى فلتر الأهداف من "بحث Google".
<data>
أضِف علامة <data> واحدة أو أكثر، وتمثّل كل علامة منها تنسيق معرّف موارد منتظم (URI) يؤدي إلى النشاط. ويجب أن تتضمّن العلامة <data> على الأقل السمة android:scheme.

يمكنك إضافة المزيد من السمات لتحسين نوع معرف الموارد المنتظم (URI) الذي يقبله النشاط. على سبيل المثال، قد تكون لديك أنشطة متعددة تقبل معرّفات موارد منتظمة (URI)، لكنّها تختلف ببساطة استنادًا إلى اسم المسار. في هذه الحالة، استخدِم السمة android:path أو الصيغتَين pathPattern أو pathPrefix للتمييز بين النشاط الذي يجب أن يفتحه النظام لمسارات معرّفات الموارد المنتظمة (URI) المختلفة.

<category>
يجب تضمين الفئة BROWSABLE. وهذا الإجراء مطلوب حتى يمكن الوصول إلى فلتر الأهداف من متصفّح ويب. وبدون هذا الرابط، لا يمكن أن يؤدي النقر على رابط في المتصفّح إلى الانتقال إلى تطبيقك.

يجب أيضًا تضمين الفئة DEFAULT. يسمح هذا لتطبيقك بالاستجابة للأهداف الضمنية. وبدون ذلك، لا يمكن بدء النشاط إلا إذا حدّد الغرض اسم مكون تطبيقك.

يوضّح مقتطف XML التالي كيفية تحديد فلتر أهداف في البيان الخاص بك للربط بصفحات معيّنة. يتم استخدام معرّفَي الموارد المنتظمين (URI) “example://gizmos” و “http://www.example.com/gizmos” معًا لهذا النشاط.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "http://www.example.com/gizmos” -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "example://gizmos” -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

يُرجى العلم أنّ فلترَي الأهداف يختلفان فقط في العنصر <data>. مع أنّه يمكن تضمين عدة عناصر <data> في الفلتر نفسه، من المهم إنشاء فلاتر منفصلة عندما يكون هدفك هو تحديد عناوين URL فريدة (مثل تركيبة معيّنة من scheme وhost)، لأنّ عناصر <data> المتعددة في فلتر الأهداف نفسه يتم دمجها معًا لاحتساب جميع صيغ سماتها المجمّعة. على سبيل المثال، ضع في اعتبارك ما يلي:

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

يبدو أنّ هذه الميزة متوافقة مع https://www.example.com وapp://open.my.app فقط. في المقابل، إنّه يتوافق في الواقع مع هذين العنصرَين، بالإضافة إلى ما يلي: app://www.example.com وhttps://open.my.app.

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

بعد إضافة فلاتر الأهداف مع معرّفات الموارد المنتظمة (URI) لمحتوى النشاط إلى بيان التطبيق، يمكن لنظام Android توجيه أي Intent يحتوي على معرّفات URI مطابقة إلى تطبيقك في وقت التشغيل.

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

قراءة البيانات من الأهداف الواردة

بعد أن يبدأ النظام نشاطك من خلال فلتر الأهداف، يمكنك استخدام البيانات المقدَّمة من Intent لتحديد ما تحتاج إلى عرضه. ويمكنك استدعاء الإجراءَين getData() وgetAction() لاسترداد البيانات والإجراء المرتبطَين بعلامة Intent الواردة. يمكنك استدعاء هذه الطرق في أي وقت خلال دورة حياة النشاط، ولكن عليك بشكل عام فعل ذلك أثناء معاودة الاتصال في مرحلة مبكرة مثل onCreate() أو onStart().

في ما يلي مقتطف يوضّح كيفية استرداد البيانات من Intent:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    val action: String? = intent?.action
    val data: Uri? = intent?.data
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();
}

يُرجى اتّباع أفضل الممارسات التالية لتحسين تجربة المستخدم:

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

اختبار الروابط المؤدية إلى صفحات في تطبيقك

يمكنك استخدام حزمة تصحيح أخطاء Android مع أداة مدير النشاط (am) لاختبار ما إذا كانت معرّفات الموارد المنتظمة (URI) لفلتر الأهداف التي حدّدتها للربط بصفحة معيّنة في التطبيق تؤدي إلى النشاط الصحيح على التطبيق. يمكنك تشغيل أمر adb على جهاز أو محاكي.

البنية العامة لاختبار عنوان URI لفلتر الأهداف باستخدام Adb هي:

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d <URI> <PACKAGE>

على سبيل المثال، يحاول الأمر أدناه عرض نشاط تطبيق مستهدف مرتبط بمعرّف الموارد المنتظم (URI) المحدد.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d "example://gizmos" com.example.android

يحدِّد تعريف البيان ومعالج الأهداف الذي ضبطته أعلاه العلاقة بين تطبيقك والموقع الإلكتروني وما يجب فعله بالروابط الواردة. ومع ذلك، لكي يتعامل النظام مع تطبيقك كمعالج تلقائي لمجموعة من معرّفات الموارد المنتظمة (URI)، يجب أيضًا أن تطلب من النظام التحقّق من هذا الاتصال. ويوضّح الدرس التالي كيفية تنفيذ عملية التحقّق هذه.

لمزيد من المعلومات عن الأغراض وروابط التطبيقات، اطّلِع على المراجع التالية: