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

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

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

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

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

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

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

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

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

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