Migrate from version 2.x.x to 4.0.0

Overview

As the last update v4, we make some changes to improve the experience of integrate the ROOK SDK inside your react native apps.

Requirements

• Android
  • android >= 29.0
  • targetSDK >= 36.0
  • kotlin >= 2.1.21
• iOS
  • 26.0 < = XCode > 26.4.0

Migrations

Configuration Migration Guide

The updated useRookConfiguration hook removes several source-specific methods in favor of a cleaner interface. Management of specific health sources is now handled through the SDKDataSource enum where applicable.

Interface Comparition

const useRookConfiguration = () => {
    ready: boolean;
    getUserID: () => Promise<string>;
    updateUserID: (userID: string) => Promise<boolean>;
-   clearUserID: (sources: SDKDataSource[]) => Promise<boolean>;
    syncUserTimeZone: () => Promise<boolean>;
    removeUserFromRook: (sources: SDKDataSource[]) => Promise<boolean>;
-   enableAppleHealthSync: () => Promise<boolean>;
-   disableAppleHealthSync: () => Promise<boolean>;
-   isAppleHealthSyncEnabled: () => Promise<boolean>;
-   scheduleAndroidYesterdaySync: () => Promise<boolean>;
-   enableSamsungSync: () => Promise<boolean>;
-   disableSamsungSync: () => Promise<boolean>;
-   isSamsungSyncEnabled: () => Promise<boolean>;
  }

---

Key Changes

• Platform-Specific Hooks: The enable/disable methods for Apple and Samsung have been moved to their own specialized hooks to improve modularity and reduce the configuration hook's footprint.

• Use useRookAppleHealth for iOS-specific synchronization.

• Use useRookSamsungHealth for Samsung-specific synchronization.

• Centralized Cleanup: clearUserID has been deprecated; use removeUserFromRook with the SDKDataSource enum for granular data removal.

Implementation Example

Old Approach:

const { enableAppleHealthSync } = useRookConfiguration();

New Approach (Migration):

const { enableAppleHealthSync } = useRookAppleHealth();

---

Quick Reference: SDKDataSource Enum

When performing administrative tasks like removing a user, use the new enum:

await removeUserFromRook([SDKDataSource.SAMSUNG_HEALTH, SDKDataSource.HEALTH_CONNECT]);

Permissions Migration Guide

This update introduces a more type-safe and modular approach to permission handling. We have replaced the generic PermissionsType string union with specific Enums for Apple and Samsung, and streamlined the hook to be more platform-aware.

Interface & Type Changes

- type PermissionsType = "appleExerciseTime" | "appleMoveTime" | ...;
- type CheckPermissionsParam = { type: PermissionsType; };

+ enum AppleHealthPermission { APPLE_EXERCISE_TIME = 'appleExerciseTime', ... }
+ enum SamsungHealthPermission { ACTIVITY_SUMMARY = 'ACTIVITY_SUMMARY', ... }

  const useRookPermissions = () => {
    ready: boolean;
-   checkAvailability: () => Promise<CheckAvailabilityResponse>;
+   checkHealthConnectAvailability: () => Promise<CheckAvailabilityResponse>;
-   checkBackgroundReadStatus: () => Promise<BackgroundStatus>;
+   checkHealthConnectBackgroundReadStatus: () => Promise<BackgroundStatus>;
-   appleHealthHasPermissions: (param?: CheckPermissionsParam) => Promise<PermissionStatus>;
+   appleHealthHasPermissions: (param: AppleHealthPermission) => Promise<PermissionStatus>;
    
    // ... Health Connect & Samsung methods ...

-   requestAllPermissions: () => Promise<RequestStatusPermissions>;
-   requestAllAppleHealthPermissions: () => Promise<RequestStatusPermissions>;
-   requestAllHealthConnectPermissions: () => Promise<RequestStatusPermissions>;
+   requestHealthConnectPermissions: () => Promise<RequestStatusPermissions>;
+   revokeHealthConnectPermissions: () => Promise<boolean>;
  }

---

Key Changes

