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

عندما يستدعي رابط تم النقر عليه أو طلب آلي هدف معرّف الموارد المنتظم (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 مع أداة مدير الأنشطة (am) لاختبار ما إذا كانت معرّفات الموارد المنتظمة (URI) لفلتر الأهداف التي حدّدتها للربط بصفحة معيّنة في التطبيق تعمل على النحو الصحيح. يمكنك تشغيل أمر adb على جهاز أو محاكي.

البنية العامة لاختبار عنوان URL لفلتر الأهداف باستخدام 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

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

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

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