این راهنما نمای کلی از نحوه پشتیبانی از موارد استفاده کلیدی برای برقراری ارتباط با دستگاه‌های جانبی را زمانی که برنامه شما در پس‌زمینه اجرا می‌شود ارائه می‌دهد:
گزینه‌های متعددی برای پشتیبانی از هرکدام از این موارد استفاده وجود دارد. هرکدام از این روش‌ها مزایا و معایبی دارند که ممکن است آن‌ها را برای نیازهای خاص شما کم‌وبیش مناسب کند.
نمودار زیر نمای ساده‌شده‌ای از راهنمایی‌های این صفحه را نشان می‌دهد:
پیدا کردن دستگاه
ابتدا، برنامه‌تان باید دستگاهی را برای اتصال پیدا کند. برای پیدا کردن دستگاه BLE، می‌توانید از یکی از میاناهای برنامه‌سازی کاربردی زیر استفاده کنید:
BluetoothLeScannerهمان‌طور که در پیدا کردن دستگاه‌های BLE شرح داده شده است. (نمونه)CompanionDeviceManagerهمان‌طور که در جفت‌سازی دستگاه همپا شرح داده شده است. (نمونه)
در پس‌زمینه
هیچ محدودیتی برای استفاده از هیچ‌کدام از این میاناهای برنامه‌سازی کاربردی در زمانی که برنامه قابل‌مشاهده نیست وجود ندارد، اما هر دو نیاز دارند که فرایند برنامه شما فعال باشد. اگر فرایند برنامه اجرا نمی‌شود، می‌توانید از راه‌حل‌های زیر استفاده کنید:
- برای
BluetoothLeScanner:startScan()را با شیءPendingIntentبه‌جای شیءScanCallbackفراخوانی کنید تا وقتی دستگاهی مطابق با فیلتر شما اسکن شد، مطلع شوید. (نمونه) - برای
CompanionDeviceManager: راهنمایی‌های موجود در بیدار نگه داشتن برنامه‌های همراه را دنبال کنید تا برنامه را بیدار کنید و آن را بیدار نگه دارید درحالی‌که دستگاهی که قبلاً مرتبط شده است در محدوده قرار دارد. (نمونه)
اتصال به دستگاه
برای اتصال به دستگاه پس‌از پیدا کردن آن، باید نمونه
BluetoothDevice را برای
دستگاه از یکی از منابع زیر دریافت کنید:
- نتیجه اسکن
BluetoothLeScannerهمان‌طور که در بخش قبلی شرح داده شده است. - فهرست دستگاه‌های پیوندشده از
BluetoothAdapter.getBondedDevices()بازیابی شد. - حافظه نهان
BluetoothAdapter، بااستفاده ازBluetoothAdapter.getRemoteLeDevice().
پس‌از اینکه نمونه BluetoothDevice را داشتید، می‌توانید با فراخوانی یکی از روش‌های
connectGatt()
درخواست اتصال به دستگاه مربوطه را شروع کنید. مقداری که به مقدار بولی autoConnect ارسال می‌کنید تعیین می‌کند که کارخواه GATT از کدام‌یک از دو حالت اتصال زیر استفاده کند:
- اتصال مستقیم (
autoconnect = false): تلاش برای اتصال مستقیم به دستگاه جانبی، و ناموفق بودن درصورت دردسترس نبودن دستگاه. درصورت قطع اتصال، کارخواه GATT به‌طور خودکار برای اتصال مجدد تلاش نمی‌کند. - اتصال خودکار (
autoconnect = true): هرگاه دستگاه جانبی دردسترس باشد، به‌طور خودکار به آن متصل می‌شود. درصورت قطع اتصال توسط دستگاه جانبی یا به‌دلیل خارج شدن دستگاه جانبی از محدوده، سرویس‌گیرنده GATT به‌طور خودکار تلاش می‌کند وقتی دستگاه جانبی دردسترس است دوباره متصل شود.
در پس‌زمینه
هیچ محدودیتی برای اتصال به دستگاه درحالی‌که برنامه در پس‌زمینه است وجود ندارد، هرچند اگر فرایند شما متوقف شود، اتصال بسته می‌شود. علاوه‌براین، محدودیت‌هایی برای شروع فعالیت‌ها (در Android 10 و بالاتر) یا سرویس‌های پیش‌زمینه (در Android 12 و بالاتر) از پس‌زمینه وجود دارد.
بنابراین، برای برقراری اتصال در پس‌زمینه، برنامه‌ها می‌توانند از راهکارهای زیر استفاده کنند:
- برای اتصال به دستگاهتان، از WorkManager استفاده کنید.
- می‌توانید
PeriodicWorkRequestیاOneTimeWorkRequestرا برای انجام کنش تعریف‌شده‌ای تنظیم کنید، هرچند ممکن است محدودیت‌های برنامه اعمال شود. - علاوه‌براین، می‌توانید از ویژگی‌های WorkManager مانند محدودیت‌های کار، کار تسریع‌شده، خط‌مشی امتحان مجدد، و غیره بهره‌مند شوید.
- اگر اتصال باید تا حد امکان برای انجام کاری مثل همگام‌سازی داده‌ها یا نظرسنجی از دستگاه‌های جانبی فعال نگه داشته شود، باید سرویس پیش‌زمینه‌ای را با دنبال کردن راهنمایی‌های موجود در پشتیبانی از کارگران طولانی‌مدت شروع کنید. بااین‌حال، محدودیت‌های راه‌اندازی سرویس پیش‌زمینه‌ای از Android 12 اعمال می‌شود.
- می‌توانید
- سرویس پیش‌زمینه‌ای را با نوع
connectedDeviceشروع کنید.- اگر اتصال باید تا حد امکان برای انجام کاری مثل همگام‌سازی داده‌ها یا نظرسنجی از دستگاه‌های جانبی فعال نگه داشته شود، باید سرویس پیش‌زمینه‌ای را با دنبال کردن راهنمایی‌های موجود در پشتیبانی از کارگران طولانی‌مدت شروع کنید. بااین‌حال، محدودیت‌های راه‌اندازی سرویس پیش‌زمینه‌ای از Android 12 اعمال می‌شود.
startScan()را با شیءPendingIntentهمان‌طور که در پیدا کردن دستگاه شرح داده شده است فراخوانی کنید تا وقتی دستگاه موجود است، فرایندتان را بیدار کنید. دستگاه جانبی باید درحال تبلیغ باشد.- توصیه می‌کنیم که Worker و Job را شروع کنید. ممکن است سیستم در این فرایند وقفه ایجاد کند و بنابراین فقط می‌تواند از ارتباطات کوتاه پشتیبانی کند.
- در نسخه‌های پایین‌تر از Android 12، می‌توانید سرویس پیش‌زمینه‌ای را مستقیماً از شیء
PendingIntentشروع کنید.
- برای شروع سرویس از پس‌زمینه، از
CompanionDeviceServiceو یکی از اجازه‌هایREQUEST_COMPANION_RUN_IN_BACKGROUNDیاREQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUNDاستفاده کنید.
متصل ماندن به دستگاه
در حالت ایده‌آل، برنامه‌ها باید اتصال به دستگاه‌های جانبی را فقط تا زمانی که لازم است حفظ کنند و پس‌از تکمیل شدن تکلیف، اتصال را قطع کنند. بااین‌حال، دو مورد وجود دارد که ممکن است برنامه نیاز داشته باشد اتصال را به‌طور نامحدود فعال نگه دارد:
در هر دو مورد، گزینه‌های زیر دردسترس است:
- از
CompanionDeviceServiceبا اجازهREQUEST_COMPANION_RUN_IN_BACKGROUNDو روشCompanionDeviceManager.startObservingDevicePresence()استفاده کنید. - سرویس پیش‌زمینه‌ای را درحالی‌که
برنامه در پیش‌زمینه است (یا در یکی از
معافیت‌ها قرار دارد)
با نوع پیش‌زمینه
connectedDeviceشروع کنید.
هنگام جابه‌جایی بین برنامه‌ها
پیدا کردن دستگاه، متصل شدن به آن، و انتقال داده زمان‌بر است و
منابع زیادی مصرف می‌کند. برای جلوگیری از قطع اتصال و نیاز به انجام کامل فرایند هربار که کاربر بین برنامه‌ها جابه‌جا می‌شود یا کارهای هم‌زمان انجام می‌دهد، باید اتصال را تا پایان عملیات فعال نگه دارید. می‌توانید
از سرویس پیش‌نما با نوع connectedDevice یا
میانای برنامه‌سازی کاربردی
حضور دستگاه همپا استفاده کنید.
هنگام گوش دادن به اعلان‌های جانبی
برای گوش دادن به اعلان‌های جانبی، برنامه باید
setCharacteristicNotification() را فراخوانی کند،
بااستفاده از
onCharacteristicChanged()
به فراخوانی‌های برگشتی گوش دهد،
و اتصال را فعال نگه دارد. برای اکثر برنامه‌ها، بهتر است از این مورد استفاده با CompanionDeviceService پشتیبانی شود زیرا برنامه احتمالاً باید برای مدت طولانی به گوش دادن ادامه دهد. بااین‌حال، می‌توانید از سرویس پیش‌زمینه‌ای هم استفاده کنید.
در هر دو مورد، می‌توانید پس‌از پایان فرایند با دنبال کردن دستورالعمل‌های بخش اتصال به دستگاه دوباره متصل شوید.