com.samsung.android.sdk.healthdata

Class HealthPermissionManager



  • public class HealthPermissionManager
    extends Object
    This class requests permission to read or write health data for the specific health data type.
    Note, HealthConstants.HealthDocument can be accessed with the instant permission. See acquring instant data permission.

    Requesting Permission

    An application can access health data only if the user consents. Permission for data access can be requested by each data type and the permission type (read or write).

       public class MainActivity extends Activity {
      
           // The state of connection
           private HealthDataStore mStore;
           Set<PermissionKey> mKeys = new HashSet<PermissionKey>();
      
           private static final String APP_TAG = "MyApp";
      
           public void requestPermission() {
      
               // Acquire permission
               HealthPermissionManager pmsManager = new HealthPermissionManager(mStore);
               mKeys.add(new PermissionKey(Exercise.HEALTH_DATA_TYPE, PermissionType.READ));
               mKeys.add(new PermissionKey(Exercise.HEALTH_DATA_TYPE, PermissionType.WRITE));
               mKeys.add(new PermissionKey(StepDailyTrend.HEALTH_DATA_TYPE, PermissionType.READ));
      
               try {
                   pmsManager.requestPermissions(mKeys, MainActivity.this).setResultListener(mPermissionListener);
               } catch (Exception e) {
                   Log.d(APP_TAG, "requestPermissions() fails");
               }
           }

    If requestPermissions() succeeds, the permission UI is popped up on the device.
    The user can check and allow each data type's permission with scrolling down.

    If the user allows permission items on the permission UI and select "DONE", its result is sent to PermissionResult and you can check whether the user allows the data access or not.

           private final HealthResultHolder.ResultListener<PermissionResult> mPermissionListener =
               new HealthResultHolder.ResultListener<PermissionResult>() {
      
               @Override
               public void onResult(PermissionResult result) {
      
                   Map<PermissionKey, Boolean> resultMap = result.getResultMap();
      
                   if (resultMap.values().contains(Boolean.FALSE)) {
                       Log.d(APP_TAG, "All required permissions are not granted.");
                   } else {
                       Log.d(APP_TAG, "All required permissions are granted.");
                       //Access health data
                   }
               }
           };
       }

    Specifying Permission in Manifest

    Not only calling permission related APIs, but specifying permission in the manifest file is required.
    The declared permission items in the application's manifest are shown on "Samsung Health > Settings > Data permissions > [YourApp]".

    Manifest below contains two data permissions to read and one data permission to write health data. Use the semicolon (;) to declare multiple data types.

       <manifest . . . >
           <application . . . >
               <meta-data android:name="com.samsung.android.health.permission.read"
                          android:value="com.samsung.health.exercise;com.samsung.shealth.step_daily_trend"/>
               <meta-data android:name="com.samsung.android.health.permission.write"
                          android:value="com.samsung.health.exercise"/>
           </application>
       </manifest>

    The constant value of the required data type can be checked as shown below.

    1. Find its HEALTH_DATA_TYPE in API Reference.
      E.g. if the data type is HealthConstants.Exercise, you'll meet the following description.

    2. Use the constant value, "com.samsung.health.exercise", for a permission declaration in your app's manifest file.


    Guidelines for Permission Request

    Acquiring permission from the user is essential to access health data but too frequent requests of permission can annoy the user. Here are guidelines that help you to find a solution for the permission request.

    Permission needs to be requested in the following cases.

    • When your application connects to Samsung Health at the first time
    • If there is a menu that connects to Samsung Health in your application and the user selects it

    And avoid requesting permission in the following cases.

    • When your application goes on the background
    • Frequent requests of permission until the user grants
      (an occasional nudge is fine)

    See the privacy section of Programming Guide for more information.

    Since:
    1.0.0
    • Constructor Detail

      • HealthPermissionManager

        public HealthPermissionManager(HealthDataStore store)
        Constructs and initializes an instance of HealthPermissionManager.
        Parameters:
        store - The successful connection to the health data store.
        Since:
        1.0.0
    • Method Detail

      • isPermissionAcquired

        public Map<HealthPermissionManager.PermissionKey,Boolean> isPermissionAcquired(Set<HealthPermissionManager.PermissionKey> permissionKeys)
        Checks whether the specified permissions are acquired.
        Parameters:
        permissionKeys - The set of permission keys to check acquisition
        Returns:
        The result map representing whether the specified permissions are acquired. The permission state for the specific permission key can be retrieved by Map.get(Object) as the following example.

           public class HealthPermissionManagerExample {
          
               // The state of connection
               private HealthDataStore mStore;
          
               private static final String APP_TAG = "MyApp";
          
               private void CheckPermissions() {
                   HealthPermissionManager pmsManager = new HealthPermissionManager(mStore);
          
                   Set<HealthPermissionManager.PermissionKey> keys =
                       new HashSet<HealthPermissionManager.PermissionKey>();
                   HealthPermissionManager.PermissionKey key1 = new HealthPermissionManager.PermissionKey(
                       HealthConstants.BloodGlucose.HEALTH_DATA_TYPE,
                       HealthPermissionManager.PermissionType.READ);
                   keys.add(key1);
                   HealthPermissionManager.PermissionKey key2 = new HealthPermissionManager.PermissionKey(
                       HealthConstants.BloodPressure.HEALTH_DATA_TYPE,
                       HealthPermissionManager.PermissionType.READ);
                   keys.add(key2);
          
                   try {
                       Map resultMap = pmsManager.isPermissionAcquired(keys);
          
                       if(resultMap.get(key1) == Boolean.TRUE) {
                           Log.d(APP_TAG, "You can read the blood glucose data type.");
                       } else {
                           Log.d(APP_TAG, "There is no permission to read the blood glucose data type.");
                       }
          
                       if(resultMap.get(key2) == Boolean.TRUE) {
                           Log.d(APP_TAG, "You can read the blood pressure data type.");
                       } else {
                           Log.d(APP_TAG, "There is no permission to read the blood pressure data type.");
                       }
                   } catch (Exception e) {
                       Log.d(APP_TAG, "Check the connection.");
                   }
              }
           }

        Throws:
        IllegalArgumentException - If the permissionKeys is invalid
        IllegalStateException - If the connection to the health data store is invalid or a remote-invocation error occurs on the connection
        Since:
        1.0.0