• Removal of requestAllPermissions: To ensure a better user experience and comply with platform-specific privacy guidelines, the catch-all requestAllPermissions has been removed. You must now explicitly request permissions for the specific platform the user is interacting with (e.g., requestAppleHealthPermissions).
• Enum Integration: Permission types are now strictly defined via AppleHealthPermission and SamsungHealthPermission. This prevents runtime errors caused by typos in permission strings.
• Method Renaming: Generic availability methods have been renamed (e.g., checkAvailability → checkHealthConnectAvailability) to clarify which underlying service is being queried.
• New Utility: Added revokeHealthConnectPermissions to allow users to disconnect and clear data access directly from within your app.

Implementation Example

Old Approach (Generic):

await requestAllPermissions();

New Approach (Platform Specific):

// For iOS
await requestAppleHealthPermissions([AppleHealthPermission.STEP_COUNT, AppleHealthPermission.HEART_RATE]);

// For Android (Health Connect)
await requestHealthConnectPermissions();

---

Migration Checklist

1. Update Imports: Replace PermissionsType imports with the new Enums.
2. Platform Logic: Replace requestAllPermissions() calls with a conditional check that triggers the specific request for the active platform.
3. Check Availability: Update background status checks to use the new checkHealthConnect... naming convention.

Deprecation Notice: Summaries and Events Hooks

As part of our effort to simplify the SDK architecture, the specialized hooks useRookSummaries and useRookEvents have been deprecated.

All synchronization logic has been consolidated into a single, unified hook: useRookSync. This new hook acts as a centralized orchestrator for both Summaries (Physical, Sleep, Body) and Events across all supported platforms (Apple Health, Health Connect, and Samsung Health).

---

Migration Mapping

Old Hook	Old Method	New Unified Replacement (useRookSync)
useRookSummaries	syncSummaries()	sync(callback, params?)
useRookEvents	syncEvents()	syncEvents(params)

---

Key Features of useRookSync

The new sync method offers flexible execution modes based on the parameters provided:

1. Standard Sync (Default): If only a callback is provided, the SDK automatically syncs data from the last 29 days across all available native sources.
2. Granular Sync: By providing a date and source, you can target specific days.
3. Pillar-Specific Sync: You can filter by specific data pillars (Physical, Sleep, or Body) using the summary parameter.

---

Implementation Comparison

1. Synchronizing Summaries

Old Way (useRookSummaries):

const { syncSummaries } = useRookSummaries();
await syncSummaries(date);

New Unified Way (useRookSync):

const { sync } = useRookSync();

// Comprehensive sync for a specific date
sync((result) => console.log(result), { date: '2023-10-27' });

2. Synchronizing Events

Old Way (useRookEvents):

const { syncEvents } = useRookEvents();
await syncEvents(eventParams);

New Unified Way (useRookSync):

const { syncEvents } = useRookSync();

// Typed event synchronization
await syncEvents({
  date: '2023-10-27',
  event: 'HEART_RATE',
  sources: [SDKDataSource.APPLE_HEALTH]
});

---

Summary of Benefits

• Reduced Boilerplate: No need to initialize multiple hooks for different data types.
• Centralized Error Handling: All sync results are returned through a consistent SyncResult callback pattern.
• Platform Agnostic: The same sync method handles the underlying complexities of iOS and Android automatically.

Deprecation Notice: Variable Extraction

The hook useRookAppleHealthVariables has been deprecated. To provide a consistent experience across all platforms, we have introduced a unified hook: useRookVariables.

This new hook allows you to extract real-time data—such as steps and calories—from any supported source (Apple Health, Health Connect, or Samsung Health) using a single, cross-platform interface.

---

Migration Mapping

Old Hook	Old Method	New Unified Replacement (useRookVariables)
useRookAppleHealthVariables	getStepsToday()	getTodaySteps(SDKDataSource.APPLE_HEALTH)
useRookAppleHealthVariables	getCaloriesToday()	getTodayCalories(SDKDataSource.APPLE_HEALTH)

---

Key Improvements

• Cross-Platform Consistency: You no longer need separate logic for iOS and Android. Simply pass the appropriate SDKDataSource to the function.
• Centralized Readiness: The ready property ensures the SDK is initialized before you attempt to fetch real-time metrics.
• Standardized Returns: getTodayCalories returns a structured Calories object containing both active and basal energy, regardless of the platform.

---

Implementation Example

1. Fetching Today's Steps

Old Way (useRookAppleHealthVariables):

const { getStepsToday } = useRookAppleHealthVariables();
const steps = await getStepsToday();

New Unified Way (useRookVariables):

const { getTodaySteps } = useRookVariables();

