Companion device profile, introduced in Android 12, is a feature that allows companion apps to request a set of permissions specific to the type of the companion device, for example, a smartwatch. Using a companion device profile simplifies the enrollment process by allowing apps to display a single prompt to users on their mobile devices to request a defined set of permissions instead of multiple prompts requesting permissions individually. This can allow for a more streamlined setup experience and better opt-in rates for companion apps.
Use of companion devices profiles are only available to device manufacturers that have companion devices. For companion devices to gain access to the feature, they must meet the requirements and be approved.
The following companion device profiles types are available in
Android 12: COMPANION_DEVICE_WATCH
.
For more information about companion devices, see Companion device pairing.
Device behavior
This section describes device behavior when companion device profiles are used.
When a user accepts an app's request to create an association with a companion
device, the
CompanionDeviceManager
(CDM) service waits for the companion device to connect, and when it connects,
the CDM assigns the device profile role (for example, watch) to the companion
app, granting all the permissions defined for that specified profile role.
Figure 1 shows an example of an app requesting permissions for the
COMPANION_DEVICE_WATCH
device profile.
Figure 1. Dialog requesting permissions for the watch device profile.
When the association between an app and the companion device is removed, for example when the data for a package is cleared or when a device is forgotten, CDM revokes the device profile role for the app, which removes all the defined permissions for the profile role from the app.
After a user accepts an app's request to grant permissions for a particular device profile, the user can revoke individual permissions that were granted. When a permission is revoked by a user, the app remains associated with the companion device but certain features might become unavailable. If the permission is required for the app to function, the app must request the permission through a normal permission request.
Requirements
For a companion app to gain access to the companion device profile API, the app must meet the following requirements:
- Have a companion device (for example, a smartwatch).
- Have a legitimate reason for requiring the permissions defined for the companion device profile.
Watch companion device profile requirements
The following table describes the defined permissions for the
COMPANION_DEVICE_WATCH
device profile role and the requirements for using them.
Permissions | Companion app and device requirements |
---|---|
NotificationsBIND_NOTIFICATION_LISTENER_SERVICE |
|
Phonephone |
|
SMS
sms |
|
Contacts
contacts |
|
Calendar
calendar |
|
Nearby devices
nearby_devices |
|
eSIM provisioning
USE_ICC_AUTH_WITH_DEVICE_IDENTIFIER |
|
Managing ongoing calls
MANAGE_ONGOING_CALLS |
|
Getting access
For apps to gain access to companion device profiles, they must be approved and added to an allowlist. When a request to be added to the allowlist is received, the Android team reviews the app to make sure that it meets the requirements for the corresponding companion device profile.
Implementation
For device manufacturers implementing a companion app with a specific device, use the following required Android system configs to certify the companion app, which allows the app to skip displaying the CDM prompt for users.
Retrieve the certificate using the following command:
keytool -printcert -jarfile PATH/TO/APK
Replace the package name and certificate as shown in the following sample input in the config file:
<!-- A list of packages managing companion device(s) by the same manufacturers as the main device. It will not create the association without prompting if the association has been called multiple times in a short period. Note that config_companionDeviceManagerPackage and config_companionDeviceCerts are parallel arrays. --> <string-array name="config_companionDevicePackages" translatable="false"> <item>YOUR_COMPANION_APP_PACKAGE_NAME</item> </string-array> <!-- A list of SHA256 Certificates managing companion device(s) by the same manufacturers as the main device. It will fall back to showing a prompt if the association has been called multiple times in a short period. Note that config_companionDeviceCerts and config_companionDeviceManagerPackage are parallel arrays. Example: "1A:2B:3C:4D" --> <string-array name="config_companionDeviceCerts" translatable="false"> <item>YOUR_COMPANION_APP_CERTIFICATE</item> </string-array>
Use
AssociationRequest
to make an association request to a single companion device.
For third-party developers implementing a companion app that requests the
DEVICE_PROFILE_WATCH
profile, do the following:
- Call the
setDeviceProfile
method. - Pass in the
DEVICE_PROFILE_WATCH
profile when buildingAssociationRequest
.
Validation
To test the behavior of the companion device profile feature, use the following CTS tests: