فلاتر الأهداف والنية

Intent هو عنصر مراسلة يمكنك استخدامه لطلب إجراء من مكوّن تطبيق آخر. على الرغم من أنّ ملفات Intent تسهّل التواصل بين المكوّنات بعدة طرق، هناك ثلاث حالات استخدام أساسية:

• بدء نشاط

  يمثّل Activity شاشة واحدة في تطبيق. يمكنك بدء مثيل جديد لعنصر Activity من خلال تمرير Intent إلى startActivity(). تصف السمة Intent النشاط المطلوب بدؤه وتحمل أي بيانات ضرورية.

  إذا أردت تلقّي نتيجة من النشاط عند انتهائه، اتصل على startActivityForResult(). يتلقّى نشاطك النتيجة كعنصر Intent منفصل في دالة ردّ الاتصال onActivityResult() لنشاطك. لمزيد من المعلومات، يُرجى الاطّلاع على دليل الأنشطة.

• بدء خدمة

  Service هو مكوّن ينفِّذ العمليات في الخلفية بدون واجهة مستخدم. باستخدام الإصدار 5.0 من نظام التشغيل Android (المستوى 21 من واجهة برمجة التطبيقات) والإصدارات الأحدث، يمكنك بدء خدمة باستخدام JobScheduler. لمزيد من المعلومات عن JobScheduler، يُرجى الاطّلاع على API-reference documentation.

  بالنسبة إلى الإصدارات الأقدم من Android 5.0 (المستوى 21 من واجهة برمجة التطبيقات)، يمكنك بدء خدمة باستخدام methods من فئة Service. يمكنك بدء خدمة لتنفيذ عملية لمرة واحدة (مثل تنزيل ملف) من خلال تمرير Intent إلى startService(). يصف Intent الخدمة التي سيتم تشغيلها ويحمل أي بيانات ضرورية.

  إذا تم تصميم الخدمة باستخدام واجهة بين العميل والخادم، يمكنك الربط بالخدمة من مكوّن آخر عن طريق تمرير Intent إلى bindService(). لمزيد من المعلومات، يُرجى الاطّلاع على دليل الخدمات.

• إرسال بث

  البث هو رسالة يمكن لأي تطبيق تلقّيها. يُرسِل النظام محتوًى مختلفًا للبثّ لأحداث النظام، مثل بدء تشغيل النظام أو بدء شحن الجهاز. يمكنك إرسال بث إلى تطبيقات أخرى من خلال تمرير Intent إلى sendBroadcast() أو sendOrderedBroadcast().

توضّح بقية هذه الصفحة آلية عمل النوايا وكيفية استخدامها. للاطّلاع على معلومات ذات صلة، يُرجى الاطّلاع على مقالتَي التفاعل مع التطبيقات الأخرى ومشاركة المحتوى.

أنواع الأهداف

هناك نوعان من النوايا:

• تحدِّد المقصودات الصريحة المكوّن الذي سيلبّي المقصود من التطبيق، وذلك من خلال تحديد ComponentName كامل. ستستخدم عادةً نية صريحة لبدء مكوّن في تطبيقك، لأنّك تعرف اسم فئة النشاط أو الخدمة التي تريد بدؤها. على سبيل المثال، يمكنك بدء نشاط جديد في تطبيقك استجابةً للإجراء الذي يتّخذه المستخدم، أو بدء خدمة لتنزيل ملف في الخلفية.
• لا تحدِّد الأهداف الضمنية اسم مكوّن معيّنًا، بل تحدِّد بدلاً من ذلك إجراءً عامًا لإجرائه، ما يسمح لمكوّن من تطبيق آخر بتنفيذه. على سبيل المثال، إذا كنت تريد إظهار موقع جغرافي للمستخدم على خريطة، يمكنك استخدام نية ضمنية لطلب عرض موقع جغرافي محدّد على خريطة من تطبيق آخر مزوّد بإمكانية عرض الخرائط.

يوضِّح الشكل 1 كيفية استخدام النية عند بدء نشاط. عندما يُسمّي عنصر Intent مكوّن نشاط معيّنًا بشكل صريح، يبدأ النظام هذا المكوّن على الفور.

الشكل 1: كيفية إرسال نية ضمنية من خلال النظام لبدء نشاط آخر: [1] ينشئ النشاط "أ" Intent يحتوي على وصف إجراء ويمرره إلى startActivity(). [2] يبحث نظام Android في كل التطبيقات عن فلتر أهداف يتطابق مع الطلب. عند العثور على مطابقة، [3] يشغّل النظام النشاط المطابق (العملية ب) من خلال استدعاء طريقة onCreate() ونقل القيمة Intent إليها.

عند استخدام نية ضمنية، يعثر نظام Android على المكوّن المناسب لبدء التطبيق من خلال مقارنة محتوى النية بفلاتر الأهداف المُعلَن عنها في ملف البيان للتطبيقات الأخرى على الجهاز. إذا تطابق الغرض مع فلتر غرض، يبدأ النظام هذا المكوّن ويرسله كائن Intent. إذا كانت عدّة فلاتر أهداف متوافقة، يعرض النظام مربّع حوار حتى يتمكّن المستخدم من اختيار التطبيق الذي يريد استخدامه.

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

تحذير: لضمان أمان تطبيقك، يجب استخدام Service معيّن عند بدء Service وعدم تحديد فلاتر Service لخدماتك. يشكّل استخدام نية ضمنية لبدء خدمة خطرًا على الأمن لأنّه لا يمكنك التأكّد من الخدمة التي ستستجيب للنية، ولا يمكن للمستخدم معرفة الخدمة التي يتم تشغيلها. بدءًا من الإصدار 5.0 من Android (المستوى 21 لواجهة برمجة التطبيقات)، يُرسِل النظام استثناءً في حال استدعاء bindService() باستخدام نية ضمنية.

إنشاء نية

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

في ما يلي المعلومات الأساسية الواردة في Intent:

اسم المكوّن

اسم المكوّن الذي سيتم تشغيله.

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

ملاحظة: عند بدء Service، حدِّد دائمًا اسم المكوّن. بخلاف ذلك، لا يمكنك التأكّد من الخدمة التي ستستجيب للطلب، ولا يمكن للمستخدم معرفة الخدمة التي سيتم تشغيلها.

