تلبية حالات الاستخدام الشائعة مع توفُّر إمكانية رؤية محدودة للحزمة

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

عندما يستخدِم أحد التطبيقات التي تستهدف الإصدار 11 من نظام التشغيل Android أو الإصدارات الأحدث نيةً لإجراء ما يلي: وبدء نشاط في تطبيق آخر، فإن النهج الأكثر سهولة هو استدعاء النية والتعامل مع ActivityNotFoundException باستثناء في حالة عدم توفر أي تطبيق.

إذا كان جزء من تطبيقك يعتمد على معرفة ما إذا كانت المكالمة startActivity() أن تنجح، مثل عرض واجهة مستخدم، أو إضافة عنصر إلى العنصر <queries> في تطبيقك البيان. ويكون ذلك عادةً عنصر <intent>.

عناوين URL المفتوحة

يوضّح هذا القسم طرقًا مختلفة لفتح عناوين URL في تطبيق يستهدف الإصدار 11 من نظام التشغيل Android أو إصدار أحدث

فتح عناوين URL في متصفّح أو تطبيق آخر

لفتح عنوان URL، استخدِم هدفًا يحتوي على ACTION_VIEW الإجراء المطلوب، مثل كما هو موضح في دليل تحميل موقع ويب عنوان URL. بعد الاتصال بـ startActivity() باستخدام هذا الغرض، يحدث أحد ما يلي:

  • يتم فتح عنوان URL في تطبيق متصفّح ويب.
  • يتم فتح عنوان URL في تطبيق يتوافق مع عنوان URL كصفحة لصفحة في التطبيق. .
  • يظهر مربّع حوار توضيحي يتيح للمستخدم اختيار التطبيق. لفتح عنوان URL.

  • تحدث ActivityNotFoundException بسبب عدم توفّر تطبيق مثبّت على الجهاز يمكنه فتح عنوان URL. (هذا أمر غير عادي).

    ننصحك بأن يرصد تطبيقك خطأ ActivityNotFoundException ويعالجه في حال حدوثه.

بما أنّ طريقة startActivity() لا تتطلّب إذن الوصول إلى الحزمة لبدء نشاط تطبيق آخر، ليس عليك إضافة عنصر <queries> إلى ملف بيان تطبيقك أو إجراء أي تغييرات على عنصر <queries> حالي. وينطبق ذلك على كلّ من الأهداف الضمنية والصريحة التي تفتح عنوان URL.

التحقُّق من توفُّر متصفِّح

في بعض الحالات، قد يحتاج تطبيقك إلى التأكّد من توفُّر متصفّح واحد على الأقل. متاحة على الجهاز، أو أن متصفحًا معينًا هو المتصفح الافتراضي، قبل محاولة فتح عنوان URL. في هذه الحالات، أدرِج العنصر التالي <intent> كجزء من العنصر <queries> في البيان:

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" />
</intent>

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

فتح عناوين URL في علامات تبويب مخصَّصة

تتيح علامات التبويب المخصصة على تخصيص شكل المتصفح وأسلوبه. يمكنك فتح عنوان URL في علامة تبويب مخصّصة بدون الحاجة إلى إضافة عنصر <queries> أو تغييره في بيان تطبيقك.

ومع ذلك، ننصحك بالتحقّق مما إذا كان الجهاز مزوّدًا بمتصفّح متوافق. علامات التبويب المخصَّصة أو اختيار متصفّح محدّد لتشغيله باستخدام "علامات التبويب المخصّصة" (Custom Tabs) باستخدام CustomTabsClient.getPackageName() في هذه الحالات، أدرِج العنصر <intent> التالي كجزء من العنصر <queries> في البيان:

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.support.customtabs.action.CustomTabsService" />
</intent>

السماح للتطبيقات التي لا تستخدم متصفّحًا بالتعامل مع عناوين URL

حتى إذا كان بإمكان تطبيقك فتح عناوين URL باستخدام علامات التبويب المخصَّصة، ننصحك السماح لتطبيق بدون متصفح بفتح عنوان URL إن أمكن لتوفير هذه المعلومات، في تطبيقك، يُرجى محاولة الاتصال بالرقم startActivity() باستخدام إجراء. التي تحدد FLAG_ACTIVITY_REQUIRE_NON_BROWSER علامة intent. إذا أظهر النظام رمز ActivityNotFoundException، يمكن لتطبيقك فتح عنوان URL في علامة تبويب مخصّصة.

إذا تضمّن الغرض هذه العلامة، يؤدّي استدعاء startActivity() إلى حدوث يتم طرح ActivityNotFoundException في إحدى الحالتَين التاليتَين الحالات التالية:

  • كان من الممكن أن تؤدي المكالمة إلى تشغيل تطبيق المتصفح مباشرةً.
  • ستعرض المكالمة للمستخدم مربع حوار توضيحي حيث هي تطبيقات المتصفح.

