CompanionDeviceManager

public final class CompanionDeviceManager
extends Object

java.lang.Object
   ↳ android.companion.CompanionDeviceManager

System level service for managing companion devices See this guide for a usage example.

To obtain an instance call Context#getSystemService(Context.COMPANION_DEVICE_SERVICE) Then, call associate(android.companion.AssociationRequest, android.companion.CompanionDeviceManager.Callback, android.os.Handler) to initiate the flow of associating current package with a device selected by user.

Summary

Nested classes

class CompanionDeviceManager.Callback

Callback for applications to receive updates about and the outcome of AssociationRequest issued via associate() call. 

Constants

String EXTRA_ASSOCIATION

Extra field name for the AssociationInfo object, included into Intent which application receive in Activity#onActivityResult(int, int, Intent) after the application's AssociationRequest was successfully processed and an association was created.

String EXTRA_DEVICE

This constant was deprecated in API level Tiramisu. use EXTRA_ASSOCIATION instead.

Public methods

void associate(AssociationRequest request, Executor executor, CompanionDeviceManager.Callback callback)

Request to associate this app with a companion device.

void associate(AssociationRequest request, CompanionDeviceManager.Callback callback, Handler handler)

Request to associate this app with a companion device.

void disassociate(int associationId)

Remove an association.

void disassociate(String deviceMacAddress)

This method was deprecated in API level Tiramisu. use disassociate(int)

List<String> getAssociations()

This method was deprecated in API level Tiramisu. use getMyAssociations()

List<AssociationInfo> getMyAssociations()

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest
boolean hasNotificationAccess(ComponentName component)

This method was deprecated in API level Tiramisu. Use NotificationManager#isNotificationListenerAccessGranted(ComponentName) instead.

void requestNotificationAccess(ComponentName component)

Request notification access for the given component.

void startObservingDevicePresence(String deviceAddress)

Register to receive callbacks whenever the associated device comes in and out of range.

void stopObservingDevicePresence(String deviceAddress)

Unregister for receiving callbacks whenever the associated device comes in and out of range.

Inherited methods

Constants

EXTRA_ASSOCIATION

Added in Android Tiramisu 
public static final String EXTRA_ASSOCIATION

Extra field name for the AssociationInfo object, included into Intent which application receive in Activity#onActivityResult(int, int, Intent) after the application's AssociationRequest was successfully processed and an association was created.

Constant Value: "android.companion.extra.ASSOCIATION"

EXTRA_DEVICE

Added in API level 26
Deprecated in API level Tiramisu 
public static final String EXTRA_DEVICE

This constant was deprecated in API level Tiramisu.
use EXTRA_ASSOCIATION instead.

A device, returned in the activity result of the IntentSender received in Callback#onDeviceFound Type is:

Constant Value: "android.companion.extra.DEVICE"

Public methods

associate

public void associate (AssociationRequest request, 
                Executor executor, 
                CompanionDeviceManager.Callback callback)

Request to associate this app with a companion device.

Note that before creating establishing association the system may need to show UI to collect user confirmation.

If the app needs to be excluded from battery optimizations (run in the background) or to have unrestricted data access (use data in the background) it should declare use of Manifest.permission.REQUEST_COMPANION_RUN_IN_BACKGROUND and Manifest.permission.REQUEST_COMPANION_USE_DATA_IN_BACKGROUND in its AndroidManifest.xml respectively. Note that these special capabilities have a negative effect on the device's battery and user's data usage, therefore you should request them when absolutely necessary.

Application can use getMyAssociations() for retrieving the list of currently AssociationInfo objects, that represent their existing associations. Applications can also use disassociate(int) to remove an association, and are recommended to do when an association is no longer relevant to avoid unnecessary battery and/or data drain resulting from special privileges that the association provides

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Parameters
request AssociationRequest: A request object that describes details of the request. This value cannot be null.
executor Executor: The executor which will be used to invoke the callback. This value cannot be null.
callback CompanionDeviceManager.Callback: The callback used to notify application when the association is created. This value cannot be null.

associate

Added in API level 26 
public void associate (AssociationRequest request, 
                CompanionDeviceManager.Callback callback, 
                Handler handler)

Request to associate this app with a companion device.

Note that before creating establishing association the system may need to show UI to collect user confirmation.