هذا الحقل من Intent هو كائن ComponentName، ويمكنك تحديده باستخدام اسم فئة مؤهَّل بالكامل للمكوّن المستهدَف، بما في ذلك اسم حزمة التطبيق، على سبيل المثال، com.example.ExampleActivity. يمكنك ضبط اسم المكوّن باستخدام setComponent() أو setClass() أو setClassName() أو باستخدام Intent.

الإجراء

سلسلة تحدّد الإجراء العام المطلوب تنفيذه (مثل عرض أو اختيار).

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

يمكنك تحديد إجراءاتك الخاصة لاستخدامها من قِبل النوايا داخل تطبيقك (أو لاستخدامها من قِبل التطبيقات الأخرى لاستدعاء المكوّنات في تطبيقك)، ولكنك عادةً ما تحدّد ثوابت الإجراءات التي تحدّدها فئة Intent أو فئات إطار العمل الأخرى. في ما يلي بعض الإجراءات الشائعة لبدء نشاط:

ACTION_VIEW

استخدِم هذا الإجراء في نية مع startActivity() عندما يكون لديك بعض المعلومات التي يمكن أن يعرضها النشاط للمستخدم، مثل صورة لعرضها في تطبيق معرض صور أو عنوان لعرضه في تطبيق خرائط.

ACTION_SEND

يُعرف هذا الإذن أيضًا باسم إذن المشاركة، ويجب استخدامه في طلب مع startActivity() عندما يكون لديك بعض البيانات التي يمكن للمستخدم مشاركتها من خلال تطبيق آخر، مثل تطبيق بريد إلكتروني أو تطبيق مشاركة على وسائل التواصل الاجتماعي.

اطّلِع على مرجع فئة Intent للحصول على مزيد من الثوابت التي تحدّد الإجراءات العامة. يتم تعريف الإجراءات الأخرى في مكان آخر في إطار عمل Android، مثل Settings للإجراءات التي تفتح شاشات معيّنة في تطبيق "الإعدادات" للنظام.

يمكنك تحديد الإجراء لطلب باستخدام setAction() أو باستخدام عنصر إنشاء Intent.

إذا حدّدت إجراءاتك الخاصة، احرص على تضمين اسم حزمة تطبيقك كبادئة، كما هو موضّح في المثال التالي:

Kotlin

const val ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL"

Java

static final String ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL";

البيانات

معرّف الموارد المنتظم (URI) (عنصر Uri) الذي يشير إلى البيانات التي يجب اتّخاذ إجراء بشأنها و/أو نوع MIME لهذه البيانات. ويحدِّد الإجراء المرتبط بالنية نوع البيانات المقدَّمة بشكل عام. على سبيل المثال، إذا كان الإجراء هو ACTION_EDIT، يجب أن تحتوي البيانات على معرّف الموارد المتّصل (URI) للمستند المطلوب تعديله.

عند إنشاء نية، من المهمّ غالبًا تحديد نوع البيانات (نوع MIME) بالإضافة إلى معرّف الموارد المنتظم (URI). على سبيل المثال، النشاط الذي يمكنه عرض الصور قد لا يتمكن من تشغيل ملف صوتي، حتى لو كانت تنسيقات معرّفات الموارد المنتظمة متشابهة. يساعد تحديد نوع MIME لبياناتك نظام Android في العثور على أفضل مكوّن لتلقّي طلبك. ومع ذلك، يمكن في بعض الأحيان استنتاج نوع MIME من معرّف الموارد المنتظم (URI)، خاصةً عندما تكون البيانات هي معرّف موارد content: المنتظم. يشير content: URI إلى أنّ البيانات متوفّرة على الجهاز ويتحكم فيهاContentProvider، ما يجعل نوع MIME للبيانات مرئيًا للنظام.

لضبط عنوان URI للبيانات فقط، اتصل بالرقم setData(). لضبط نوع MIME فقط، اتصل بالرقم setType(). إذا لزم الأمر، يمكنك ضبط كليهما بشكل صريح باستخدام setDataAndType().

تحذير: إذا كنت تريد ضبط كل من معرّف الموارد المنتظم ونوع MIME، لا تستخدِم setData() و setType() لأنّ كلّ منهما يُلغي قيمة الآخر. استخدِم دائمًا setDataAndType() لضبط كلٍّ من عنوان URL ونوع MIME.

الفئة

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

CATEGORY_BROWSABLE

يسمح النشاط المستهدَف لمتصفّح الويب ببدءه لعرض البيانات التي يشير إليها رابط، مثل صورة أو رسالة إلكترونية.

CATEGORY_LAUNCHER

النشاط هو النشاط الأولي للمهمة ويتم إدراجه في مشغّل تطبيقات النظام.

اطّلِع على وصف فئة Intent للحصول على القائمة الكاملة للفئات.

يمكنك تحديد فئة باستخدام addCategory().

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

الإضافات

أزواج المفاتيح والقيم التي تحتوي على معلومات إضافية مطلوبة لإكمال الإجراء المطلوب تمامًا كما تستخدم بعض الإجراءات أنواعًا معيّنة من عناوين URL للبيانات، تستخدم بعض الإجراءات أيضًا عناصر إضافية معيّنة.

يمكنك إضافة بيانات إضافية باستخدام طرق putExtra() مختلفة، يقبل كلّ منها مَعلمتَين: اسم المفتاح والقيمة. يمكنك أيضًا إنشاء عنصر Bundle يتضمّن كل البيانات الإضافية، ثم إدراج Bundle في Intent باستخدام putExtras().

على سبيل المثال، عند إنشاء نية لإرسال رسالة إلكترونية باستخدام ACTION_SEND، يمكنك تحديد المستلِم إلى باستخدام المفتاح EXTRA_EMAIL، وتحديد الموضوع باستخدام المفتاح EXTRA_SUBJECT.

تحدّد فئة Intent العديد من الثوابت EXTRA_* لأنواع البيانات الموحدة. إذا كنت بحاجة إلى الإفصاح عن مفاتيح إضافية خاصة بك (للنوايا التي يتلقّاها تطبيقك)، احرص على تضمين اسم حزمة تطبيقك كبادئة، كما هو موضّح في المثال التالي:

Kotlin

const val EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS"

Java

static final String EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS";

تحذير: لا تستخدِم بيانات Parcelable أو Serializable عند إرسال نية تتوقّع أن يتلقّاها تطبيق آخر. إذا حاول تطبيق الوصول إلى البيانات في عنصر Bundle ولكن ليس لديه إذن الوصول إلى الفئة المجزّأة أو المتسلسلة، يُنشئ النظام سوى RuntimeException.

العلامات

