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.

To use companion device profiles, companion apps must meet the following requirements:

  • Manage a companion device (for example, a smartwatch).
  • Have app features or call Android APIs that require all the permissions defined for the companion device profile.

Each companion device profile corresponds to an Android role. For more information about the permissions and corresponding Android role of each profile, see companion device profiles for third-party apps.

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 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.

Watch device profile dialog prompt

Figure 1. Dialog requesting permissions for the watch device profile.

When a user clears the package data in Settings or removes all devices in the companion app, CDM revokes the profile while the app isn't running in the foreground nor has a foreground service running. Revoking the profile also revokes all defined permissions for the profile.

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.

Companion device profiles for third-party apps

Watch profile

The watch profile is introduced in Android 12.

The following table describes the defined permissions for the COMPANION_DEVICE_WATCH device profile 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
  • 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
  • Be a connected device using Bluetooth and/or Wi-Fi
  • Has a screen that displays SMS messages
  • Provide a user-facing SMS experience
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
  • 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
  • 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
  • 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
  • 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)

Glasses profile

The Glasses profile is introduced in Android 14.

The following table describes the defined permissions for the COMPANION_DEVICE_GLASSES device profile and the requirements for using them.

Permissions Companion app and device requirements
Notifications

BIND_NOTIFICATION_LISTENER_SERVICE

POST_NOTIFICATIONS
  • 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.
  • Posts phone notifications for device management, for example, when a glasses device is connected or when a specific feature is enabled.
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
  • Be a connected device using Bluetooth and/or Wi-Fi
  • Has a screen that displays SMS messages
  • Provide a user-facing SMS experience
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
Microphone
  • Be a connected device using Bluetooth and/or Wi-Fi
  • Has a display screen
  • Provides a user-facing microphone experience on the glasses
Nearby devices
  • Be a connected device using Bluetooth and/or Wi-Fi
  • Has a display screen
  • Provides a user-facing pairing/connecting experience on the glasses
Managing 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)

Implementation

For third-party developers implementing a companion app that requests the DEVICE_PROFILE_WATCH profile, do the following:

  1. Call the setDeviceProfile method.

  2. Pass in a profile (for example, DEVICE_PROFILE_WATCH when building AssociationRequest.

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 user consent dialog for users.

  1. Retrieve the certificate using the following command:

    keytool  -printcert -jarfile PATH/TO/APK
    
  2. 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>
    
  3. Use AssociationRequest to make an association request to a single companion device.

Validation

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