cariva-exercise-sdk

React Native SDK for reading exercise and activity data from Android Health Connect.

Platform Support

| Platform | Status | |----------|--------| | Android | Supported (Health Connect) | | iOS | Out of scope for this release |

Requirements

• React Native 0.68+ (New Architecture / Turbo Module compatible)
• Android API level 26+
• Health Connect installed on the device (or available through Play Services on Android 14+)

Installation

1. Install the package

# npm
npm install cariva-exercise-sdk

# yarn
yarn add cariva-exercise-sdk

2. Android — AndroidManifest.xml

The SDK ships its own manifest with Health Connect permissions, but you must also declare two additional entries in your app's AndroidManifest.xml:

2a. Add the <queries> block (package visibility)

Inside the root <manifest> element:

<queries>
  <package android:name="com.google.android.apps.fitness" />
  <package android:name="com.google.android.apps.healthdata" />
  <package android:name="com.google.android.healthconnect.controller" />
</queries>

2b. Add the Health Connect permission rationale activities

Inside the <application> element:

<!-- Required by Health Connect: shown when user taps "Privacy policy" in permissions dialog -->
<activity
  android:name="com.carivaexercisesdk.HealthConnectPermissionsRationaleActivity"
  android:exported="true">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
  </intent-filter>
</activity>

<!-- Required by Health Connect: shown from Android Settings > App permissions -->
<activity
  android:name="com.carivaexercisesdk.HealthConnectPermissionUsageActivity"
  android:exported="true"
  android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
  <intent-filter>
    <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
    <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
  </intent-filter>
</activity>

Note: These activities are part of the Health Connect compliance requirement. The app will still build without them, but Health Connect permission management will not work correctly.

3. iOS

No additional setup is required. The SDK is a no-op on iOS.

Quick Start

import {
  connect,
  getExerciseData,
  setAllowDatasource,
  getAllowDatasource,
} from 'cariva-exercise-sdk';

// 1. Connect and request permissions
const status = await connect({
  onMissingApp: 'status',
  requestPermission: true,
  permissionScope: ['steps', 'calories'],
});

if (!status.ready) {
  console.log('Next action required:', status.nextAction);
  // e.g. 'INSTALL_HEALTH_CONNECT' | 'REQUEST_PERMISSION' | ...
  return;
}

// 2. Fetch exercise data
const data = await getExerciseData({
  sinceMillis: Date.now() - 7 * 24 * 60 * 60 * 1000, // last 7 days
  untilMillis: Date.now(),
  type: 'all',
  bucketPeriod: 'daily',
});

console.log('Records:', data.records);
console.log('Total steps:', data.totalSteps);

API Reference

connect(options?)

Checks Health Connect availability and optionally requests permissions.

type ConnectOptions = {
  onMissingApp?: 'status' | 'open';   // 'open' navigates to Play Store
  requestPermission?: boolean;          // default: false
  permissionScope?: Array<'steps' | 'activetimes' | 'calories' | 'distances'>;
};

type ConnectResult = {
  ready: boolean;
  healthConnectInstalled: boolean;
  googleFitInstalled: boolean;
  healthConnectStatus: 'AVAILABLE' | 'PROVIDER_UPDATE_REQUIRED' | 'UNAVAILABLE' | 'UNKNOWN';
  hasPermissions: boolean;
  nextAction:
    | 'INSTALL_HEALTH_CONNECT'
    | 'INSTALL_GOOGLE_FIT'
    | 'UPDATE_HEALTH_CONNECT'
    | 'REQUEST_PERMISSION'
    | 'NONE';
  requestedPermissions?: string[];
};

| Option | Type | Default | Description | |--------|------|---------|-------------| | onMissingApp | 'status' \| 'open' | 'status' | 'open' opens Play Store for the missing app | | requestPermission | boolean | false | Trigger the Health Connect permission dialog | | permissionScope | PermissionScope[] | all scopes | Limit which permissions are requested |

getExerciseData(options)

Reads aggregated exercise data from Health Connect.

type GetExerciseDataOptions = {
  sinceMillis: number;
  untilMillis: number;
  type?: 'steps' | 'activetimes' | 'calories' | 'distances' | 'all'; // default: 'all'
  bucketPeriod?: 'hourly' | 'daily';                                    // default: 'hourly'
};

type ExerciseData = {
  totalSteps: number;
  totalKcal: number;
  totalDistanceMeters: number;
  totalActiveTimeMillis: number;
  timeZone: string;
  records: UnifiedIntervalRecord[];
  warnings?: string[];
  integrity?: {
    projectionPreserved: boolean;
    roundingScale: number;
  };
};

Periods longer than 90 days reject with error code E_INVALID_PERIOD.

setAllowDatasource(config)

Configures which data sources to exclude from results.

type DatasourceType = 'manual_input' | 'device' | 'app' | 'unknown';

type DatasourceConfig = {
  blacklist: DatasourceType[];
};

// Example: exclude manually-entered data
await setAllowDatasource({ blacklist: ['manual_input'] });

getAllowDatasource()

Returns the current datasource blacklist configuration.

const config = await getAllowDatasource();
// => { blacklist: ['manual_input'] }

Unified Record Schema

Every record in data.records follows this shape regardless of the type queried:

type UnifiedIntervalRecord = {
  steps: number;
  activeCalories: number;
  activeCaloriesUnit: 'kcal';
  distance: number;
  distanceUnit: 'km';
  activeTime: number;
  activeTimeUnit: 'milliseconds';
  startDate: string; // ISO offset string, e.g. "2026-02-16T08:00:00+07:00"
  endDate: string;
};

Example record:

{
  "steps": 1300,
  "activeCalories": 60.2,
  "activeCaloriesUnit": "kcal",
  "distance": 1.0,
  "distanceUnit": "km",
  "activeTime": 1200000,
  "activeTimeUnit": "milliseconds",
  "startDate": "2026-02-16T08:30:00+07:00",
  "endDate": "2026-02-16T09:00:00+07:00"
}

Overlap Handling

The SDK automatically de-duplicates overlapping Health Connect records:

| Metric | Strategy | |--------|----------| | steps | Source priority: device > app > unknown > manual_input | | activetimes, calories, distances | Proportional-by-time allocation |

Integrity & Warnings

data.warnings is an optional string array that appears when non-fatal anomalies are detected (e.g. value sanitization or boundary guard signals).

data.integrity is always present and describes the projection audit:

{
  projectionPreserved: boolean; // true if totals were preserved after overlap correction
  roundingScale: number;        // rounding precision applied
}

React Native UI pattern (non-blocking):

const hasWarnings = !!data.warnings?.length;

return (
  <View>
    {hasWarnings && <Text>Data warnings available</Text>}
    <Text>{`Projection preserved: ${data.integrity?.projectionPreserved}`}</Text>
  </View>
);

Full Example

import { connect, getExerciseData, setAllowDatasource } from 'cariva-exercise-sdk';

async function loadHealthData() {
  // Exclude manual entries
  await setAllowDatasource({ blacklist: ['manual_input'] });

  // Connect with minimal permission scope
  const status = await connect({
    onMissingApp: 'status',
    requestPermission: true,
    permissionScope: ['steps', 'calories'],
  });

  if (!status.ready) {
    console.warn('Health Connect not ready. Next action:', status.nextAction);
    return null;
  }

  // Query last 24 hours in hourly buckets
  const data = await getExerciseData({
    sinceMillis: Date.now() - 24 * 60 * 60 * 1000,
    untilMillis: Date.now(),
    type: 'all',
    bucketPeriod: 'hourly',
  });

  return data;
}