موارد استفاده متداول را در حالی که دید بسته محدودی دارید انجام دهید

این سند چندین مورد استفاده متداول را ارائه می‌کند که در آن یک برنامه با برنامه‌های دیگر تعامل دارد. هر بخش راهنمایی هایی در مورد نحوه انجام عملکرد برنامه با قابلیت مشاهده بسته محدود ارائه می دهد، که اگر برنامه شما Android 11 (سطح API 30) یا بالاتر را هدف قرار می دهد، باید در نظر بگیرید.

هنگامی که برنامه‌ای که اندروید 11 یا بالاتر را هدف قرار می‌دهد از یک هدف برای شروع فعالیت در برنامه دیگری استفاده می‌کند، ساده‌ترین رویکرد این است که در صورت عدم وجود برنامه، این هدف را فراخوانی کنید و استثناء ActivityNotFoundException را مدیریت کنید.

اگر بخشی از برنامه شما به دانستن اینکه آیا فراخوانی startActivity() می تواند موفق باشد، مانند نشان دادن یک رابط کاربری، بستگی دارد، یک عنصر به عنصر <queries> مانیفست برنامه خود اضافه کنید. به طور معمول، این یک عنصر <intent> است.

URL ها را باز کنید

این بخش روش های مختلفی را برای باز کردن URL ها در برنامه ای که اندروید 11 یا بالاتر را هدف قرار می دهد، توضیح می دهد.

URL ها را در مرورگر یا برنامه های دیگر باز کنید

برای باز کردن یک URL، از یک intent استفاده کنید که حاوی کنش intent ACTION_VIEW است، همانطور که در راهنمای بارگیری URL وب توضیح داده شده است. پس از فراخوانی startActivity() با استفاده از این intent، یکی از موارد زیر رخ می دهد:

• 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 ها را در برگه های سفارشی باز کنید

برگه‌های سفارشی به برنامه اجازه می‌دهد ظاهر و احساس مرورگر را سفارشی کند. می‌توانید بدون نیاز به افزودن یا تغییر عنصر <queries> در مانیفست برنامه خود ، یک URL را در یک برگه سفارشی باز کنید .

با این حال، ممکن است بخواهید بررسی کنید که آیا دستگاه مرورگری دارد که از Tabs پشتیبانی می‌کند یا یک مرورگر خاص را برای راه‌اندازی با Custom Tabs با استفاده از CustomTabsClient.getPackageName() انتخاب کنید. در این موارد، عنصر <intent> زیر را به عنوان بخشی از عنصر <queries> در مانیفست خود قرار دهید:

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

به برنامه های غیر مرورگر اجازه دهید URL ها را مدیریت کنند

حتی اگر برنامه شما بتواند URL ها را با استفاده از تب های سفارشی باز کند، توصیه می شود در صورت امکان به یک برنامه غیر مرورگر اجازه دهید URL را باز کند. برای ارائه این قابلیت در برنامه خود، با استفاده از یک intent که پرچم هدف FLAG_ACTIVITY_REQUIRE_NON_BROWSER را تنظیم می کند، با startActivity() تماس بگیرید. اگر سیستم یک ActivityNotFoundException پرتاب کند، برنامه شما می‌تواند URL را در یک برگه سفارشی باز کند.

اگر یک intent شامل این پرچم باشد، فراخوانی به startActivity() باعث می‌شود که ActivityNotFoundException زمانی که یکی از شرایط زیر رخ می‌دهد پرتاب شود:

• این تماس مستقیماً یک برنامه مرورگر راه اندازی می کرد.
• این تماس یک گفتگوی ابهام‌زدایی را به کاربر نشان می‌دهد که تنها گزینه‌ها برنامه‌های مرورگر هستند.

قطعه کد زیر نحوه به روز رسانی منطق خود را برای استفاده از پرچم هدف FLAG_ACTIVITY_REQUIRE_NON_BROWSER نشان می دهد:

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)
}

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 را تنظیم می‌کند.

