במכשירים עם Android מגרסה 8.0 (רמת API 26) ואילך, מכשיר נלווה
מבצעת סריקת Bluetooth או Wi-Fi של מכשירים בקרבת מקום
בלי צורך
ACCESS_FINE_LOCATION
הרשאה. כך אפשר למקסם את אמצעי ההגנה על פרטיות המשתמשים. אפשר להשתמש בשיטה הזו כדי
את התצורה הראשונית של המכשיר הנלווה, למשל התקן תומך ב-BLE
שעון חכם. בנוסף, להתאמה של מכשירים נלווים נדרשת הרשאת גישה לשירותי המיקום
להיות מופעלת.
התאמה של מכשיר נלווה לא יוצרת חיבורים באופן עצמאי ולא מופעלת סריקה רציפה. אפליקציות יכולות להשתמש בממשקי API לקישוריות Bluetooth או Wi-Fi כדי ליצור חיבורים.
לאחר התאמת המכשיר, המכשיר יוכל להשתמש
REQUEST_COMPANION_RUN_IN_BACKGROUND
וגם
REQUEST_COMPANION_USE_DATA_IN_BACKGROUND
הרשאות להפעלת האפליקציה מהרקע. אפליקציות יכולות להשתמש גם ב-
REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND
הרשאה להפעלת שירות שפועל בחזית מהרקע.
המשתמש יכול לבחור מכשיר מתוך רשימה ולהעניק לאפליקציה הרשאות גישה
במכשיר. ההרשאות האלה מבוטלות אם מסירים את האפליקציה או מתקשרים
disassociate()
האפליקציה הנלווית אחראית להסרת השיוכים שלה אם המשתמש
לא צריך אותם יותר, למשל כשהם מתנתקים או מסירים מכשירים קשורים.
הטמעת התאמת מכשירים נלווים
בקטע הזה מוסבר איך להשתמש ב-CompanionDeviceManager
כדי להתאים את
אפליקציה עם מכשירים נלווים דרך Bluetooth, BLE ו-Wi-Fi.
הגדרת מכשירים נלווים
דוגמת הקוד הבאה מראה איך להוסיף את
סימון <uses-feature>
ל
קובץ מניפסט. הפעולה הזו מציינת למערכת שהאפליקציה שלך מתכוונת להגדיר מודעה נלווית
מכשירים.
<uses-feature android:name="android.software.companion_device_setup"/>
הצגת רשימה של מכשירים לפי DeviceFilter
אפשר להציג את כל המכשירים הנלווים בטווח שתואמים ל-
DeviceFilter
(מוצג באיור 1). אם רוצים להגביל את הסריקה לפריט אחד בלבד
של המכשיר, אפשר
setSingleDevice()
אל true
(מוצג באיור 2).
![התאמה של מכשירים נלווים](https://developer.android.google.cn/static/images/develop/connectivity/companion-device-pairing-1.png?authuser=5&hl=he)
![התאמת מכשיר יחיד](https://developer.android.google.cn/static/images/develop/connectivity/companion-device-pairing-2.png?authuser=5&hl=he)
אלה קבוצות המשנה של DeviceFilter
אפשר לציין את הפורמט הזה בAssociationRequest
:
לכל שלוש מחלקות המשנה יש builderים שמייעלים את הגדרת המסננים.
בדוגמה הבאה, מכשיר מבצע סריקה לאיתור מכשיר Bluetooth עם
BluetoothDeviceFilter
Kotlin
val deviceFilter: BluetoothDeviceFilter = BluetoothDeviceFilter.Builder() // Match only Bluetooth devices whose name matches the pattern. .setNamePattern(Pattern.compile("My device")) // Match only Bluetooth devices whose service UUID matches this pattern. .addServiceUuid(ParcelUuid(UUID(0x123abcL, -1L)), null) .build()
Java
BluetoothDeviceFilter deviceFilter = new BluetoothDeviceFilter.Builder() // Match only Bluetooth devices whose name matches the pattern. .setNamePattern(Pattern.compile("My device")) // Match only Bluetooth devices whose service UUID matches this pattern. .addServiceUuid(new ParcelUuid(new UUID(0x123abcL, -1L)), null) .build();
מגדירים DeviceFilter
כ-AssociationRequest
CompanionDeviceManager
יכול לקבוע איזה סוג של מכשירים לחפש.
Kotlin
val pairingRequest: AssociationRequest = AssociationRequest.Builder() // Find only devices that match this request filter. .addDeviceFilter(deviceFilter) // Stop scanning as soon as one device matching the filter is found. .setSingleDevice(true) .build()
Java
AssociationRequest pairingRequest = new AssociationRequest.Builder() // Find only devices that match this request filter. .addDeviceFilter(deviceFilter) // Stop scanning as soon as one device matching the filter is found. .setSingleDevice(true) .build();
אחרי שהאפליקציה מפעילה AssociationRequest
, מריצים את
associate()
ב-CompanionDeviceManager
. הפונקציה associate()
מקבל AssociationRequest
ו-Callback
.
הפונקציה Callback
מחזירה
IntentSender
ב-
onAssociationPending
כאשר CompanionDeviceManager
מאתר מכשיר
והוא מוכן להפעלת תיבת דו-שיח להסכמת המשתמש.
אחרי שהמשתמש יאשר את המכשיר, AssociationInfo
של המכשיר מוחזר בעוד onAssociationCreated
.
אם לא יימצאו מכשירים באפליקציה, המערכת תחזיר את הערך onFailure
עם הודעת שגיאה.
במכשירים עם Android מגרסה 13 (API ברמה 33) ואילך:
Kotlin
val deviceManager = requireContext().getSystemService(Context.COMPANION_DEVICE_SERVICE) val executor: Executor = Executor { it.run() } deviceManager.associate(pairingRequest, executor, object : CompanionDeviceManager.Callback() { // Called when a device is found. Launch the IntentSender so the user // can select the device they want to pair with. override fun onAssociationPending(intentSender: IntentSender) { intentSender?.let { startIntentSenderForResult(it, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0) } } override fun onAssociationCreated(associationInfo: AssociationInfo) { // An association is created. } override fun onFailure(errorMessage: CharSequence?) { // To handle the failure. } })
Java
CompanionDeviceManager deviceManager = (CompanionDeviceManager) getSystemService(Context.COMPANION_DEVICE_SERVICE); Executor executor = new Executor() { @Override public void execute(Runnable runnable) { runnable.run(); } }; deviceManager.associate(pairingRequest, new CompanionDeviceManager.Callback() { executor, // Called when a device is found. Launch the IntentSender so the user can // select the device they want to pair with. @Override public void onDeviceFound(IntentSender chooserLauncher) { try { startIntentSenderForResult( chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0 ); } catch (IntentSender.SendIntentException e) { Log.e("MainActivity", "Failed to send intent"); } } @Override public void onAssociationCreated(AssociationInfo associationInfo) { // An association is created. } @Override public void onFailure(CharSequence errorMessage) { // To handle the failure. });
במכשירים עם Android בגרסה 12L (רמת API 32) ומטה (הוצאה משימוש):
Kotlin
val deviceManager = requireContext().getSystemService(Context.COMPANION_DEVICE_SERVICE) deviceManager.associate(pairingRequest, object : CompanionDeviceManager.Callback() { // Called when a device is found. Launch the IntentSender so the user // can select the device they want to pair with. override fun onDeviceFound(chooserLauncher: IntentSender) { startIntentSenderForResult(chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0) } override fun onFailure(error: CharSequence?) { // To handle the failure. } }, null)
Java
CompanionDeviceManager deviceManager = (CompanionDeviceManager) getSystemService(Context.COMPANION_DEVICE_SERVICE); deviceManager.associate(pairingRequest, new CompanionDeviceManager.Callback() { // Called when a device is found. Launch the IntentSender so the user can // select the device they want to pair with. @Override public void onDeviceFound(IntentSender chooserLauncher) { try { startIntentSenderForResult( chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0 ); } catch (IntentSender.SendIntentException e) { Log.e("MainActivity", "Failed to send intent"); } } @Override public void onFailure(CharSequence error) { // To handle the failure. } }, null);
התוצאה של בחירת המשתמש נשלחת חזרה למקטע
onActivityResult()
של הפעילות שלכם. לאחר מכן אפשר לגשת למכשיר שנבחר.
כשהמשתמש יבחר מכשיר Bluetooth, צריך לצפות
BluetoothDevice
כשהמשתמש בוחר מכשיר Bluetooth LE, צריך לצפות
android.bluetooth.le.ScanResult
כשהמשתמש יבחר מכשיר Wi-Fi, צריך לצפות
android.net.wifi.ScanResult
Kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { when (requestCode) { SELECT_DEVICE_REQUEST_CODE -> when(resultCode) { Activity.RESULT_OK -> { // The user chose to pair the app with a Bluetooth device. val deviceToPair: BluetoothDevice? = data?.getParcelableExtra(CompanionDeviceManager.EXTRA_DEVICE) deviceToPair?.let { device -> device.createBond() // Continue to interact with the paired device. } } } else -> super.onActivityResult(requestCode, resultCode, data) } }
Java
@Override protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) { if (resultCode != Activity.RESULT_OK) { return; } if (requestCode == SELECT_DEVICE_REQUEST_CODE && data != null) { BluetoothDevice deviceToPair = data.getParcelableExtra(CompanionDeviceManager.EXTRA_DEVICE); if (deviceToPair != null) { deviceToPair.createBond(); // Continue to interact with the paired device. } } else { super.onActivityResult(requestCode, resultCode, data); } }
מקרה לדוגמה מלא:
במכשירים עם Android מגרסה 13 (API ברמה 33) ואילך:
Kotlin
private const val SELECT_DEVICE_REQUEST_CODE = 0 class MainActivity : AppCompatActivity() { private val deviceManager: CompanionDeviceManager by lazy { getSystemService(Context.COMPANION_DEVICE_SERVICE) as CompanionDeviceManager } val mBluetoothAdapter: BluetoothAdapter by lazy { val java = BluetoothManager::class.java getSystemService(java)!!.adapter } val executor: Executor = Executor { it.run() } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // To skip filters based on names and supported feature flags (UUIDs), // omit calls to setNamePattern() and addServiceUuid() // respectively, as shown in the following Bluetooth example. val deviceFilter: BluetoothDeviceFilter = BluetoothDeviceFilter.Builder() .setNamePattern(Pattern.compile("My device")) .addServiceUuid(ParcelUuid(UUID(0x123abcL, -1L)), null) .build() // The argument provided in setSingleDevice() determines whether a single // device name or a list of them appears. val pairingRequest: AssociationRequest = AssociationRequest.Builder() .addDeviceFilter(deviceFilter) .setSingleDevice(true) .build() // When the app tries to pair with a Bluetooth device, show the // corresponding dialog box to the user. deviceManager.associate(pairingRequest, executor, object : CompanionDeviceManager.Callback() { // Called when a device is found. Launch the IntentSender so the user // can select the device they want to pair with. override fun onAssociationPending(intentSender: IntentSender) { intentSender?.let { startIntentSenderForResult(it, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0) } } override fun onAssociationCreated(associationInfo: AssociationInfo) { // AssociationInfo object is created and get association id and the // macAddress. var associationId: int = associationInfo.id var macAddress: MacAddress = associationInfo.deviceMacAddress } override fun onFailure(errorMessage: CharSequence?) { // Handle the failure. } ) override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { when (requestCode) { SELECT_DEVICE_REQUEST_CODE -> when(resultCode) { Activity.RESULT_OK -> { // The user chose to pair the app with a Bluetooth device. val deviceToPair: BluetoothDevice? = data?.getParcelableExtra(CompanionDeviceManager.EXTRA_DEVICE) deviceToPair?.let { device -> device.createBond() // Maintain continuous interaction with a paired device. } } } else -> super.onActivityResult(requestCode, resultCode, data) } } }
Java
class MainActivityJava extends AppCompatActivity { private static final int SELECT_DEVICE_REQUEST_CODE = 0; Executor executor = new Executor() { @Override public void execute(Runnable runnable) { runnable.run(); } }; @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); CompanionDeviceManager deviceManager = (CompanionDeviceManager) getSystemService( Context.COMPANION_DEVICE_SERVICE ); // To skip filtering based on name and supported feature flags, // do not include calls to setNamePattern() and addServiceUuid(), // respectively. This example uses Bluetooth. BluetoothDeviceFilter deviceFilter = new BluetoothDeviceFilter.Builder() .setNamePattern(Pattern.compile("My device")) .addServiceUuid( new ParcelUuid(new UUID(0x123abcL, -1L)), null ) .build(); // The argument provided in setSingleDevice() determines whether a single // device name or a list of device names is presented to the user as // pairing options. AssociationRequest pairingRequest = new AssociationRequest.Builder() .addDeviceFilter(deviceFilter) .setSingleDevice(true) .build(); // When the app tries to pair with the Bluetooth device, show the // appropriate pairing request dialog to the user. deviceManager.associate(pairingRequest, new CompanionDeviceManager.Callback() { executor, // Called when a device is found. Launch the IntentSender so the user can // select the device they want to pair with. @Override public void onDeviceFound(IntentSender chooserLauncher) { try { startIntentSenderForResult( chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0 ); } catch (IntentSender.SendIntentException e) { Log.e("MainActivity", "Failed to send intent"); } } @Override public void onAssociationCreated(AssociationInfo associationInfo) { // AssociationInfo object is created and get association id and the // macAddress. int associationId = associationInfo.getId(); MacAddress macAddress = associationInfo.getDeviceMacAddress(); } @Override public void onFailure(CharSequence errorMessage) { // Handle the failure. }); } @Override protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) { if (resultCode != Activity.RESULT_OK) { return; } if (requestCode == SELECT_DEVICE_REQUEST_CODE) { if (resultCode == Activity.RESULT_OK && data != null) { BluetoothDevice deviceToPair = data.getParcelableExtra( CompanionDeviceManager.EXTRA_DEVICE ); if (deviceToPair != null) { deviceToPair.createBond(); // ... Continue interacting with the paired device. } } } else { super.onActivityResult(requestCode, resultCode, data); } } }
במכשירים עם Android בגרסה 12L (רמת API 32) ומטה (הוצאה משימוש):
Kotlin
private const val SELECT_DEVICE_REQUEST_CODE = 0 class MainActivity : AppCompatActivity() { private val deviceManager: CompanionDeviceManager by lazy { getSystemService(Context.COMPANION_DEVICE_SERVICE) as CompanionDeviceManager } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // To skip filters based on names and supported feature flags (UUIDs), // omit calls to setNamePattern() and addServiceUuid() // respectively, as shown in the following Bluetooth example. val deviceFilter: BluetoothDeviceFilter = BluetoothDeviceFilter.Builder() .setNamePattern(Pattern.compile("My device")) .addServiceUuid(ParcelUuid(UUID(0x123abcL, -1L)), null) .build() // The argument provided in setSingleDevice() determines whether a single // device name or a list of them appears. val pairingRequest: AssociationRequest = AssociationRequest.Builder() .addDeviceFilter(deviceFilter) .setSingleDevice(true) .build() // When the app tries to pair with a Bluetooth device, show the // corresponding dialog box to the user. deviceManager.associate(pairingRequest, object : CompanionDeviceManager.Callback() { override fun onDeviceFound(chooserLauncher: IntentSender) { startIntentSenderForResult(chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0) } override fun onFailure(error: CharSequence?) { // Handle the failure. } }, null) } override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { when (requestCode) { SELECT_DEVICE_REQUEST_CODE -> when(resultCode) { Activity.RESULT_OK -> { // The user chose to pair the app with a Bluetooth device. val deviceToPair: BluetoothDevice? = data?.getParcelableExtra(CompanionDeviceManager.EXTRA_DEVICE) deviceToPair?.let { device -> device.createBond() // Maintain continuous interaction with a paired device. } } } else -> super.onActivityResult(requestCode, resultCode, data) } } }
Java
class MainActivityJava extends AppCompatActivity { private static final int SELECT_DEVICE_REQUEST_CODE = 0; @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); CompanionDeviceManager deviceManager = (CompanionDeviceManager) getSystemService( Context.COMPANION_DEVICE_SERVICE ); // To skip filtering based on name and supported feature flags, // don't include calls to setNamePattern() and addServiceUuid(), // respectively. This example uses Bluetooth. BluetoothDeviceFilter deviceFilter = new BluetoothDeviceFilter.Builder() .setNamePattern(Pattern.compile("My device")) .addServiceUuid( new ParcelUuid(new UUID(0x123abcL, -1L)), null ) .build(); // The argument provided in setSingleDevice() determines whether a single // device name or a list of device names is presented to the user as // pairing options. AssociationRequest pairingRequest = new AssociationRequest.Builder() .addDeviceFilter(deviceFilter) .setSingleDevice(true) .build(); // When the app tries to pair with the Bluetooth device, show the // appropriate pairing request dialog to the user. deviceManager.associate(pairingRequest, new CompanionDeviceManager.Callback() { @Override public void onDeviceFound(IntentSender chooserLauncher) { try { startIntentSenderForResult(chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0); } catch (IntentSender.SendIntentException e) { // failed to send the intent } } @Override public void onFailure(CharSequence error) { // handle failure to find the companion device } }, null); } @Override protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) { if (requestCode == SELECT_DEVICE_REQUEST_CODE) { if (resultCode == Activity.RESULT_OK && data != null) { BluetoothDevice deviceToPair = data.getParcelableExtra( CompanionDeviceManager.EXTRA_DEVICE ); if (deviceToPair != null) { deviceToPair.createBond(); // ... Continue interacting with the paired device. } } } else { super.onActivityResult(requestCode, resultCode, data); } } }
פרופילים של מכשירים נלווים
ב-Android 12 (רמת API 31) ואילך, אפליקציות נלוות שמנהלות מכשירים כמו שעונים יכולים להשתמש בפרופילים של מכשירים נלווים כדי לייעל את תהליך ההגדרה להעניק את ההרשאות הדרושות בזמן ההתאמה. מידע נוסף זמין במאמר הבא: פרופילים של מכשירים נלווים.
השארת אפליקציות נלוות במצב פעיל
ב-Android מגרסה 12 (רמת API 31) ואילך, אפשר להשתמש בממשקי API נוספים כדי האפליקציה הנלווית תמשיך לפעול כשמכשיר נלווה נמצא בטווח. ממשקי ה-API האלה מאפשרים לכם:
יש להוציא את האפליקציה ממצב שינה כשמכשיר נלווה נמצא בטווח.
פרטים נוספים זמינים במאמר
CompanionDeviceManager.startObservingDevicePresence()
להבטיח שתהליך האפליקציה ימשיך לפעול כל עוד המודעה הנלווית שהמכשיר יישאר בטווח.
פרטים נוספים זמינים במאמר
CompanionDeviceService.onDeviceAppeared()