Auf Geräten mit Android 8.0 (API-Level 26) und höher: Begleitgerät
beim Koppeln wird für Ihr Gerät eine Bluetooth- oder WLAN-Suche nach Geräten in der Nähe durchgeführt,
ohne die App
ACCESS_FINE_LOCATION
Berechtigung. So können Sie die Privatsphäre der Nutzer bestmöglich schützen. Verwenden Sie diese Methode, um
die Erstkonfiguration des Begleitgeräts, z. B. eines BLE-fähigen Geräts, durchführen
Smartwatch. Für das Koppeln von Begleitgeräten sind außerdem Standortdienste erforderlich,
aktiviert sein.
Beim Koppeln von Begleitgeräten werden keine Verbindungen selbst hergestellt und nicht aktiviert kontinuierliches Scannen. Über Bluetooth- oder WLAN-Verbindungs-APIs können Apps Verbindungen herstellen.
Nach der Kopplung kann das Gerät die
REQUEST_COMPANION_RUN_IN_BACKGROUND
und
REQUEST_COMPANION_USE_DATA_IN_BACKGROUND
Berechtigungen, um die App im Hintergrund zu starten. Apps können auch
REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND
Berechtigung, einen Dienst im Vordergrund aus dem Hintergrund zu starten.
Ein Nutzer kann ein Gerät aus einer Liste auswählen und der App Zugriffsberechtigungen erteilen.
auf dem Gerät. Diese Berechtigungen werden widerrufen, wenn du die App deinstallierst oder aufrufst
disassociate()
Die Companion-App ist für das Löschen ihrer eigenen Verknüpfungen zuständig, wenn der Nutzer
sie nicht mehr benötigt, z. B. wenn sie sich abmelden oder gebundene Geräte entfernen.
Begleitgerätkopplung implementieren
In diesem Abschnitt wird erläutert, wie du CompanionDeviceManager zum Koppeln deines
App mit Begleitgeräten über Bluetooth, BLE und WLAN.
Begleitgeräte angeben
Im folgenden Codebeispiel wird gezeigt, wie Sie den Parameter
<uses-feature>-Flag in einen
Manifestdatei. Dadurch wird dem System mitgeteilt, dass in Ihrer App Companion-Anzeigen eingerichtet werden sollen.
Geräte.
<uses-feature android:name="android.software.companion_device_setup"/>
Geräte nach DeviceFilter auflisten
Du kannst alle Companion-Geräte anzeigen lassen, die sich in Reichweite befinden und die den
DeviceFilter
die Sie bereitstellen (siehe Abbildung 1). Wenn Sie den Scan auf nur eine
können Sie
setSingleDevice()
zu true (siehe Abbildung 2).
Im Folgenden finden Sie die abgeleiteten Klassen von DeviceFilter, die
kann in AssociationRequest angegeben werden:
Alle drei Unterklassen haben Builder, die die Konfiguration von Filtern optimieren.
Im folgenden Beispiel sucht ein Gerät nach einem Bluetooth-Gerät mit einem
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();
Setzen Sie DeviceFilter auf AssociationRequest, damit
CompanionDeviceManager kann festlegen, nach welchen Gerätetypen 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();
Nachdem Ihre App ein AssociationRequest initialisiert hat, führen Sie den
associate()
für CompanionDeviceManager. associate()-Funktion
nimmt ein AssociationRequest und ein Callback ein.
Callback gibt eine
IntentSender bei
onAssociationPending, wenn CompanionDeviceManager ein Gerät findet
Nun kann ein Dialog
zum Einholen der Nutzereinwilligung gestartet werden.
Nachdem der Nutzer das Gerät bestätigt hat, wird ein AssociationInfo-Fehler angezeigt.
des Geräts wird in onAssociationCreated zurückgegeben.
Wenn deine App keine Geräte findet, gibt der Callback onFailure zurück.
mit einer Fehlermeldung.
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) {
// 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.
});
Auf Geräten mit Android 12L (API-Level 32) oder 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?) {
// 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);
Das Ergebnis der Nutzerauswahl wird an das Fragment im
onActivityResult()
Ihrer Aktivitäten. Sie können dann auf das ausgewählte Gerät zugreifen.
Wenn der Nutzer ein Bluetooth-Gerät auswählt, wird eine
BluetoothDevice
Wenn der Nutzer ein Bluetooth LE-Gerät auswählt, wird eine
android.bluetooth.le.ScanResult
Wenn der Nutzer ein WLAN-Gerät auswählt,
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);
}
}
Sehen Sie sich das vollständige Beispiel an:
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) oder 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
Unter Android 12 (API-Level 31) und höher werden Companion-Apps zur Verwaltung von Geräten wie Smartwatches können mit Companion-Geräteprofilen die Einrichtung vereinfachen, und die erforderlichen Berechtigungen bei der Kopplung gewähren. Weitere Informationen finden Sie unter Companion-Geräteprofile
Companion-Apps aktiv lassen
Unter Android 12 (API-Level 31) und höher können Sie zusätzliche APIs verwenden, um bleibt deine Companion-App aktiv, solange 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()Es wird garantiert, dass ein App-Prozess ausgeführt wird, solange der Companion-Vorgang Gerät in Reichweite bleibt.
Weitere Informationen finden Sie unter
CompanionDeviceService.onDeviceAppeared()