يتمّ تحديد العلامات في فئة Intent التي تعمل كبيانات وصفية لهدف. قد تُعلِم الإشارات نظام Android بكيفية تشغيل نشاط معيّن (على سبيل المثال، تحديد المهمة التي يجب أن ينتمي إليها ) وكيفية التعامل معه بعد تشغيله (على سبيل المثال، ما إذا كان ينتمي إلى قائمة الأنشطة الأخيرة).

لمزيد من المعلومات، يُرجى الاطّلاع على طريقة setFlags().

مثال على نية صريحة

القصد الصريح هو القصد الذي تستخدمه لتشغيل مكوّن تطبيق معيّن، مثل نشاط أو خدمة معيّنة في تطبيقك. لإنشاء قصد صريح، حدِّد اسم المكوّن لعنصر Intent، وتكون كل سمات القصد الأخرى اختيارية.

على سبيل المثال، إذا أنشأت خدمة في تطبيقك باسم DownloadService مصمّمة لتنزيل ملف من الويب، يمكنك تشغيلها باستخدام الرمز البرمجي التالي:

Kotlin

// Executed in an Activity, so 'this' is the Context
// The fileUrl is a string URL, such as "http://www.example.com/image.png"
val downloadIntent = Intent(this, DownloadService::class.java).apply {
    data = Uri.parse(fileUrl)
}
startService(downloadIntent)

Java

// Executed in an Activity, so 'this' is the Context
// The fileUrl is a string URL, such as "http://www.example.com/image.png"
Intent downloadIntent = new Intent(this, DownloadService.class);
downloadIntent.setData(Uri.parse(fileUrl));
startService(downloadIntent);

يزوِّد Intent(Context, Class) المنشئ التطبيق Context والمكوّن بكائن Class. وبناءً على ذلك، يبدأ هذا القصد صراحةً فئة DownloadService في التطبيق.

لمزيد من المعلومات عن إنشاء خدمة وبدء تشغيلها، يُرجى الاطّلاع على دليل الخدمات.

مثال على النية الضمنية

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

على سبيل المثال، إذا كان لديك محتوى تريد من المستخدم مشاركته مع مستخدمين آخرين، أنشئ نية باستخدام الإجراء ACTION_SEND وأضِف عناصر إضافية تحدّد المحتوى المطلوب مشاركته. عند استدعاء startActivity() بهذه النية، يمكن للمستخدم اختيار تطبيق لمشاركة المحتوى من خلاله.

Kotlin

// Create the text message with a string.
val sendIntent = Intent().apply {
    action = Intent.ACTION_SEND
    putExtra(Intent.EXTRA_TEXT, textMessage)
    type = "text/plain"
}

// Try to invoke the intent.
try {
    startActivity(sendIntent)
} catch (e: ActivityNotFoundException) {
    // Define what your app should do if no activity can handle the intent.
}

Java

// Create the text message with a string.
Intent sendIntent = new Intent();
sendIntent.setAction(Intent.ACTION_SEND);
sendIntent.putExtra(Intent.EXTRA_TEXT, textMessage);
sendIntent.setType("text/plain");

// Try to invoke the intent.
try {
    startActivity(sendIntent);
} catch (ActivityNotFoundException e) {
    // Define what your app should do if no activity can handle the intent.
}

عند استدعاء startActivity()، يفحص النظام جميع التطبيقات المثبَّتة لتحديد التطبيقات التي يمكنها معالجة هذا النوع من النية (نية تتضمّن الإجراء ACTION_SEND وتحمل بيانات "text/plain" ). إذا كان هناك تطبيق واحد فقط يمكنه معالجة الطلب، سيتم فتح هذا التطبيق على الفور وسيتم منحه الهدف. إذا لم تتمكّن أي تطبيقات أخرى من معالجة ذلك، يمكن لتطبيقك رصد ActivityNotFoundException التي تحدث. إذا كانت أنشطة متعددة تقبل النية، يُظهِر النظام مربع حوار مثل المعروض في الشكل 2، حتى يتمكّن المستخدم من اختيار التطبيق الذي يريد استخدامه.

يمكنك أيضًا الاطّلاع على مزيد من المعلومات حول تشغيل تطبيقات أخرى في الدليل المتعلّق بإرسال المستخدم إلى تطبيق آخر.

الشكل 2: مربّع حوار اختيار

فرض أداة اختيار التطبيقات

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

ومع ذلك، إذا كان بإمكان تطبيقات متعددة الاستجابة لطلب التشغيل وقد يريد المستخدم استخدام تطبيق مختلف في كل مرة، يجب عرض مربّع حوار اختيار بشكل صريح. يطلب مربّع الحوار من الناشر تحديد التطبيق الذي يريد استخدامه لتنفيذ الإجراء (لا يمكنه اختيار تطبيق تلقائي لتنفيذ الإجراء). على سبيل المثال، عندما ينفِّذ تطبيقك إجراء "المشاركة" باستخدام الإجراء ACTION_SEND، قد يريد المستخدمون المشاركة باستخدام تطبيق مختلف استنادًا إلى حالتهم الحالية، لذا عليك استخدام مربّع حوار أداة الاختيار دائمًا، كما هو موضّح في الشكل 2.

لعرض أداة الاختيار، أنشئ Intent باستخدام createChooser() ونقلها إلى startActivity()، كما هو موضّح في المثال التالي. يعرض هذا المثال مربّع حوار يتضمّن قائمة بالتطبيقات التي تستجيب للintent الذي تم تمريره إلى الطريقة createChooser()، ويستخدم النص المقدَّم كعنوان للمربّع الحوار.

Kotlin

val sendIntent = Intent(Intent.ACTION_SEND)
...

// Always use string resources for UI text.
// This says something like "Share this photo with"
val title: String = resources.getString(R.string.chooser_title)
// Create intent to show the chooser dialog
val chooser: Intent = Intent.createChooser(sendIntent, title)

// Verify the original intent will resolve to at least one activity
if (sendIntent.resolveActivity(packageManager) != null) {
    startActivity(chooser)
}

Java

Intent sendIntent = new Intent(Intent.ACTION_SEND);
...

// Always use string resources for UI text.
// This says something like "Share this photo with"
String title = getResources().getString(R.string.chooser_title);
// Create intent to show the chooser dialog
Intent chooser = Intent.createChooser(sendIntent, title);

// Verify the original intent will resolve to at least one activity
if (sendIntent.resolveActivity(getPackageManager()) != null) {
    startActivity(chooser);
}

رصد عمليات بدء التطبيقات غير الآمنة

قد يطلق تطبيقك أهدافًا للتنقّل بين المكوّنات داخل تطبيقك، أو لتنفيذ إجراء نيابةً عن تطبيق آخر. لتحسين أمان النظام الأساسي، يوفّر نظام التشغيل Android 12 (المستوى 31 من واجهة برمجة التطبيقات) والإصدارات الأحدث ميزة تصحيح الأخطاء التي تحذرك إذا كان تطبيقك يُجري عملية إطلاق غير آمنة لهدف. على سبيل المثال، قد يؤدي تطبيقك إلى إجراء عملية إطلاق غير آمنة لرسالة غرض مُدمَجة، وهي رسالة غرض يتم تمريرها كإضافة في رسالة غرض أخرى.

إذا نفَّذ تطبيقك كلا الإجراءَين التاليَين، يرصد النظام عملية إطلاق intent غير آمنة، ويحدث انتهاك StrictMode:

1. يُفكّ تطبيقك حزمة هدف مُدمَج من البيانات الإضافية لهدف تم إرساله.
2. يبدأ تطبيقك على الفور أحد مكونات التطبيق باستخدام هذا الإجراء المتداخل، مثل تمرير الإجراء إلى startActivity() أو startService() أو bindService().

لمزيد من التفاصيل حول كيفية تحديد هذا الموقف وإجراء تغييرات على تطبيقك، يُرجى قراءة مشاركة المدوّنة حول تداخل طلبات Android على Medium.

التحقّق من عمليات إطلاق المقاصد غير الآمنة

للتحقّق من عمليات إطلاق النوايا غير الآمنة في تطبيقك، يمكنك استدعاء detectUnsafeIntentLaunch() عند ضبط VmPolicy، كما هو موضّح في مقتطف الرمز البرمجي التالي. إذا رصد تطبيقك انتهاكًا لـ StrictMode، ننصحك بإيقاف تنفيذ التطبيق بهدف حماية المعلومات الحسّاسة المحتملة.

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

Kotlin

fun onCreate() {
    StrictMode.setVmPolicy(VmPolicy.Builder()
        // Other StrictMode checks that you've previously added.
        // ...
        .detectUnsafeIntentLaunch()
        .penaltyLog()
        // Consider also adding penaltyDeath()
        .build())
}

Java

protected void onCreate() {
    StrictMode.setVmPolicy(new VmPolicy.Builder()
        // Other StrictMode checks that you've previously added.
        // ...
        .detectUnsafeIntentLaunch()
        .penaltyLog()
        // Consider also adding penaltyDeath()
        .build());
}

استخدام النوايا بشكل أكثر مسؤولية

لتقليل احتمالية إطلاق نية غير آمنة وانتهاك StrictMode، اتّبِع أفضل الممارسات التالية.

انسخ الإضافات الأساسية فقط ضمن النوايا، ونفِّذ أي عمليات تنظيف وتحقّق ضرورية. قد ينسخ تطبيقك البيانات الإضافية من نية إلى نية أخرى تُستخدَم لإطلاق مكوّن جديد. يحدث ذلك عندما يُطلِق تطبيقك طلبات إلى putExtras(Intent) أو putExtras(Bundle). إذا كان تطبيقك ينفّذ إحدى هذه العمليات، يجب نسخ الإضافات التي يتوقعها العنصر المُستلِم فقط. إذا كان الغرض الآخر (الذي يتلقّى النسخة) يشغّل مكوّنًا لم يتم تصديره، عليك إزالة البيانات غير الصالحة من ملف extras و التحقّق منه قبل نسخه إلى الغرض الذي يشغّل المكوّن.

لا تصدِّر مكوّنات تطبيقك بدون داعٍ. على سبيل المثال، إذا كان العميل ينوي إطلاق مكوّن تطبيق باستخدام هدف مُدمَج داخلي، يجب ضبط سمة android:exported الخاصة بهذا المكوّن على false.

استخدِم PendingIntent بدلاً من نية متداخلة. بهذه الطريقة، عندما يفكك تطبيق آخر حِزمة PendingIntent من Intent التي يحتوي عليها، يمكن للتطبيق الآخر تشغيل PendingIntent باستخدام هوية تطبيقك. ويسمح هذا الإعداد للتطبيق الآخر بتشغيل أي مكوّن بأمان في تطبيقك، بما في ذلك المكوّن الذي لم يتم تصديره.

يوضِّح المخطّط البياني في الشكل 2 كيفية نقل النظام التحكّم من تطبيقك (العميل) إلى تطبيق آخر (خدمة)، ثمّ إعادته إلى تطبيقك:

1. ينشئ تطبيقك رسالة Intent تستدعي نشاطًا في تطبيق آخر. ضمن هذه الرسالة، يمكنك إضافة عنصر PendingIntent كعنصر إضافي. يُستخدَم هذا الإجراء المعلّق لتشغيل مكوّن في تطبيقك، ولا يتم تصدير هذا المكوّن.
2. عند تلقّي طلب تطبيقك، يستخرج التطبيق الآخر العنصر المُدمَج PendingIntent.
3. يستدعي التطبيق الآخر الطريقة send() على عنصر PendingIntent.
4. بعد إعادة التحكّم إلى تطبيقك، يستدعي النظام المحاولة التي في انتظار المراجعة باستخدام سياق تطبيقك.

الشكل 2: مخطّط بياني للتواصل بين التطبيقات عند استخدام قيد ملف شخصي مُدمج

تلقّي نية ضمنية

للإعلان عن الأهداف الضمنية التي يمكن لتطبيقك تلقّيها، حدِّد فلتر هدف واحدًا أو أكثر لكل مكوّن من مكوّنات تطبيقك باستخدام عنصر <intent-filter> في ملف البيان. يحدِّد كل فلتر أهداف نوع الأهداف التي يقبلها استنادًا إلى إجراء الهدف وبياناته وفئتَه. لا يرسل النظام نية ضمنية إلى مكوّن تطبيقك إلا إذا كان بالإمكان تمرير النيّة من خلال أحد فلاتر النيّات.

ملاحظة: يتم دائمًا إرسال هدف صريح إلى هدفه، بغض النظر عن أي فلاتر أهداف يعلن عنها المكوّن.

يجب أن يعلن مكوّن التطبيق عن فلاتر منفصلة لكل مهمة فريدة يمكنه تنفيذها. على سبيل المثال، قد يتضمّن نشاط واحد في تطبيق معرض الصور فلترَين: فلتر لعرض صورة، وفلتر آخر لتعديل صورة. عند بدء النشاط، يفحص Intent ويقرر كيفية التصرف استنادًا إلى المعلومات في Intent (مثل عرض عناصر التحكّم في المحرِّر أو عدم عرضها).

يتم تعريف كل فلتر أهداف باستخدام عنصر <intent-filter> في ملف بيان التطبيق، ويتم إدراجه في مكوّن التطبيق المقابل (مثل عنصر <activity> ).

في كل مكوّن تطبيق يتضمّن عنصر <intent-filter>، حدِّد قيمة android:exported صراحةً. تشير هذه السمة إلى ما إذا كان بإمكان التطبيقات الأخرى الوصول إلى مكوّن التطبيق. في بعض الحالات، مثل الأنشطة التي تتضمّن فلاتر أهدافها فئة LAUNCHER ، من المفيد ضبط هذه السمة على true. وبخلاف ذلك، من الأفضل ضبط هذه السمة على false.

تحذير: إذا كان النشاط أو الخدمة أو android:exported المستلِم في تطبيقك يستخدم فلاتر الأهداف ولا يضبط القيمة لـ android:exported بشكل صريح، لا يمكن تثبيت تطبيقك على جهاز يعمل بنظام التشغيل Android 12 أو إصدار أحدث.

داخل <intent-filter>، يمكنك تحديد نوع النوايا المراد قبولها باستخدام واحد أو أكثر من هذه العناصر الثلاثة:

<action>

يُعلن عن قبول إجراء النية في السمة name. يجب أن تكون القيمة هي القيمة الحرفية للسلسلة الخاصة بإجراء معيّن، وليس القيمة الثابتة للفئة.

<data>

يُستخدَم لتعريف نوع البيانات المقبولة، باستخدام سمة واحدة أو أكثر تحدد جوانب مختلفة من معرّف URI للبيانات (scheme وhost وport path) ونوع MIME.

<category>

يُعلن عن قبول فئة الغرض في السمة name. يجب أن تكون القيمة هي القيمة الحرفية للسلسلة الخاصة بإجراء معيّن، وليس القيمة الثابتة للفئة.

ملاحظة: لتلقّي النوايا الضمنية، عليك تضمين فئة CATEGORY_DEFAULT في فلتر النوايا. تتعامل الطريقتان startActivity() و startActivityForResult() مع جميع النوايا كما لو أنّهما أعلنتا عن الفئة CATEGORY_DEFAULT. إذا لم تحدِّد هذه الفئة في فلتر الأهداف، لن يتم تحويل أي أهداف ضمنية إلى نشاطك.

على سبيل المثال، إليك بيان نشاط يتضمّن فلتر نية لتلقّي نية ACTION_SEND عندما يكون نوع البيانات نصًا:

<activity android:name="ShareActivity" android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
</activity>

يمكنك إنشاء فلتر يتضمّن أكثر من مثيل واحد من <action> أو <data> أو <category>. وفي حال فعلت ذلك، يجب التأكّد من أنّ المكوّن يمكنه التعامل مع أي تركيبة من تركيبات عناصر الفلتر هذه.

عندما تريد التعامل مع أنواع متعدّدة من النوايا، ولكن في مجموعات محدّدة فقط من نوع الإجراء والبيانات والفئة، عليك إنشاء فلاتر متعددة للنوايا.

يتم اختبار النية الضمنية مقابل فلتر من خلال مقارنة النية بكل من العناصر الثلاثة. لكي يتم إرسال النية إلى المكوّن، يجب أن تجتاز النية جميع الاختبارات الثلاثة. وفي حال تعذّر مطابقة أيٍّ منها، لن يرسل نظام Android النية إلى الادخال. ومع ذلك، بما أنّ المكوّن قد يحتوي على فلاتر متعددة للنوايا، قد يتمكّن أحد الفلاتر من السماح بمرور نية لا تَجتاز أحد فلاتر المكوّن. يمكنك الاطّلاع على مزيد من المعلومات حول كيفية حلّ النظام للنوايا في القسم أدناه المتعلقبحلّ النوايا.

تحذير: لا يُعدّ استخدام فلتر الأهداف طريقة آمنة لمنع التطبيقات الأخرى من بدء مكوناتك. على الرغم من أنّ فلاتر ملفات Intent تحدّ من استجابة المكوّن لأنواع معيّنة فقط من ملفات Intent الضمنية، يمكن لتطبيق آخر بدء مكوّن تطبيقك باستخدام ملف Intent صريح إذا حدّد المطوّر أسماء المكوّنات. إذا كان من المهم أن يتمكّن تطبيقك فقط من بدء أحد مكوّناتك، يجب عدم الإفصاح عن فلاتر الأهداف في البيان. بدلاً من ذلك، اضبط سمة exported على "false" لهذا المكوّن.

وبالمثل، لتجنُّب تشغيل Service لتطبيق مختلف عن طريق الخطأ، استخدِم دائمًا نية صريحة لبدء خدمتك الخاصة.

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

أمثلة على الفلاتر

لتوضيح بعض سلوكيات فلاتر الأهداف، إليك مثال من ملف بيان تطبيق لمشاركة المحتوى على الشبكات الاجتماعية:

<activity android:name="MainActivity" android:exported="true">
    <!-- This activity is the main entry, should appear in app launcher -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

<activity android:name="ShareActivity" android:exported="false">
    <!-- This activity handles "SEND" actions with text data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
    <!-- This activity also handles "SEND" and "SEND_MULTIPLE" with media data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <action android:name="android.intent.action.SEND_MULTIPLE"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="application/vnd.google.panorama360+jpg"/>
        <data android:mimeType="image/*"/>
        <data android:mimeType="video/*"/>
    </intent-filter>
</activity>

النشاط الأول، MainActivity، هو نقطة الدخول الرئيسية للتطبيق، أي النشاط الذي يفتح عندما يشغّل المستخدم التطبيق في البداية باستخدام رمز مشغّل التطبيقات:

• يشير الإجراء ACTION_MAIN إلى أنّ هذه هي نقطة الدخول الرئيسية ولا تتوقّع أي بيانات نية.
• تشير فئة CATEGORY_LAUNCHER إلى أنّه يجب وضع رمز هذا النشاط في مشغّل التطبيقات في النظام. إذا لم يحدّد عنصر <activity> رمزًا باستخدام icon، سيستخدم النظام الرمز من عنصر <application>.

