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

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

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

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

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

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

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

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

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

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

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

يوضّح مقتطف XML التالي كيفية تحديد فلتر أهداف في البيان لإنشاء روابط لصفحات معيّنة في التطبيق. يتم تحليل كل من معرّفَي الموارد الموحّدَين “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 يتضمّن معرّفات موارد منتظمة مطابقة إلى تطبيقك في وقت التشغيل.

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

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

بعد أن يبدأ النظام نشاطك من خلال فلتر الأهداف، يمكنك استخدام البيانات التي يوفّرها 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 Debug Bridge مع أداة "مدير الأنشطة" (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)، يجب أيضًا أن تطلب من النظام التحقّق من هذا الربط. يوضّح الدرس التالي كيفية تنفيذ عملية إثبات الملكية هذه.

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