Companion Device Profiles

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
Notifications `BIND_NOTIFICATION_LISTENER_SERVICE`	Be a connected device using Bluetooth and/or Wi-Fi Has a screen capable of displaying notifications (devices that use haptics instead of a screen are excluded) Provides a user-facing notification experience, for example, displaying phone notifications on the companion device screen
Phone `phone`	Be a connected device using Bluetooth and/or Wi-Fi Has a built-in microphone and speaker that enables voice conversation Has a screen that displays caller info Provides a user-facing phone calling experience (the companion app bridges phone calls)
SMS `sms`	Be a connected device using Bluetooth and/or Wi-Fi Has a screen that displays SMS messages Provide a user-facing SMS experience
Contacts `contacts`	Be a connected device using Bluetooth and/or Wi-Fi Has a display screen Uses contact information as part of the calling or messaging experience
Calendar `calendar`	Be a connected device using Bluetooth and/or Wi-Fi Has a display screen Provide a user-facing calendar experience on the watch
Nearby devices `nearby_devices`	Be a connected device using Bluetooth and/or Wi-Fi Has a display screen Provide a user-facing pairing/connecting experience on the watch
eSIM provisioning `USE_ICC_AUTH_WITH_DEVICE_IDENTIFIER`	Be a connected device using Bluetooth and/or Wi-Fi Has a display screen Provide a user-facing experience that manages the subscriber's services from the carrier on the watch
Managing ongoing calls `MANAGE_ONGOING_CALLS`	Be a connected device using Bluetooth and/or Wi-Fi Has a built-in microphone and speaker that enables voice conversation Has a screen that displays caller info Provides a user-facing phone calling experience (the companion app bridges phone calls)

Getting access

For apps to gain access to companion device profiles without displaying the user consent dialogs, 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 building AssociationRequest.

Validation

To test the behavior of the companion device profile feature, use the CTS tests in cts/tests/tests/companion/.