اگر یک intent شامل این پرچم باشد، فراخوانی به startActivity() باعث می‌شود که ActivityNotFoundException در زمانی که تماس یک گفتگوی ابهام‌زدایی را به کاربر نشان می‌دهد پرتاب می‌شود.

اگر یک intent هم این پرچم و هم پرچم هدف FLAG_ACTIVITY_REQUIRE_NON_BROWSER را شامل شود، یک فراخوانی به startActivity() باعث می‌شود یک ActivityNotFoundException پرتاب شود که یکی از شرایط زیر رخ دهد:

• تماس مستقیماً برنامه مرورگر را راه اندازی می کرد.
• تماس یک گفتگوی ابهام‌زدایی را به کاربر نشان می‌داد.

قطعه کد زیر نحوه استفاده از پرچم‌های FLAG_ACTIVITY_REQUIRE_NON_BROWSER و FLAG_ACTIVITY_REQUIRE_DEFAULT را با هم نشان می‌دهد:

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)
}

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);
}

یک فایل باز کنید

اگر برنامه شما فایل‌ها یا پیوست‌ها را کنترل می‌کند، مانند بررسی اینکه آیا دستگاهی می‌تواند یک فایل معین را باز کند، معمولاً ساده‌ترین کار شروع فعالیتی است که بتواند فایل را مدیریت کند. برای انجام این کار، از یک intent استفاده کنید که شامل کنش intent ACTION_VIEW و URI است که فایل خاص را نشان می‌دهد. اگر هیچ برنامه ای در دستگاه موجود نباشد، برنامه شما می تواند 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() با هدفتان بررسی کنید که آیا یک برنامه در دسترس است یا خیر.

اجازه دسترسی به URI

برای برنامه‌هایی که Android 11 یا بالاتر را هدف قرار می‌دهند تا به URI محتوا دسترسی داشته باشند، هدف برنامه شما باید مجوزهای دسترسی URI را با تنظیم یک یا هر دو پرچم‌های هدف زیر اعلام کند: FLAG_GRANT_READ_URI_PERMISSION و FLAG_GRANT_WRITE_URI_PERMISSION .

در اندروید 11 و بالاتر، مجوزهای دسترسی URI قابلیت‌های زیر را به برنامه‌ای که قصد دریافت می‌کند می‌دهد:

• بسته به مجوزهای URI داده شده، داده‌هایی را که URI محتوا نشان می‌دهد، بخوانید یا روی آن بنویسید.
• در برنامه حاوی ارائه‌دهنده محتوایی که با مرجع URI مطابقت دارد قابل مشاهده باشید. برنامه ای که حاوی ارائه دهنده محتوا است ممکن است با برنامه ای که قصد ارسال می کند متفاوت باشد.

قطعه کد زیر نحوه افزودن پرچم قصد مجوزهای URI را نشان می دهد تا برنامه دیگری که اندروید 11 یا بالاتر را هدف قرار می دهد بتواند داده ها را در URI محتوا مشاهده کند:

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

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

اتصال به خدمات

اگر برنامه شما نیاز به تعامل با سرویسی دارد که به‌طور خودکار قابل مشاهده نیست، می‌توانید اقدام مناسب را در یک عنصر <queries> اعلام کنید. بخش‌های زیر نمونه‌هایی را با استفاده از سرویس‌های رایج ارائه می‌دهند.

به موتور تبدیل متن به گفتار متصل شوید

اگر برنامه شما با موتور تبدیل متن به گفتار (TTS) تعامل دارد، عنصر <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> در مانیفست خود نشان دهید. بخش های زیر راهنمایی دقیق برای چندین سناریو رایج ارائه می دهد.

درخواست برای برنامه های پیام کوتاه

اگر برنامه شما به اطلاعاتی درباره مجموعه برنامه‌های پیامک نصب شده در دستگاهی نیاز دارد، برای مثال برای بررسی اینکه کدام برنامه مدیریت پیامک پیش‌فرض دستگاه است، عنصر <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 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>