Na urządzeniach z Androidem 8.0 (poziom interfejsu API 26) lub nowszym na urządzeniu towarzyszącym
parowanie polega na skanowaniu przez Bluetooth lub Wi-Fi urządzeń w pobliżu w imieniu Twojego
bez konieczności
ACCESS_FINE_LOCATION
uprawnienia. Pomoże to zmaksymalizować ochronę prywatności użytkowników. Użyj tej metody, aby:
przeprowadzić początkową konfigurację urządzenia towarzyszącego, na przykład z modułem BLE
smartwatchu. Ponadto parowanie urządzeń towarzyszących wymaga, aby usługi lokalizacyjne
włącz.
Parowanie urządzeń towarzyszących nie powoduje samoistnego tworzenia połączeń ani ich nie umożliwia ciągłego skanowania. Aplikacje mogą używać interfejsów API połączeń przez Bluetooth lub Wi-Fi do: nawiązywać kontakty.
Po sparowaniu urządzenie może korzystać z
REQUEST_COMPANION_RUN_IN_BACKGROUND
oraz
REQUEST_COMPANION_USE_DATA_IN_BACKGROUND
uprawnień do uruchamiania aplikacji w tle. Aplikacje mogą też używać
REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND
uprawnienia do uruchomienia usługi na pierwszym planie w tle.
Użytkownik może wybrać urządzenie z listy i przyznać aplikacji uprawnienia dostępu
urządzenia. Te uprawnienia zostaną unieważnione, jeśli odinstalujesz aplikację lub połączenie
disassociate()
Aplikacja towarzysząca jest odpowiedzialna za usuwanie własnych powiązań, jeśli użytkownik
już ich nie potrzebują, na przykład po wylogowaniu się lub usunięciu powiązanych urządzeń.
Wdróż parowanie urządzeń towarzyszących
W tej sekcji wyjaśniamy, jak używać urządzenia CompanionDeviceManager
do parowania
z urządzeniami towarzyszącymi przez Bluetooth, BLE i Wi-Fi.
Określanie urządzeń towarzyszących
Poniższy przykładowy kod pokazuje, jak dodać
<uses-feature>
na
manifestu. Informuje to system, że aplikacja chce skonfigurować aplikację towarzyszącą
urządzenia.
<uses-feature android:name="android.software.companion_device_setup"/>
Wyświetl listę urządzeń według urządzenia DeviceFilter
Możesz wyświetlić wszystkie urządzenia towarzyszące w zasięgu pasujące do zapytania
DeviceFilter
przez reklamodawcę (jak widać na rysunku 1). Jeśli chcesz ograniczyć skanowanie tylko do jednego
urządzenia, możesz
setSingleDevice()
do true
(widoczne na ilustracji 2).
![Parowanie urządzeń towarzyszących](https://developer.android.com/static/images/develop/connectivity/companion-device-pairing-1.png?authuser=6&hl=pl)
![Parowanie jednego urządzenia](https://developer.android.com/static/images/develop/connectivity/companion-device-pairing-2.png?authuser=6&hl=pl)
Oto podklasy klasy DeviceFilter
, które
można określić w AssociationRequest
:
Wszystkie 3 podklasy mają kreatory, które upraszczają konfigurację filtrów.
W poniższym przykładzie urządzenie szuka urządzenia Bluetooth z
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();
Ustaw DeviceFilter
na AssociationRequest
,
CompanionDeviceManager
może określić, jakiego typu urządzenia szukać.
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();
Po zainicjowaniu przez aplikację AssociationRequest
uruchom
associate()
w CompanionDeviceManager
. Funkcja associate()
pobiera AssociationRequest
i Callback
.
Callback
zwraca błąd
IntentSender
w
onAssociationPending
, gdy CompanionDeviceManager
zlokalizuje urządzenie
i można zacząć od otwarcia
okna z prośbą o zgodę na przetwarzanie danych osobowych.
Gdy użytkownik potwierdzi urządzenie, AssociationInfo
urządzenia jest zwrócone w onAssociationCreated
.
Jeśli aplikacja nie znajdzie żadnych urządzeń, wywołanie zwrotne zwróci onFailure
z komunikatem o błędzie.
Na urządzeniach z Androidem 13 (poziom interfejsu API 33) lub nowszym:
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. });
Na urządzeniach z Androidem 12L (poziom interfejsu API 32) lub starszym (wycofano):
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);
Wynik wyboru użytkownika jest odsyłany z powrotem do fragmentu w tagu
onActivityResult()
Twojej aktywności. Dzięki temu uzyskasz dostęp do wybranego urządzenia.
Gdy użytkownik wybierze urządzenie Bluetooth,
BluetoothDevice
Gdy użytkownik wybierze urządzenie Bluetooth LE,
android.bluetooth.le.ScanResult
Gdy użytkownik wybierze urządzenie 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); } }
Zobacz pełny przykład:
Na urządzeniach z Androidem 13 (poziom interfejsu API 33) lub nowszym:
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); } } }
Na urządzeniach z Androidem 12L (poziom interfejsu API 32) lub starszym (wycofano):
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); } } }
Profile urządzeń towarzyszących
Na Androidzie 12 (poziom interfejsu API 31) lub nowszym w aplikacjach towarzyszących służących do zarządzania urządzeniami takimi jak zegarki mogą korzystać z profili urządzeń towarzyszących, aby uprościć proces konfiguracji przez na przyznanie wymaganych uprawnień podczas parowania. Więcej informacji: Profile urządzeń towarzyszących
Nie usypiaj aplikacji towarzyszących
Na Androidzie 12 (poziom interfejsu API 31) i nowszym możesz używać dodatkowych interfejsów API, aby aplikacja towarzysząca będzie działać, gdy urządzenie towarzyszące będzie w zasięgu. Dzięki tym interfejsom API możesz:
Wybudź aplikację, gdy urządzenie towarzyszące będzie w zasięgu.
Więcej informacji:
CompanionDeviceManager.startObservingDevicePresence()
Zapewnij, że proces aplikacji będzie działać tak długo, jak długo działanie aplikacji towarzyszącej urządzenie pozostaje w zasięgu.
Więcej informacji:
CompanionDeviceService.onDeviceAppeared()