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

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

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

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

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

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

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

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

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

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

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

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

بعد إضافة فلاتر الأهداف التي تحتوي على معرّفات الموارد المنتظمة لمحتوى النشاط إلى ملف манифест تطبيقك، يمكن لنظام التشغيل 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 DebugBridge مع أداة "مدير النشاط" (am) لاختبار معرّفات الموارد المنتظمة (URI) لفلتر الأهداف التي حدّدتها للربط بصفحات معيّنة في النشاط الصحيح على التطبيق. يمكنك تنفيذ الأمر adb على جهاز أو محاكي.

الصيغة العامة لاختبار معرّف الموارد المنتظم (URI) لفلتر الأهداف باستخدام adb هي:

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

على سبيل المثال، يحاول الأمر أدناه عرض نشاط تطبيق مستهدَف يكون مرتبطًا بعنوان URL المحدّد.

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

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

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