Skip to main content

Quick Start

Get started with the basic implementation

1. Overview​

Features​

  • Get authorization.
  • Register users.
  • Sync Health Connect summaries and events.
  • Schedule automatic Health Connect data syncs every time the app is launched or in background.
  • Track and upload steps from Android System in background.

Restrictions​

Health Connect (HC) known issues

Health Connect is a container of data where apps can READ and WRITE from and into it, that means for the ideal scenario both the provider (application that writes) and the consumer (application that reads) have to be working correctly.

There have been numerous reports of apps failing to synchronize data with Health Connect due to technical issues within the HC platform itself or because of the providers.

Also is important to clarify that Health Connect does not have real-time behaviour the availability of the data depends on each provider business rules for synchronization.

Finally, we'd like you to remember that we are always improving our SDK to offer the best experience, however, the Health Connect platform is in an alpha state, so it's functionality sometimes may not always be the expected.

Samsung Health

For Samsung Health we recommend to use our direct integration; Rook Samsung SDK which provides more accurate results and does not have the limitations of the Health Connect platform.

Android Studio​

Android Studio Narwhal 4 Feature Drop | 2025.1.4 or higher is recommended.

Dart and Flutter​

This package was developed with the following sdk constraints:

  • dart: >=3.10.4 <4.0.0
  • flutter: >=3.0.0

2. Installation​

In your build.gradle (app) set your min and target sdk version like below:

minSdk 26
targetSdk 36
  • rook_sdk_health_connect
    • Latest version: Health Connect Version
    • Latest stable version: 4.1.0
    • LTS version (supported until September 27, 2026): 3.3.0
  • rook_sdk_core
    • Latest version: Core Version
    • Latest stable version: 4.1.0
    • LTS version (supported until September 27, 2026): 1.2.0
flutter pub add rook_sdk_core
flutter pub add rook_sdk_health_connect

3. Initialize SDK​

void initialize() {
  const environment =
  kDebugMode ? RookEnvironment.sandbox : RookEnvironment.production;

  final rookConfiguration = RookConfiguration(
    clientUUID: clientUUID,
    secret: secret,
    environment: environment,
    // If true background sync will start when the SDK is initialized
    enableBackgroundSync: false,
  );

  // MUST be called first if you want to enable native logs
  if (kDebugMode) {
    HCRookConfigurationManager.enableNativeLogs();
  }

  HCRookConfigurationManager.setConfiguration(rookConfiguration);

  HCRookConfigurationManager.initRook().then((_) {
    // Success
  }).catchError((exception) {
    // Hanlde error
  });
}
tip

We recommend you to ask your users if they want to enable the automatic sync and steps tracking, then save their preference in local storage and set enableBackgroundSync conditionally.

tip

You should only initialize the SDK once per app launch.

Critical Requirement

You must register your applicationId (package name) and its corresponding secret in the ROOK Portal before attempting to initialize the SDK. Failure to register these credentials will cause the initialization to fail with an SDKNotAuthorizedException.

The ROOK Portal supports independent configurations for Sandbox and Production environments. Each environment requires its own unique pair of Package Name and secret.

If you come from a previous version you MUST re-initialize the SDK with the new authentication flow.

4. Update userID​

Update the userID:

void updateUserID() {
  HCRookConfigurationManager.updateUserID(userID).then((_) {
    // Success
  }).catchError((exception) {
    // Handle error
  });
}
info

Any call to updateUserID with a different userID will override the previous userID and reset the sync status, so if you are using Automatic Sync all health data will synchronize again.

5. Request permissions​

Check availability​

Before proceeding further, you need to ensure the user's device is compatible with Health Connect and check if the APK is installed.

Call checkHealthConnectAvailability and take the corresponding actions:

StatusDescriptionWhat to do
installedAPK is installedProceed to check permissions
notInstalledAPK is not installedPrompt the user to install Health Connect.
notSupportedThis device does not support Health ConnectTake the user out of the Health Connect section
void checkAvailability() {
  HCRookHealthPermissionsManager.checkHealthConnectAvailability().then((availability) {
    // Success
  }).catchError((exception) {
    // Handle error
  });
}

Once you have confirmed that availability == HCAvailabilityStatus.installed, ask permissions:

void requestHealthConnectPermissions() {
  HCRookHealthPermissionsManager.requestHealthConnectPermissions().then((requestPermissionsStatus) {
    if (requestPermissionsStatus == RequestPermissionsStatus.alreadyGranted) {
      // Permissions already granted, update your UI
    } else {
      // Permissions dialog has been displayed
    }
  }).catchError((error) {
    // Handle error
  });
}

6. Schedule a background sync​

void enableBackgroundSync() async {
  try {
    await HCRookBackgroundSync.enableBackground(enableNativeLogs: isDebug);

    // Background sync enabled
  } catch (error) {
    // Handle error
  }
}
tip

We recommend adding an extra call to enableBackground in the main method:

void main() {
  // Ensure that the plugin is ready
  WidgetsFlutterBinding.ensureInitialized();

  if (Platform.isAndroid) {
    enableAndroidBackgroundSync();
  } else {
    enableIOSBackgroundSync();
  }

  runApp(App());
}

void enableAndroidBackgroundSync() async {
  try {
    final userAllowedBackgroundSync = await AppPreferences().getUserAllowedBackgroundSync();

    if (userAllowedBackgroundSync) {
      await HCRookBackgroundSync.enableBackground(enableNativeLogs: isDebug);
    }
  } catch (error) {
    // Log
  }
}

void enableIOSBackgroundSync() async {
  // Go to IOS documentation to learn how to enable background sync
}

Continue learning​

Next steps​

Prepare for release​

Additional resources​