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

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

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

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

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

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

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

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

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

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

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

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