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

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

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

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

ملاحظة: بدءًا من نظام التشغيل 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:

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

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

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

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

• فلاتر Intent وIntent
• السماح للتطبيقات الأخرى ببدء نشاطك
• إضافة Android App Links باستخدام "استوديو Android"