Auf Geräten mit Android 8.0 (API-Level 26) und höher wird bei der Kopplung des Begleitgeräts im Namen deiner App eine Bluetooth- oder WLAN-Suche nach Geräten in der Nähe durchgeführt, ohne dass die Berechtigung ACCESS_FINE_LOCATION erforderlich ist. So können Sie die Privatsphäre der Nutzer bestmöglich schützen. Nach der Kopplung kann das Gerät die Berechtigungen REQUEST_COMPANION_RUN_IN_BACKGROUND und REQUEST_COMPANION_USE_DATA_IN_BACKGROUND nutzen, um die App im Hintergrund zu starten. Verwenden Sie diese Methode, um die Erstkonfiguration des Begleitgeräts, z. B. einer BLE-fähigen Smartwatch, durchzuführen. Für das Koppeln von Begleitgeräten müssen außerdem die Standortdienste aktiviert sein.
Beim Koppeln des Begleitgeräts werden keine Verbindungen automatisch hergestellt. Bluetooth- und Wi-Fi-Konnektivitäts-APIs stellen Verbindungen her. Durch die Kopplung von Companion-Geräten wird auch kein kontinuierliches Scannen ermöglicht.
Ein Nutzer kann ein Gerät aus einer Liste auswählen und ihm Zugriff auf eine App gewähren. Diese Berechtigungen werden widerrufen, wenn Sie die App deinstallieren oder disassociate() aufrufen.
Eine App ist dafür verantwortlich, ihre eigenen Verknüpfungen zu löschen, wenn der Nutzer diese nicht mehr benötigt, z. B. wenn er sich abmeldet oder verbundene Geräte entfernt.
Begleitgerätkopplung implementieren
Eine Verbindung zu einem Begleitgerät kannst du über den CompanionDeviceManager herstellen und verwalten.
In diesem Abschnitt wird erläutert, wie du das Dialogfeld für die Kopplungsanfrage anpassen kannst, wenn du deine App über Bluetooth, BLE und WLAN mit Begleitgeräten koppelst.
Begleitgeräte angeben
Das folgende Codebeispiel zeigt, wie Sie das Flag <uses-feature> in eine Manifestdatei einfügen. Dadurch wird dem System mitgeteilt, dass mit deiner App Companion-Geräte eingerichtet werden sollen.
<uses-feature android:name="android.software.companion_device_setup"/>
Geräte nach Typ auflisten
Du kannst alle verfügbaren Companion-Geräte anzeigen lassen, die dem von dir angegebenen Filter entsprechen, oder die Anzeige auf eine einzige Option beschränken (siehe Abbildung 1). Dazu erstellen Sie einen Filter, der angibt, nach welchen Gerätetypen Ihre App sucht, oder setzen setSingleDevice() auf true (siehe Abbildung 2).
Wenn du einen Filter auf die Liste der Begleitgeräte anwenden möchtest, die im Dialogfeld „Anfrage“ angezeigt wird, musst du prüfen, ob Bluetooth aktiviert ist oder ob WLAN aktiviert ist.
Nachdem eine Verbindung aktiviert wurde, können Sie eine DeviceFilter hinzufügen. Die folgenden abgeleiteten Klassen von DeviceFilter geben die Gerätetypen an, die Ihre App basierend auf einem Verbindungstyp verknüpfen kann:
Alle drei Unterklassen haben Builder, die die Konfiguration von Filtern optimieren.
Im folgenden Beispiel sucht ein Gerät mit einer BluetoothDeviceFilter nach einem Bluetooth-Gerät.
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();
Legen Sie für DeviceFilter einen AssociationRequest fest, damit der Gerätemanager bestimmen kann, nach welchem Gerätetyp gesucht werden soll.
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();
Führen Sie nach dem Initialisieren eines AssociationRequest die Funktion associate() für CompanionDeviceManager aus. Die Funktion associate() übernimmt die Verknüpfung des Anfrageobjekts mit dem Callback. Callbacks zeigen an, wenn eine App ein Gerät findet, sodass ein Dialogfeld geöffnet werden kann, in dem der Nutzer seine Auswahl eingeben kann.
Wenn eine App keine Geräte findet, gibt der Callback eine Fehlermeldung zurück.
Auf Geräten mit Android 13 (API-Level 33) und höher:
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.
});
Auf Geräten mit Android 12L (API-Level 32) und niedriger (eingestellt):
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);
Damit Nutzer auswählen können, mit welchem Gerätetyp sie eine Verbindung herstellen möchten, starten Sie mit dem Parameter intentSender in der Funktion onAssociationPending() eine Einstellungsaktivität. Die Ergebnisse dieser Aktion werden an das Fragment in der Funktion onActivityResult() Ihrer Einstellungsaktivität zurückgesendet. Dadurch werden Sie aktualisiert, wenn der Nutzer eine Auswahl basierend auf dem Ergebnis trifft. Sie können dann auf das ausgewählte Gerät zugreifen. Wenn ein Nutzer ein Bluetooth-Gerät auswählt, wird ein BluetoothDevice-Objekt gesendet.
Wenn die Funktion onAssociationPending() erkennt, dass ein Nutzer ein Bluetooth LE-Gerät auswählt, wird ein android.bluetooth.le.ScanResult-Objekt erwartet. Bei WLAN-Geräten wird ein android.net.wifi.ScanResult-Objekt erwartet.
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);
}
}
In den folgenden Beispielen wird die Kopplung von Companion-Geräten mit Filtern implementiert, mit denen Geräte angegeben und nach Typ aufgelistet werden können:
Auf Geräten mit Android 13 (API-Level 33) und höher:
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);
}
}
}
Auf Geräten mit Android 12L (API-Level 32) und niedriger (eingestellt):
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 von Companion-Geräten
Partner-Apps auf Geräten mit Android 12 (API-Level 31) und höher können Profile von Companion-Geräten verwenden, um eine Verbindung mit einer Smartwatch herzustellen. Weitere Informationen findest du in der Anleitung zum Anfordern von Berechtigungen unter Wear OS.
Companion-Apps aktiv lassen
Unter Android 12 (API-Level 31) und höher können Sie zusätzliche APIs verwenden, damit die Companion-App ausgeführt wird, während sich ein Begleitgerät in Reichweite befindet. Mit diesen APIs können Sie Folgendes tun:
Aktiviere den Ruhemodus deiner App, wenn sich ein Begleitgerät in Reichweite befindet.
Weitere Informationen finden Sie unter
CompanionDeviceManager.startObservingDevicePresence().Ein App-Prozess muss so lange ausgeführt werden, wie er sich in Reichweite des Begleitgeräts befindet.
Weitere Informationen finden Sie unter
CompanionDeviceService.onDeviceAppeared().