يوضح مقتطف الرمز التالي كيفية تعديل منطقك لاستخدام علامة هدف واحدة (FLAG_ACTIVITY_REQUIRE_NON_BROWSER):

Kotlin

try {
    val intent = Intent(ACTION_VIEW, Uri.parse(url)).apply {
        // The URL should either launch directly in a non-browser app (if it's
        // the default) or in the disambiguation dialog.
        addCategory(CATEGORY_BROWSABLE)
        flags = FLAG_ACTIVITY_NEW_TASK or FLAG_ACTIVITY_REQUIRE_NON_BROWSER
    }
    startActivity(intent)
} catch (e: ActivityNotFoundException) {
    // Only browser apps are available, or a browser is the default.
    // So you can open the URL directly in your app, for example in a
    // Custom Tab.
    openInCustomTabs(url)
}

Java

try {
    Intent intent = new Intent(ACTION_VIEW, Uri.parse(url));
    // The URL should either launch directly in a non-browser app (if it's the
    // default) or in the disambiguation dialog.
    intent.addCategory(CATEGORY_BROWSABLE);
    intent.setFlags(FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_REQUIRE_NON_BROWSER);
    startActivity(intent);
} catch (ActivityNotFoundException e) {
    // Only browser apps are available, or a browser is the default.
    // So you can open the URL directly in your app, for example in a
    // Custom Tab.
    openInCustomTabs(url);
}

تجنب مربع حوار توضيحي

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

إذا كان أحد الأهداف يتضمّن هذا العلامة، يؤدي طلب startActivity() إلى طرح ActivityNotFoundException عندما كان الطلب سيعرض مربّع حوار لإزالة الالتباس للمستخدم.

إذا كان الإجراء يحتوي على هذه العلامة وعلامة الإجراء FLAG_ACTIVITY_REQUIRE_NON_BROWSER ، يؤدي طلب startActivity() إلى طرح ActivityNotFoundException عند حدوث أيٍّ من الشروط التالية:

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

يوضّح المقتطف البرمجي التالي كيفية استخدام العلامتَين FLAG_ACTIVITY_REQUIRE_NON_BROWSER وFLAG_ACTIVITY_REQUIRE_DEFAULT معًا:

Kotlin

val url = URL_TO_LOAD
try {
    // For this intent to be invoked, the system must directly launch a
    // non-browser app.
    val intent = Intent(ACTION_VIEW, Uri.parse(url)).apply {
        addCategory(CATEGORY_BROWSABLE)
        flags = FLAG_ACTIVITY_NEW_TASK or FLAG_ACTIVITY_REQUIRE_NON_BROWSER or
                FLAG_ACTIVITY_REQUIRE_DEFAULT
    }
    startActivity(intent)
} catch (e: ActivityNotFoundException) {
    // This code executes in one of the following cases:
    // 1. Only browser apps can handle the intent.
    // 2. The user has set a browser app as the default app.
    // 3. The user hasn't set any app as the default for handling this URL.
    openInCustomTabs(url)
}

Java

String url = URL_TO_LOAD;
try {
    // For this intent to be invoked, the system must directly launch a
    // non-browser app.
    Intent intent = new Intent(ACTION_VIEW, Uri.parse(url));
    intent.addCategory(CATEGORY_BROWSABLE);
    intent.setFlags(FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_REQUIRE_NON_BROWSER |
            FLAG_ACTIVITY_REQUIRE_DEFAULT);
    startActivity(intent);
} catch (ActivityNotFoundException e) {
    // This code executes in one of the following cases:
    // 1. Only browser apps can handle the intent.
    // 2. The user has set a browser app as the default app.
    // 3. The user hasn't set any app as the default for handling this URL.
    openInCustomTabs(url);
}

فتح ملف

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

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

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.intent.action.VIEW" />
  <!-- If you don't know the MIME type in advance, set "mimeType" to "*/*". -->
  <data android:mimeType="application/pdf" />
</intent>

يمكنك بعد ذلك التحقّق ممّا إذا كان التطبيق متاحًا من خلال الاتصال على الرقم resolveActivity(). في تحقيق هدفك.

منح إذن الوصول إلى عنوان URL

ملاحظة: تعريف أذونات الوصول إلى عنوان URI كما هو موضّح في هذا القسم مطلوبة للتطبيقات التي تستهدف Android 11 (المستوى 30 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث ننصح به لجميع التطبيقات، بغض النظر عن إصدار حزمة تطوير البرامج (SDK) المستهدَف وما إذا كان الجهة التي تُصدِّرها موفّري المحتوى التابعين لهم.

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

في نظام التشغيل Android 11 والإصدارات الأحدث، تمنح أذونات الوصول إلى معرّف الموارد المنتظم (URI) الإمكانات التالية للتطبيق الذي يتلقّى الغرض:

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

يوضح مقتطف الرمز التالي كيفية إضافة علامة intent لأذونات معرّف الموارد المنتظم (URI). لكي يتمكّن تطبيق آخر يستهدف الإصدار 11 من نظام التشغيل Android أو الإصدارات الأحدث من عرض البيانات في معرف الموارد المنتظم للمحتوى:

Kotlin

val shareIntent = Intent(Intent.ACTION_VIEW).apply {
    flags = Intent.FLAG_GRANT_READ_URI_PERMISSION
    data = CONTENT_URI_TO_SHARE_WITH_OTHER_APP
}

Java

Intent shareIntent = new Intent(Intent.ACTION_VIEW);
shareIntent.setFlags(FLAG_GRANT_READ_URI_PERMISSION);
shareIntent.setData(CONTENT_URI_TO_SHARE_WITH_OTHER_APP);

الربط بالخدمات

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

الربط بمحرك لتحويل النص إلى كلام

إذا كان تطبيقك يتفاعل مع محرك لتحويل النص إلى كلام، يجب تضمين ما يلي: العنصر <intent> كجزء من العنصر <queries> في البيان:

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.intent.action.TTS_SERVICE" />
</intent>

الاتصال بخدمة التعرّف على الكلام

إذا كان تطبيقك يتفاعل مع خدمة التعرّف على الكلام، أدرِج العنصر التالي <intent> كجزء من العنصر <queries> في البيان:

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.speech.RecognitionService" />
</intent>

الاتصال بخدمات متصفّح الوسائط

إذا كان تطبيقك متصفّح وسائط العميل ، أدرِج العنصر <intent> التالي كجزء من العنصر <queries> في بيان التطبيق:

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.media.browse.MediaBrowserService" />
</intent>

توفير وظائف مخصصة

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

طلب البحث عن تطبيقات الرسائل القصيرة

إذا كان تطبيقك يحتاج إلى معلومات حول مجموعة تطبيقات الرسائل القصيرة (SMS) المثبَّتة على الجهاز، على سبيل المثال للتحقّق من التطبيق الذي يُعد معالِج الرسائل القصيرة SMS التلقائي على الجهاز، تضمين العنصر <intent> التالي كجزء من العنصر <queries> في في بيان التطبيق:

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.intent.action.SENDTO"/>
  <data android:scheme="smsto" android:host="*" />
</intent>

إنشاء ورقة مشاركة مخصّصة

استخدِم القيمة التي يقدّمها النظام قائمة مشاركة البيانات. بدلاً من ذلك، تضمين العنصر <intent> التالي كجزء من العنصر <queries> في في بيان التطبيق:

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.intent.action.SEND" />
  <!-- Replace with the MIME type that your app works with, if needed. -->
  <data android:mimeType="image/jpeg" />
</intent>

أما عملية إنشاء جدول المشاركة في منطق تطبيقك، مثل طلب queryIntentActivities()، فلا تتغيّر مقارنةً بإصدارات Android الأقدم من Android 11.

إظهار إجراءات تحديد النص المخصّص

عندما يحدّد المستخدمون نصًا في تطبيقك، ستظهر عبارة اختيار نص. شريط الأدوات تعرض مجموعة العمليات المحتملة التي يمكن إجراؤها على النص المحدد. إذا كان هذا يعرض شريط الأدوات الإجراءات المخصّصة من التطبيقات الأخرى، ما يلي: العنصر <intent> كجزء من العنصر <queries> في البيان:

<!-- Place inside the <queries> element. -->
<intent>
  <action android:name="android.intent.action.PROCESS_TEXT" />
  <data android:mimeType="text/plain" />
</intent>

إظهار صفوف البيانات المخصّصة لجهة اتصال

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

  1. اقرأ ملف contacts.xml من التطبيقات الأخرى.
  2. حمِّل رمزًا يتوافق مع نوع MIME المخصّص.

إذا كان تطبيقك تطبيق جهات اتصال، أدرِج عناصر <intent> التالية كجزء من عنصر <queries> في البيان:

<!-- Place inside the <queries> element. -->
<!-- Lets the app read the contacts.xml file from other apps. -->
<intent>
  <action android:name="android.accounts.AccountAuthenticator" />
</intent>
<!-- Lets the app load an icon corresponding to the custom MIME type. -->
<intent>
  <action android:name="android.intent.action.VIEW" />
  <data android:scheme="content" android:host="com.android.contacts"
        android:mimeType="vnd.android.cursor.item/*" />
</intent>
السابق
تقديم بيان إذن الوصول إلى الحزمة
التالي
اختبار إذن الوصول إلى الحِزم