If the app needs to be excluded from battery optimizations (run in the background) or to have unrestricted data access (use data in the background) it should declare use of Manifest.permission.REQUEST_COMPANION_RUN_IN_BACKGROUND and Manifest.permission.REQUEST_COMPANION_USE_DATA_IN_BACKGROUND in its AndroidManifest.xml respectively. Note that these special capabilities have a negative effect on the device's battery and user's data usage, therefore you should request them when absolutely necessary.

Application can use getMyAssociations() for retrieving the list of currently AssociationInfo objects, that represent their existing associations. Applications can also use disassociate(int) to remove an association, and are recommended to do when an association is no longer relevant to avoid unnecessary battery and/or data drain resulting from special privileges that the association provides

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Parameters
request AssociationRequest: A request object that describes details of the request. This value cannot be null.
callback CompanionDeviceManager.Callback: The callback used to notify application when the association is created. This value cannot be null.
handler Handler: The handler which will be used to invoke the callback. This value may be null.

disassociate

public void disassociate (int associationId)

Remove an association.

Any privileges provided via being associated with a given device will be revoked

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Parameters
associationId int: id of the association to be removed.

disassociate

Added in API level 26
Deprecated in API level Tiramisu 
public void disassociate (String deviceMacAddress)

This method was deprecated in API level Tiramisu.
use disassociate(int)

Remove the association between this app and the device with the given mac address.

Any privileges provided via being associated with a given device will be revoked

Consider doing so when the association is no longer relevant to avoid unnecessary battery and/or data drain resulting from special privileges that the association provides

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Parameters
deviceMacAddress String: the MAC address of device to disassociate from this app This value cannot be null.

getAssociations

Added in API level 26
Deprecated in API level Tiramisu 
public List<String> getAssociations ()

This method was deprecated in API level Tiramisu.
use getMyAssociations()

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Returns
List<String> a list of MAC addresses of devices that have been previously associated with the current app are managed by CompanionDeviceManager (ie. does not include devices managed by application itself even if they have a MAC address). This value cannot be null.

getMyAssociations

public List<AssociationInfo> getMyAssociations ()

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Returns
List<AssociationInfo> a list of associations that have been previously associated with the current app. This value cannot be null.

hasNotificationAccess

Added in API level 26
Deprecated in API level Tiramisu 
public boolean hasNotificationAccess (ComponentName component)

This method was deprecated in API level Tiramisu.
Use NotificationManager#isNotificationListenerAccessGranted(ComponentName) instead.

Check whether the given component can access the notifications via a NotificationListenerService Your app must have an association with a device before calling this API

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Parameters
component ComponentName: the name of the component
Returns
boolean whether the given component has the notification listener permission

requestNotificationAccess

Added in API level 26 
public void requestNotificationAccess (ComponentName component)

Request notification access for the given component. The given component must follow the protocol specified in NotificationListenerService Only components from the same package as the calling app are allowed. Your app must have an association with a device before calling this API

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Parameters
component ComponentName

startObservingDevicePresence

Added in API level 31 
public void startObservingDevicePresence (String deviceAddress)

Register to receive callbacks whenever the associated device comes in and out of range. The provided device must be associated with the calling app before calling this method. Caller must implement a single CompanionDeviceService which will be bound to and receive callbacks to CompanionDeviceService#onDeviceAppeared and CompanionDeviceService#onDeviceDisappeared. The app doesn't need to remain running in order to receive its callbacks. Calling app must declare uses-permission Manifest.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE. Calling app must check for feature presence of PackageManager#FEATURE_COMPANION_DEVICE_SETUP before calling this API. For Bluetooth LE devices this is based on scanning for device with the given address. For Bluetooth classic devices this is triggered when the device connects/disconnects. WiFi devices are not supported. If a Bluetooth LE device wants to use a rotating mac address, it is recommended to use Resolvable Private Address, and ensure the device is bonded to the phone so that android OS is able to resolve the address.
Requires Manifest.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE

Parameters
deviceAddress String: a previously-associated companion device's address This value cannot be null.
Throws
DeviceNotAssociatedException if the given device was not previously associated with this app.

stopObservingDevicePresence

Added in API level 31 
public void stopObservingDevicePresence (String deviceAddress)

Unregister for receiving callbacks whenever the associated device comes in and out of range. The provided device must be associated with the calling app before calling this method. Calling app must declare uses-permission Manifest.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE. Calling app must check for feature presence of PackageManager#FEATURE_COMPANION_DEVICE_SETUP before calling this API.
Requires Manifest.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE

Parameters
deviceAddress String: a previously-associated companion device's address This value cannot be null.
Throws
DeviceNotAssociatedException if the given device was not previously associated with this app.