Skip to main content

Quick Start

Get started with the basic implementation

1. Overview​

Features​

  • Get authorization.
  • Register users.
  • Sync Apple Health summaries and events.
  • Sync health data automatically on background and with every app launch.

Xcode​

The SDK requires Xcode 26.0 or higher.

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​

  • rook_sdk_apple_health
    • Latest version: Apple Health Version
    • Latest stable version: 4.1.0
    • LTS version (supported until September 27, 2026): 1.10.2
  • 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_apple_health

On root folder run:

flutter pub get

On ios/Podfile add the following

platform :ios, '13.0'

On ios folder run:

pod install

Open the ios folder with Xcode

Add HealthKit capability to your Xcode project:

  1. Open your project in Xcode.
  2. Click on your project file (most cases is Runner) in the Project Navigator.
  3. Click on the "Signing and capabilities" tab.
  4. Click on the "+ Capability" button and select "HealthKit" from the list.
  5. Check the "Background delivery" option
  6. Click on the "+ Capability" button and select "Background Modes" from the list.
  7. Check the "Background fetch" option

Add HealthKit framework to your Xcode project:

  1. Open your project in Xcode.
  2. Click on your project file (most cases is Runner) in the Project Navigator.
  3. Click on the "Build Phases" tab.
  4. Click on the "+" button under the "Link Binary With Libraries" section and select "HealthKit.framework" from the list.

Declare the privacy permissions used by this SDK. You will need to include the NSHealthShareUsageDescription and NSHealthUpdateUsageDescription keys in your app's Info.plist file.

These keys provide a description of why your app needs to access HealthKit data and will be displayed to the user in the permission request dialog.

  1. Open ios folder
  2. Open Runner folder
  3. Add the following to Info.plist
<key>NSHealthShareUsageDescription</key>
<string>This app requires access to your health and fitness data in order to track your workouts and activity levels.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>This app requires permission to write workout data to HealthKit.</string>

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) {
    AHRookConfigurationManager.enableNativeLogs();
  }

  AHRookConfigurationManager.setConfiguration(rookConfiguration);

  AHRookConfigurationManager.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() {
  AHRookConfigurationManager.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​

void requestPermissions() {
  AHRookHealthPermissionsManager.requestPermissions().then((_) {
    // Success
  }).catchError((exception) {
    // Handle error
  });
}

6. Schedule a background sync​

  void enableBackGround() async {
  try {
    AHRookBackgroundSync.enableBackground(
      enableNativeLogs: isDebug,
    );

    // Success. You will start to notice that data is syncing.
  } catch (exception) {
    // 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 {
  // Go to Android documentation to learn how to enable background sync
}

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

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

Continue learning​

Next steps​

Additional resources​