Android 8.0 (API düzeyi 26) ve sonraki sürümleri çalıştıran cihazlarda, tamamlayıcı cihaz eşleme özelliği, ACCESS_FINE_LOCATION izni gerekmeden yakındaki cihazları uygulamanız adına Bluetooth veya kablosuz ağ üzerinden tarar. Bu, kullanıcı gizliliğini en üst düzeye çıkarmaya yardımcı olur. Eşlenen cihaz, uygulamayı arka plandan başlatmak için REQUEST_COMPANION_RUN_IN_BACKGROUND ve REQUEST_COMPANION_USE_DATA_IN_BACKGROUND izinlerinden yararlanabilir. BLE özellikli akıllı saat gibi tamamlayıcı cihazın ilk yapılandırmasını gerçekleştirmek için bu yöntemi kullanın. Ayrıca, tamamlayıcı cihaz eşleme için Konum Hizmetleri'nin etkinleştirilmesi gerekir.
Tamamlayıcı cihaz eşleme kendiliğinden bağlantı oluşturmaz. Bluetooth ve kablosuz bağlantı API'leri bağlantılar oluşturur. Tamamlayıcı cihaz eşleme, sürekli taramayı da etkinleştirmez.
Bir kullanıcı listeden bir cihaz seçebilir ve uygulamaya erişim izni verebilir.
Uygulamayı kaldırırsanız veya disassociate() çağrısı yaparsanız bu izinler iptal edilir.
Kullanıcının artık ihtiyaç duymadığı (örneğin, çıkış yapması veya bağlı cihazları kaldırması) durumunda, uygulama kendi ilişkilendirmelerini temizlemekten sorumludur.
Tamamlayıcı cihaz eşlemeyi uygulayın
Tamamlayıcı cihazla bağlantı kurmak ve yönetmek için CompanionDeviceManager aracını kullanın.
Bu bölümde, uygulamanızı Bluetooth, BDE ve kablosuz ağ üzerinden tamamlayıcı cihazlarla eşlediğinizde eşleme isteği iletişim kutunuzu nasıl özelleştireceğiniz açıklanmaktadır.
Tamamlayıcı cihazları belirtin
Aşağıdaki kod örneğinde, <uses-feature> işaretinin bir manifest dosyasına nasıl ekleneceği gösterilmektedir. Bu, sisteme uygulamanızın tamamlayıcı cihazları kurmayı amaçladığını bildirir.
<uses-feature android:name="android.software.companion_device_setup"/>
Cihazları türe göre listeleme
Sağladığınız filtreyle eşleşen mevcut tüm tamamlayıcı cihazları görüntüleyebilir veya ekranı tek bir seçenekle sınırlandırabilirsiniz (Şekil 1'de gösterilmiştir). Uygulamanızın ne tür cihazlar aradığını belirten bir filtre oluşturarak veya setSingleDevice() değerini true olarak ayarlayarak (Şekil 2'de gösterilmektedir) bunu yapılandırırsınız.
İstek iletişim kutusunda görünen tamamlayıcı cihazlar listesine filtre uygulamak için Bluetooth'un açık olup olmadığını kontrol edin veya kablosuz özelliğinin açık olup olmadığını kontrol edin.
Bağlantı etkinleştirildikten sonra DeviceFilter ekleyebilirsiniz. Aşağıdaki DeviceFilter alt sınıfları, bağlantı türüne göre uygulamanızın ilişkilendirebileceği cihaz türlerini belirtir:
Üç alt sınıfın da filtre yapılandırmasını basitleştiren oluşturucular vardır.
Aşağıdaki örnekte, bir cihaz BluetoothDeviceFilter bulunan bir Bluetooth cihazı tarar.
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();
Cihaz yöneticisinin ne tür cihaz aranacağını belirleyebilmesi için DeviceFilter öğesini AssociationRequest olarak ayarlayın.
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();
Bir AssociationRequest öğesini başlattıktan sonra CompanionDeviceManager üzerinde associate() işlevini çalıştırın. associate() işlevi, eşleme isteği nesnesini ve geri çağırmayı üstlenir. Geri çağırma, bir uygulamanın bir cihazı bulduğunda ve kullanıcının seçimini girmesi için bir iletişim kutusu açmaya hazır olduğunu gösterir.
Uygulama herhangi bir cihaz bulamazsa geri arama bir hata mesajı döndürür.
Android 13 (API düzeyi 33) ve sonraki sürümleri çalıştıran cihazlarda:
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.
});
Android 12L (API düzeyi 32) ve önceki sürümleri (desteği sonlandırılmış) çalıştıran cihazlarda:
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);
Kullanıcıların ne tür cihazlara bağlanmak istediklerini seçmelerine olanak tanımak için onAssociationPending() işlevindeki intentSender parametresiyle bir tercih etkinliği başlatın. Bu işlemin sonuçları, tercihler etkinliğinizin onActivityResult() işlevindeki parçaya geri gönderilir. Bu, kullanıcı sonuca göre bir seçim yaptığında
sizi günceller. Ardından, seçili cihaza erişebilirsiniz. Kullanıcı bir Bluetooth cihazı seçtiğinde, gönderilen sonuç bir BluetoothDevice nesnesi olur.
Benzer şekilde, onAssociationPending() işlevi, kullanıcının bir Bluetooth LE cihazı seçtiğini algıladığında android.bluetooth.le.ScanResult nesnesini bekleyin. Kablosuz cihazlarda android.net.wifi.ScanResult nesnesi beklenir.
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);
}
}
Cihazları belirtebilen ve türe göre listeleyebilen filtrelerle tamamlayıcı cihaz eşlemeyi uygulamak için aşağıdaki örneklere bakın:
Android 13 (API düzeyi 33) ve sonraki sürümleri çalıştıran cihazlarda:
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 düzeyi 32) ve önceki sürümleri (desteği sonlandırılmış) çalıştıran cihazlarda:
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);
}
}
}
Tamamlayıcı cihaz profilleri
Android 12 (API düzeyi 31) ve sonraki sürümlerdeki iş ortağı uygulamaları, kol saatine bağlanırken tamamlayıcı cihaz profillerini kullanabilir. Daha fazla bilgi için Wear OS'te izin isteme rehberine bakın.
Tamamlayıcı uygulamaları açık tutun
Android 12 (API düzeyi 31) ve sonraki sürümlerde, bir tamamlayıcı cihaz kapsama alanı içindeyken tamamlayıcı uygulamanızın çalışmaya devam etmesine yardımcı olacak ek API'ler kullanabilirsiniz. Bu API'ler aşağıdakileri yapmanıza olanak tanır:
Kapsama alanında bir tamamlayıcı cihaz olduğunda uygulamanızı uyandırın.
Ayrıntılar için
CompanionDeviceManager.startObservingDevicePresence()sayfasına göz atın.Tamamlayıcı cihaz kapsama alanında kaldığı sürece uygulama işleminin çalışmaya devam edeceğini garanti eder.
Ayrıntılar için
CompanionDeviceService.onDeviceAppeared()sayfasına göz atın.