Na urządzeniach z Androidem 8.0 (poziom interfejsu API 26) lub nowszym funkcja parowania urządzeń towarzyszących przeprowadza skanowanie urządzeń w pobliżu przez Bluetooth lub Wi-Fi w imieniu aplikacji bez wymagania uprawnień ACCESS_FINE_LOCATION
. Pomaga to zmaksymalizować ochronę prywatności użytkowników. Po sparowaniu urządzenie może wykorzystać uprawnienia REQUEST_COMPANION_RUN_IN_BACKGROUND
i REQUEST_COMPANION_USE_DATA_IN_BACKGROUND
, aby uruchomić aplikację w tle. Użyj tej metody, aby przeprowadzić wstępną konfigurację urządzenia towarzyszącego, np. smartwatcha obsługującego BLE. Dodatkowo parowanie urządzeń towarzyszących wymaga włączenia usług lokalizacyjnych.
Parowanie urządzenia towarzyszącego nie tworzy połączeń samodzielnie. Interfejsy API łączności Bluetooth i Wi-Fi nawiązują połączenia. Parowanie urządzeń towarzyszących też nie umożliwia ciągłego skanowania.
Użytkownik może wybrać urządzenie z listy i przyznać mu uprawnienia dostępu do aplikacji.
Te uprawnienia zostaną anulowane, jeśli odinstalujesz aplikację lub wywołasz
disassociate()
.
Aplikacja jest odpowiedzialna za usuwanie własnych powiązań, gdy użytkownik już ich nie potrzebuje, na przykład gdy się wyloguje lub usunie połączone urządzenia.
Wdróż parowanie urządzeń towarzyszących
Aby nawiązać połączenie z urządzeniem towarzyszącym i nim zarządzać, użyj CompanionDeviceManager
.
W tej sekcji wyjaśniamy, jak dostosować okno z prośbą o sparowanie podczas parowania aplikacji z urządzeniami towarzyszącymi przez Bluetooth, BLE i Wi-Fi.
Określ urządzenia towarzyszące
Poniższy przykładowy kod pokazuje, jak dodać flagę <uses-feature>
do pliku manifestu. Informuje to system, że Twoja aplikacja zamierza skonfigurować urządzenia towarzyszące.
<uses-feature android:name="android.software.companion_device_setup"/>
Wyświetlanie listy urządzeń według typu
Możesz wyświetlić wszystkie dostępne urządzenia towarzyszące zgodne z podanym przez Ciebie filtrem lub ograniczyć wyświetlanie do jednej opcji (jak widać na ilustracji 1). Możesz to skonfigurować, tworząc filtr określający, jakich urządzeń szuka Twoja aplikacja, lub ustawiając w polu setSingleDevice()
wartość true
(jak widać na ilustracji 2).
Aby zastosować filtr do listy urządzeń towarzyszących, która pojawi się w oknie dialogowym z prośbą, sprawdź, czy Bluetooth jest włączony
lub czy Wi-Fi jest włączone.
Po włączeniu połączenia możesz dodać DeviceFilter
. Te podklasy DeviceFilter
określają typy urządzeń, z którymi aplikacja może powiązać użytkownika na podstawie typu połączenia:
Wszystkie 3 podklasy mają montery, które upraszczają konfigurację filtrów.
W poniższym przykładzie urządzenie wyszukuje urządzenie Bluetooth z komponentem 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
jako AssociationRequest
, aby menedżer urządzeń mógł określić, jakiego typu urządzenie ma 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 AssociationRequest
uruchom funkcję associate()
w CompanionDeviceManager
. Funkcja associate()
paruje obiekt żądania i wywołanie zwrotne. Wywołania zwrotne wskazują, kiedy aplikacja lokalizuje urządzenie i jest gotowa do wyświetlenia okna dialogowego, w którym użytkownik może wpisać swój wybór.
Jeśli aplikacja nie znajdzie żadnych urządzeń, wywołanie zwrotne zwróci komunikat 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) { // The association is created. } override fun onFailure(errorMessage: CharSequence?) { // 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) { // The association is created. } @Override public void onFailure(CharSequence errorMessage) { // Handle the failure. });
Na urządzeniach z Androidem 12L (poziom interfejsu API 32) i starszym (wycofanym):
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?) { // 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) { // Handle the failure. } }, null);
Aby umożliwić użytkownikom wybór typu urządzeń, z którymi chcą się połączyć, rozpocznij działanie związane z preferencjami za pomocą parametru intentSender
w funkcji onAssociationPending()
. Wyniki tego działania są odsyłane do fragmentu w funkcji onActivityResult()
w aktywności związanej z ustawieniami. Dzięki temu zobaczysz informację, gdy użytkownik dokona wyboru na podstawie wyniku. Dzięki temu uzyskasz dostęp do wybranego urządzenia. Gdy użytkownik wybierze urządzenie Bluetooth, wysyłanym wynikiem jest obiekt BluetoothDevice
.
I podobnie, gdy funkcja onAssociationPending()
wykryje, że użytkownik wybiera urządzenie Bluetooth LE, poczekaj na obiekt android.bluetooth.le.ScanResult
. W przypadku urządzeń Wi-Fi oczekujej obiektu 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); } }
Aby wdrożyć parowanie urządzeń towarzyszących za pomocą filtrów, które mogą określać urządzenia i wyświetlać je według typu, zapoznaj się z tymi przykładami:
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) i starszym (wycofanym):
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
Aplikacje partnerów na Androidzie 12 (poziom interfejsu API 31) i nowszych mogą używać profili urządzeń towarzyszących podczas łączenia się z zegarkiem. Więcej informacji znajdziesz w przewodniku dotyczącym prośby o uprawnienia w Wear OS.
Nie usypiaj aplikacji towarzyszących
Na Androidzie 12 (poziom interfejsu API 31) i nowszych możesz użyć dodatkowych interfejsów API, które pomogą Twojej aplikacji towarzyszącej działać, gdy urządzenie towarzyszące znajduje się w zasięgu. Dzięki tym interfejsom API możesz:
Wybudź aplikację, gdy urządzenie towarzyszące znajduje się w zasięgu.
Więcej informacji:
CompanionDeviceManager.startObservingDevicePresence()
.Pamiętaj, że proces aplikacji będzie kontynuowany, dopóki urządzenie towarzyszące będzie znajdować się w zasięgu.
Więcej informacji:
CompanionDeviceService.onDeviceAppeared()
.