يجب إقران هذين العنصرَين معًا لكي يظهر النشاط في مشغّل التطبيقات.

يهدف النشاط الثاني، ShareActivity، إلى تسهيل مشاركة المحتوى النصي ومحتوى الوسائط. على الرغم من أنّ المستخدمين قد يدخلون إلى هذا النشاط من خلال الانتقال إليه من MainActivity، يمكنهم أيضًا الدخول إلى ShareActivity مباشرةً من تطبيق آخر يُصدر هدفًا ضمنيًا يتطابق مع أحد فلاتر الأهداف.

ملاحظة: نوع MIME، application/vnd.google.panorama360+jpg، هو نوع بيانات خاص يحدّد الصور البانورامية، والتي يمكنك التعامل معها باستخدام واجهات برمجة تطبيقات Google panorama.

مطابقة النوايا مع فلاتر أهداف التطبيقات الأخرى

إذا كان تطبيق آخر يستهدف الإصدار 13 من نظام التشغيل Android (المستوى 33 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، لا يمكنه معالجة نية تطبيقك إلا إذا كانت مطابقة للإجراءات والفئات الخاصة بعنصر <intent-filter> في هذا التطبيق الآخر. وإذا لم يعثر النظام على مطابقة، سيُرسِل ActivityNotFoundException. يجب أن يعالج التطبيق المُرسِل هذا الاستثناء.

وبالمثل، إذا عدّلت تطبيقك ليستهدف الإصدار Android 13 أو إصدارًا أحدث، لن يتم إرسال جميع النوايا الواردة من تطبيقات خارجية إلى ملف برمجي مصدَّر من تطبيقك إلا إذا كانت هذه النوايا تتطابق مع الإجراءات والفئات لعنصر <intent-filter> الذي يعلن عنه تطبيقك. ويحدث هذا السلوك بغض النظر عن إصدار حزمة SDK المستهدَف للتطبيق المُرسِل.

في الحالات التالية، لا يتم فرض مطابقة الأهداف:

• الأهداف التي يتم إرسالها إلى المكوّنات التي لا تذكر أي فلاتر أهداف
• النوايا التي تأتي من داخل التطبيق نفسه
• النوايا التي تأتي من النظام، أي النوايا التي يتم إرسالها من "معرّف مستخدم النظام" (uid=1000). تشمل تطبيقات النظام system_server والتطبيقات التي تضبط android:sharedUserId على android.uid.system.
• النوايا التي تأتي من الجذر

اطّلِع على مزيد من المعلومات عن مطابقة النية.

استخدام طلب في انتظار المراجعة

عنصر PendingIntent هو غلاف حول عنصر Intent. الغرض الأساسي من PendingIntent هو منح إذن لتطبيق أجنبي باستخدام Intent المضمّنة كما لو تم تنفيذها من عملية تطبيقك الخاصة.

تشمل حالات الاستخدام الرئيسية للنوايا المعلّقة ما يلي:

• تحديد نية التنفيذ عند اتّخاذ المستخدم إجراءً من خلال الإشعار (ينفِّذ NotificationManager في نظام Android الإجراء Intent).
• تحديد نية لتنفيذها عندما ينفِّذ المستخدم إجراءً باستخدام أداة التطبيق (ينفِّذ تطبيق الشاشة الرئيسية Intent).
• الإعلان عن نية تنفيذ في وقت مستقبلي محدّد (ينفّذ AlarmManager في نظام Android Intent).

تمامًا كما تم تصميم كل عنصر Intent ليتم التعامل معه من خلال نوع محدّد من مكونات التطبيق (إما Activity أو Service أو BroadcastReceiver)، يجب أيضًا إنشاء PendingIntent بالطريقة نفسها. عند استخدام نية في انتظار المراجعة، لا يؤدي تطبيقك إلى تنفيذ النية من خلال طلب مثل startActivity(). بدلاً من ذلك، عليك الإفصاح عن نوع المكوّن المقصود عند إنشاء PendingIntent من خلال استدعاء طريقة الإنشاء ذات الصلة:

• PendingIntent.getActivity() لمحاولة Intent تبدأ Activity
• PendingIntent.getService() لمحاولة Intent لبدء Service
• PendingIntent.getBroadcast() لمحاولة Intent لبدء BroadcastReceiver

ما لم يكن تطبيقك يتلقّى نوايا في انتظار المراجعة من تطبيقات أخرى، قد تكون الأساليب المذكورة أعلاه لإنشاء PendingIntent هي الوحيدة PendingIntent التي ستحتاج إليها.

تأخذ كل طريقة التطبيق الحالي Context وIntent الذي تريد تغليفه وعلامة واحدة أو أكثر تحدد كيفية استخدام النية (مثل ما إذا كان يمكن استخدام النية أكثر من مرة).

لمزيد من المعلومات عن استخدام النوايا المعلّقة، اطّلِع على مستندات كلٍّ من حالات الاستخدام ذات الصلة، مثل الإشعارات وتطبيقات التطبيقات المصغّرة في أدلة واجهة برمجة التطبيقات.

تحديد قابلية التغيير

إذا كان تطبيقك يستهدف الإصدار 12 من نظام التشغيل Android أو الإصدارات الأحدث، يجب تحديد قابلية التغيّر لكل عنصر من عناصر PendingIntent التي ينشئها تطبيقك. لتحديد أنّ كائن PendingIntent معيّن قابل للتغيير أو غير قابل للتغيير، استخدِم العلامة PendingIntent.FLAG_MUTABLE أو PendingIntent.FLAG_IMMUTABLE ، على التوالي.

إذا حاول تطبيقك إنشاء عنصر PendingIntent بدون ضبط أي علامة قابلية للتغيّر، يُرسِل النظام IllegalArgumentException، ويظهر النص التالي في Logcat:

PACKAGE_NAME: Targeting S+ (version 31 and above) requires that one of \
FLAG_IMMUTABLE or FLAG_MUTABLE be specified when creating a PendingIntent.

Strongly consider using FLAG_IMMUTABLE, only use FLAG_MUTABLE if \
some functionality depends on the PendingIntent being mutable, e.g. if \
it needs to be used with inline replies or bubbles.

أنشئ طلبات ثابتة في انتظار المراجعة كلما أمكن ذلك.

في معظم الحالات، يجب أن ينشئ تطبيقك عناصر PendingIntent غير قابلة للتغيير، كما هو موضح في مقتطف الرمز التالي. إذا كان عنصر PendingIntent غير قابل للتغيير، لا يمكن للتطبيقات الأخرى تعديل النية لتعديل نتيجة استدعاء النية.

Kotlin

val pendingIntent = PendingIntent.getActivity(applicationContext,
        REQUEST_CODE, intent,
        /* flags */ PendingIntent.FLAG_IMMUTABLE)

Java

PendingIntent pendingIntent = PendingIntent.getActivity(getApplicationContext(),
        REQUEST_CODE, intent,
        /* flags */ PendingIntent.FLAG_IMMUTABLE);

ومع ذلك، تتطلّب بعض حالات الاستخدام عناصر PendingIntent قابلة للتغيير بدلاً من ذلك:

• إتاحة إجراءات الردّ المباشر في الإشعارات يتطلب الردّ المباشر تغييرًا في بيانات المقطع في عنصر PendingIntent المرتبط بالردّ. وعادةً ما تطلب هذا التغيير من خلال تمرير FILL_IN_CLIP_DATA كعلامة إلى الأسلوب fillIn().
• ربط الإشعارات بإطار عمل Android Auto باستخدام مثيلات CarAppExtender
• وضع المحادثات في فقاعات باستخدام نُسخ من PendingIntent يسمح عنصر PendingIntent القابل للتغيير للنظام بتطبيق العلامات الصحيحة، مثل FLAG_ACTIVITY_MULTIPLE_TASK و FLAG_ACTIVITY_NEW_DOCUMENT.
• طلب معلومات عن الموقع الجغرافي للجهاز من خلال استدعاء واجهة برمجة التطبيقات requestLocationUpdates() أو واجهات برمجة تطبيقات مشابهة يسمح العنصر القابل للتغيير PendingIntent للنظام بإضافة إضافات الطلبات التي تمثّل أحداث دورة حياة الموقع الجغرافي. وتشمل هذه الأحداث تغييرًا في الموقع الجغرافي وظهور مقدّم خدمة.
• جدولة التنبيهات باستخدام AlarmManager يسمح عنصر PendingIntent القابل للتغيير للنظام بإضافة EXTRA_ALARM_COUNT intent extra. يمثّل هذا المقياس الإضافي عدد المرات التي تم فيها تشغيل المنبّه المتكرّر. ومن خلال تضمين هذه المعلومات الإضافية، يمكن للIntent إبلاغ التطبيق بدقة بشأن ما إذا تم تشغيل تنبيه متكرر عدة مرات، مثلاً عندما كان الجهاز في وضع السكون.

إذا كان تطبيقك ينشئ عنصر PendingIntent قابلاً للتغيير، ننصحك بشدّة باستخدام نية صريحة وملء الحقل ComponentName. بهذه الطريقة، كلما شغّل تطبيق آخر PendingIntent ونقل التحكّم مرة أخرى إلى تطبيقك، يبدأ المكوّن نفسه في تطبيقك دائمًا.

استخدام النوايا الصريحة ضمن النوايا التي في انتظار المراجعة

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

1. تأكَّد من إدخال قيمة في حقول الإجراء والحزمة والمكوِّن في رسالة Intent الأساسية.

2. استخدِم FLAG_IMMUTABLE، الذي تمت إضافته في الإصدار 6.0 من نظام التشغيل Android (المستوى 23 من واجهة برمجة التطبيقات)، لإنشاء نوايا في انتظار المراجعة. تمنع هذه العلامة التطبيقات التي تتلقّى PendingIntent من ملء الخصائص الفارغة. إذا كان minSdkVersion لتطبيقك هو 22 أو إصدارًا أقل، يمكنك توفير الأمان والتوافق معًا باستخدام الرمز التالي:

   if (Build.VERSION.SDK_INT >= 23) {
     // Create a PendingIntent using FLAG_IMMUTABLE.
   } else {
     // Existing code that creates a PendingIntent.
   }

حلّ النية

عندما يتلقّى النظام نية ضمنية لبدء نشاط، يبحث عن أفضل نشاط للنية من خلال مقارنته بفلاتر النيّات استنادًا إلى ثلاثة جوانب:

• تصوير.
• البيانات (معرّف URI ونوع البيانات)
• الفئة.

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

اختبار الإجراء

لتحديد إجراءات النوايا المقبولة، يمكن أن يُعلن فلتر الأهداف عن صفر أو أكثر من عناصر <action>، كما هو موضّح في المثال التالي:

<intent-filter>
    <action android:name="android.intent.action.EDIT" />
    <action android:name="android.intent.action.VIEW" />
    ...
</intent-filter>

لاجتياز هذا الفلتر، يجب أن يتطابق الإجراء المحدّد في Intent مع أحد الإجراءات المدرَجة في الفلتر.

إذا لم يُدرِج الفلتر أي إجراءات، لن يتطابق أي قصد، وبالتالي لن يجتاز جميع الأغراض الاختبار. ومع ذلك، إذا لم يحدِّد Intent إجراءً، يجتاز الاختبار ما دام الفلتر يحتوي على إجراء واحد على الأقل.

اختبار الفئة

لتحديد فئات الأهداف المقبولة، يمكن أن يعلن فلتر الأهداف عن صفر أو أكثر من عناصر <category>، كما هو موضّح في المثال التالي:

<intent-filter>
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    ...
</intent-filter>

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

ملاحظة: يطبّق Android تلقائيًا فئة CATEGORY_DEFAULT على جميع النوايا الضمنية التي يتم تمريرها إلى startActivity() وstartActivityForResult(). إذا كنت تريد أن يتلقّى نشاطك أهدافًا ضمنية، يجب أن يحتوي على فئة "android.intent.category.DEFAULT" في فلاتر الأهداف، كما هو موضّح في مثال <intent-filter> السابق.

اختبار البيانات

لتحديد بيانات النية المقبولة، يمكن أن يعلن فلتر النية عن صفر أو أكثر من عناصر <data>، كما هو موضّح في المثال التالي:

<intent-filter>
    <data android:mimeType="video/mpeg" android:scheme="http" ... />
    <data android:mimeType="audio/mpeg" android:scheme="http" ... />
    ...
</intent-filter>

يمكن لكل عنصر <data> تحديد بنية عنوان URL ونوع بيانات (نوع وسائط MIME). كل جزء من معرّف الموارد المنتظم هو سمة منفصلة: scheme وhost وport وpath:

<scheme>://<host>:<port>/<path>

يعرض المثال التالي القيم المحتملة لهذه السمات:

content://com.example.project:200/folder/subfolder/etc

في معرّف الموارد المنتظم هذا، يكون المخطّط هو content والمضيف هو com.example.project والمنفذ هو 200 والمسار هو folder/subfolder/etc.

كلّ من هذه السمات اختيارية في عنصر <data>، ولكن هناك تبعيات خطية:

• في حال عدم تحديد مخطّط، يتم تجاهل المضيف.
• في حال عدم تحديد مضيف، يتم تجاهل المنفذ.
• في حال عدم تحديد المخطّط والمضيف، يتم تجاهل المسار.

عند مقارنة معرّف الموارد المنتظم في طلب بحث مع مواصفات معرّف الموارد المنتظم في فلتر، تتم المقارنة فقط مع أجزاء معرّف الموارد المنتظم المضمّنة في الفلتر. مثلاً:

• إذا كان الفلتر يحدّد مخطّطًا فقط، تتطابق جميع معرّفات URI التي تستخدم هذا المخطّط مع الفلتر.
• إذا حدّد الفلتر مخطّطًا وهيئة ولكن بدون مسار، تمرّ جميع عناوين URL التي تتضمّن المخطّط والهيئة نفسها من الفلتر بغض النظر عن مساراتها.
• إذا حدّد الفلتر مخطّطًا وهيئة ومسارًا، لن تمرّ سوى عناوين URL التي تتضمّن المخطّط والهيئة والمسار نفسه.

ملاحظة: يمكن أن تحتوي مواصفات المسار على علامة النجمة (*) لطلب مطابقة جزئية فقط لاسم المسار.

يقارن اختبار البيانات كلاً من معرّف الموارد المنتظم (URI) ونوع MIME في الطلب مع معرّف موارد منتظم ونوع MIME محدّدَين في الفلتر. في ما يلي القواعد:

1. لا يجتاز الاختبار سوى النية التي لا تحتوي على معرّف موارد منتظم (URI) أو نوع MIME، وذلك فقط إذا لم يحدّد الفلتر أي معرّفات موارد منتظمة أو أنواع MIME.
2. لا يجتاز الاختبار إلا إذا كان معرّف الموارد المنتظم (URI) الخاص به يتطابق مع تنسيق معرّف الموارد المنتظم (URI) للفلتر ولم يحدّد الفلتر نوع MIME أيضًا.
3. لا يجتاز الاختبار سوى النية التي تحتوي على نوع MIME ولكن ليس بها عنوان URL، وذلك فقط إذا كان الفلتر يسرد نوع MIME نفسه ولا يحدّد تنسيق عنوان URL.
4. لا يجتاز الإجراء الذي يحتوي على معرّف موارد منتظم ونوع MIME (سواء كان صريحًا أو يمكن الاستدلال عليه من المعرّف) جزء نوع MIME من الاختبار إلا إذا كان هذا النوع يتطابق مع نوع مُدرَج في الفلتر. يجتاز الاختبار جزء معرّف الموارد المنتظم (URI) إما إذا كان معرّف الموارد المنتظم يتطابق مع معرّف موارد منتظم في الفلتر أو إذا كان يحتوي على معرّف موارد منتظم content: أو file: ولم يحدّد الفلتر معرّف موارد منتظمًا. بعبارة أخرى، يُفترض أنّ المكوّن متوافق مع بيانات content: وfile: إذا كانت قائمة الفلتر تتضمّن نوع MIME فقط.

ملاحظة: إذا حدّد الغرض معرّف موارد منتظم (URI) أو نوع MIME، سيتعذّر اختبار البيانات في حال عدم توفّر عناصر <data> في <intent-filter>.

تعكس هذه القاعدة الأخيرة (د) التوقّع بأنّه يمكن للمكونات الحصول على بيانات محلية من ملف أو مقدّم محتوى. وبالتالي، يمكن أن تُدرِج فلاترها نوع بيانات فقط ولا تحتاج إلى تحديد اسم content: وfile: بشكل صريح. يعرض المثال التالي حالة نموذجية يُعلم فيها عنصر <data> نظام التشغيل Android بأنّ المكوّن يمكنه الحصول على بيانات الصور من مقدّم محتوى وعرضه:

<intent-filter>
    <data android:mimeType="image/*" />
    ...
</intent-filter>

إنّ الفلاتر التي تحديد نوع البيانات ولكن ليس عنوان URL هي الأكثر شيوعًا لأنّ معظم البيانات المتاحة يتم توزيعها من قِبل مقدّمي المحتوى.

من الإعدادات الشائعة الأخرى فلتر يحتوي على مخطّط ونوع بيانات. على سبيل المثال، يُعلم عنصر <data> الخاص بنظام التشغيل Android بأنّه يمكن للمكوّن استرداد بيانات الفيديو من الشبكة لتنفيذ الإجراء:

<intent-filter>
    <data android:scheme="http" android:mimeType="video/*" />
    ...
</intent-filter>

مطابقة النية

تتم مطابقة النوايا مع فلاتر النوايا ليس فقط لاكتشاف المكوّن المستهدف لتفعيله، ولكن أيضًا لاكتشاف معلومات عن مجموعة المكوّنات على الجهاز. على سبيل المثال، يعبئ تطبيق Home مشغّل التطبيقات من خلال العثور على جميع الأنشطة التي تتضمّن فلاتر أهداف تحدّد ACTION_MAIN الإجراء و CATEGORY_LAUNCHER الفئة. لا تنجح المطابقة إلا إذا كانت الإجراءات والفئات في "الهدف" متطابقة مع الفلتر، كما هو موضّح في مستندات فئة IntentFilter.

يمكن لتطبيقك استخدام ميزة مطابقة النوايا بطريقة مشابهة لطريقة تطبيق Home. يحتوي PackageManager على مجموعة من query...() methods التي تعرض جميع المكوّنات التي يمكنها قبول نية معيّنة، وسلسلة مماثلة من طرق resolve...() التي تحدّد أفضل مكوّن للردّ على نية معيّنة. على سبيل المثال، تعرِض دالة queryIntentActivities() قائمة بجميع الأنشطة التي يمكنها تنفيذ النيّة التي تم تمريرها كوسيطة، وتعرِض دالة queryIntentServices() قائمة مشابهة بالخدمات. ولا تؤدي أي من الطريقتَين إلى تفعيل المكوّنات، بل تُدرج فقط المكوّنات التي يمكنها الاستجابة. هناك طريقة مشابهة، queryBroadcastReceivers()، لمستقبِلات البث.