// Explicitly define the source
const steps = await getTodaySteps(SDKDataSource.APPLE_HEALTH);

2. Fetching Today's Calories

New Unified Way (useRookVariables):

const { getTodayCalories } = useRookVariables();

const { active, basal } = await getTodayCalories(SDKDataSource.HEALTH_CONNECT);
console.log(`Burned ${active} active calories today.`);

---

Quick Reference: Calories Type

The getTodayCalories method returns a Promise resolving to the following structure:

type Calories = {
  active: number;
  basal: number;
}

Hook Renaming & Refactoring: useRookDataSources → useRookAPISources

The hook previously known as useRookDataSources has been renamed to useRookAPISources. This change reflects a clearer distinction between native device sources (handled by SDKDataSource) and cloud-based API sources (handled by APIDataSource).

In addition to the rename, several legacy methods have been removed to favor the more robust "V2" and "Authorizer" workflows.

Interface Comparison

- const useRookDataSources = () => {
+ const useRookAPISources = () => {
    ready: boolean;
-   getAvailableDataSources: (options?: { redirectURL?: string }) => Promise<DataSource[]>;
-   presentDataSourceView: (options?: { redirectURL?: string }) => Promise<boolean>;
-   revokeDataSource: (type: DataSourceType) => Promise<boolean>;
+   revokeDataSource: (userid: string, type: APIDataSource) => Promise<boolean>;
-   getAuthorizedDataSources: () => Promise<AuthorizedSources>;
-   getDataSourceAuthorizer: (props: DataSourceProps) => Promise<DataSourceAuthorizer>;
+   getDataSourceAuthorizer: (props: DataSourceProps) => Promise<DataSourceAuthorizer>;
-   getAuthorizedDataSourcesV2: () => Promise<AuthorizedSource[]>
+   getAuthorizedDataSourcesV2: (userid: string) => Promise<AuthorizedSource[]>
  };

---

Key Changes

• Hook Rename: useRookDataSources is now useRookAPISources.
• Method Simplification: Legacy methods getAvailableDataSources, presentDataSourceView, and the original getAuthorizedDataSources have been removed.
• Mandatory UserID: Methods like revokeDataSource and getAuthorizedDataSourcesV2 now require a userid parameter to ensure actions are mapped to the correct user context.
• New Enum (APIDataSource): A strictly typed enum replaces the older DataSourceType for cloud providers (Garmin, Oura, etc.).
• Updated DataSourceProps: When requesting an authorizer, you must now provide the userID and use the APIDataSource enum.

Implementation Example

Old Approach:

const { getAuthorizedDataSourcesV2 } = useRookDataSources();
const sources = await getAuthorizedDataSourcesV2();

New Approach:

const { getAuthorizedDataSourcesV2, revokeDataSource } = useRookAPISources();

// Fetching authorized sources with a required userID
const sources = await getAuthorizedDataSourcesV2("user_123");

// Revoking a specific source
await revokeDataSource("user_123", APIDataSource.FITBIT);

---

Migration Checklist

1. Search and Replace: Rename all instances of useRookDataSources to useRookAPISources.
2. Update Parameters: Ensure all calls to getAuthorizedDataSourcesV2 and revokeDataSource include the userid string.
3. Update Enums: Switch from string-based data source types to the APIDataSource enum.

Migration Guide: Android Background Steps

The useRookAndroidBackgroundSteps hook has been refined to focus exclusively on steps derived from the device's local hardware (accelerometer/pedometer). The method specifically tied to Health Connect has been removed from this hook.

Interface Comparison

  const useRookAndroidBackgroundSteps = () => {
    ready: boolean;
    isStepsAvailable: () => Promise<boolean>;
    enableBackgroundAndroidSteps: () => Promise<boolean>;
    disableBackgroundAndroidSteps: () => Promise<boolean>;
    isBackgroundAndroidStepsActive: () => Promise<boolean>;
    syncTodayAndroidStepsCount: () => Promise<string>;
-   syncTodayHealthConnectStepsCount: () => Promise<string>;
  };

---

Key Changes

• Removal of syncTodayHealthConnectStepsCount: This method has been removed to avoid redundancy and confusion between background hardware tracking and health platform data.
• Consolidation of Data Extraction: For all standard step and calorie queries—including those from Health Connect, Apple Health, and Samsung Health—you should now use the unified useRookVariables hook.

Recommended Migration Path

If you were previously using syncTodayHealthConnectStepsCount, you should migrate to the getTodaySteps method within the useRookVariables hook.

Old Approach:

const { syncTodayHealthConnectStepsCount } = useRookAndroidBackgroundSteps();
const steps = await syncTodayHealthConnectStepsCount();

New Unified Approach:

const { getTodaySteps } = useRookVariables();

// Use the SDKDataSource enum to specify Health Connect
const steps = await getTodaySteps(SDKDataSource.HEALTH_CONNECT);

---

Comparison of Use Cases

To ensure you are using the correct hook for your implementation, refer to the table below:

Feature	Hook to Use
Hardware Background Tracking	useRookAndroidBackgroundSteps
Health Connect Step Count	useRookVariables
Apple Health Step Count	useRookVariables
Samsung Health Step Count	useRookVariables

tip

Use useRookAndroidBackgroundSteps only when you need to extract steps directly from the Android device's accelerometer. This requires the "sticky" notification mentioned in the permissions guide. For all other data retrieval, useRookVariables is the preferred method.

Hook Update: useRookAppleHealth

The useRookAppleHealth hook has been simplified by consolidating background status checks. More importantly, the internal behavior has been enhanced: enabling background updates now automatically triggers a foreground sync to ensure your data is up-to-date as soon as the app is opened.

Interface Comparison

  const useRookAppleHealth = () => {
    ready: boolean;
    enableBackGroundUpdates: () => Promise<boolean>;
    disableBackGroundUpdates: () => Promise<boolean>;
-   isBackGroundForSummariesEnable: () => Promise<boolean>;
-   isBackGroundForEventsEnable: () => Promise<void>;
+   isBackgroundUpdatesEnabled: () => Promise<boolean>;
  };

---

Key Changes

• Consolidated Status Check: isBackGroundForSummariesEnable and isBackGroundForEventsEnable have been replaced by a single, unified method: isBackgroundUpdatesEnabled().
• Automatic Foreground Sync: When you call enableBackGroundUpdates(), the SDK now manages an automatic foreground synchronization. This means you no longer need to manually trigger a sync every time the app comes to the foreground if background updates are active.
• Improved Naming: Fixed the typo in "BackGround" and "Enable" to follow standard camelCase naming conventions (isBackgroundUpdatesEnabled).

Implementation Example

Old Approach:

const { isBackGroundForSummariesEnable } = useRookAppleHealth();
const active = await isBackGroundForSummariesEnable();

New Unified Approach:

const { enableBackGroundUpdates, isBackgroundUpdatesEnabled } = useRookAppleHealth();

// This call now handles both background registration AND foreground sync logic
await enableBackGroundUpdates();

const status = await isBackgroundUpdatesEnabled();

---

Integration Note

With the introduction of useRookSync, the automatic foreground sync managed by useRookAppleHealth ensures that the "latest" data is always prepared for the server, but this two are complementary and won't geneate collitions.

Migration Guide: Health Connect Background Sync

With the introduction of native background extraction and transmission support for Health Connect, we have simplified how data is synchronized on Android.

Deprecation of scheduleYesterdaySync

The method scheduleYesterdaySync (previously part of useRookConfiguration) is no longer supported.

Previously, syncing data in the background required a "sticky" notification and specific scheduling logic. This has been replaced by a more efficient, native background service that integrates directly with Android's WorkManager via Health Connect.

---

New Migration Path: useRookHealthConnect

To enable background synchronization, you no longer need to manually schedule daily tasks. Instead, follow these two steps:

1. Grant Permissions: Ensure the user has granted permissions via requestHealthConnectPermissions (found in useRookPermissions).
2. Enable the Service: Use the new useRookHealthConnect hook to trigger the native background task.

New Hook Interface: useRookHealthConnect

const useRookHealthConnect: () => {
  ready: boolean;
  isBackgroundSyncEnabled: () => Promise<boolean>;
  scheduleBackgroundSync: () => Promise<boolean>; // Starts the native background service
  cancelBackgroundSync: () => Promise<boolean>;   // Stops the native background service
};

---

Implementation Comparison

Old Approach (Legacy):

const { scheduleAndroidYesterdaySync } = useRookConfiguration();

// Required manual scheduling and often a persistent notification
await scheduleAndroidYesterdaySync();

New Approach (Streamlined):

const { requestHealthConnectPermissions } = useRookPermissions();
const { scheduleBackgroundSync } = useRookHealthConnect();

// 1. Request permissions
 await requestHealthConnectPermissions();

// 2. Start the native background extraction and transmission service
await scheduleBackgroundSync();

---

Key Benefits

• No Sticky Notification Required: Unlike the accelerometer-based step counting, the Health Connect background sync utilizes native Android background capabilities, removing the need for a persistent notification.
• Native Efficiency: Data transmission is handled natively, reducing battery consumption and improving reliability.
• Simplified Logic: A single call to scheduleBackgroundSync handles the recurring data transmission for all Health Connect pillars.

info

While scheduleYesterdaySync is gone, if you still need to extract real-time steps from the accelerometer (not Health Connect), you must still use useRookAndroidBackgroundSteps which does require a sticky notification.

Hook Migration: Samsung Health Synchronization

To maintain a modular and platform-specific architecture, all Samsung Health synchronization logic has been moved out of the general configuration. Previously, these methods were located in useRookConfiguration; they are now consolidated within the dedicated useRookSamsungHealth hook.

Interface Comparison

- const useRookConfiguration = () => {
-   enableSamsungSync: () => Promise<boolean>;
-   disableSamsungSync: () => Promise<boolean>;
-   isSamsungSyncEnabled: () => Promise<boolean>;
- }

+ const useRookSamsungHealth = () => {
+   ready: boolean;
+   enableSamsungSync: () => Promise<boolean>;
+   disableSamsungSync: () => Promise<boolean>;
+   isSamsungSyncEnabled: () => Promise<boolean>;
+ }

---

Key Changes

• Dedicated Context: By moving these methods to useRookSamsungHealth, the SDK ensures that Samsung-specific initialization logic is only executed when necessary.
• Separation of Concerns: useRookConfiguration now focuses strictly on user identity and global settings, while useRookSamsungHealth handles the lifecycle of the Samsung Health connection.

Implementation Example

Old Approach:

const { enableSamsungSync } = useRookConfiguration();
await enableSamsungSync();

New Approach:

const { enableSamsungSync, isSamsungSyncEnabled } = useRookSamsungHealth();

// Check status and enable sync using the specific hook
const isEnabled = await isSamsungSyncEnabled();

if (!isEnabled) {
  await enableSamsungSync();
}

---

Migration Summary Table

Feature	Legacy Hook	New Dedicated Hook
Apple Health Sync	useRookConfiguration	useRookAppleHealth
Samsung Health Sync	useRookConfiguration	useRookSamsungHealth
Health Connect Sync	useRookConfiguration	useRookHealthConnect

info

This change allows you to conditionally import hooks based on the user's device brand or preferences, reducing the overall memory footprint of your application.

Conclusion

This major update to the ROOK SDK represents a shift toward a modular, platform-centric architecture. By moving away from "catch-all" hooks and generic permission strings, the SDK now provides better type safety, reduced background overhead, and a more intuitive developer experience.

Summary of Major Changes

• Platform-Specific Hooks: Global methods in useRookConfiguration have been distributed into dedicated hooks: useRookAppleHealth, useRookSamsungHealth, and useRookHealthConnect.
• Unified Data Sync: The deprecated useRookSummaries and useRookEvents have been replaced by the powerful, centralized useRookSync hook.
• Cross-Platform Variables: Real-time metrics (steps and calories) are now handled through the unified useRookVariables hook using the SDKDataSource enum.
• API vs. Native Sources: A clear distinction has been made between cloud-based providers (useRookAPISources) and local device sensors.
• Enhanced Background Services: Background synchronization for Health Connect and Apple Health is now more efficient and includes automatic foreground syncing where applicable.

Quick Migration Checklist

1. Update Permissions: Replace string-based permissions with AppleHealthPermission and SamsungHealthPermission enums.
2. Refactor Sync Logic: Move existing summary and event sync calls to the new useRookSync().sync() and syncEvents() methods.
3. Update Variable Extraction: Replace useRookAndroidBackgroundSteps or useRookAppleHealthVariables with the unified useRookVariables hook for Health Connect, Apple, and Samsung data.
4. Refactor Sources: Rename useRookDataSources to useRookAPISources and ensure userID is passed to the V2 methods.