Apple Health, Health Connect & Samsung Health

Once a user connects Apple Health, Health Connect, or Samsung Health, the Thryve SDK can retrieve and sync data from these native sources either automatically or manually.

We generally recommend manually synchronizing connected native data sources whenever your app comes to the foreground to ensure all data is up-to-date, as automatic background data synchronization is highly dependent on the operating system and its resource and battery management, allowing for regular synchronizations.

Web data sources are seamlessly managed by the Thryve backend. This page is only related to data sources where health data is directly retrieved from the end user device via the Thryve SDK.

SDK Module Configuration

When using Apple Health, Health Connect & Samsung Health, you will need the optional SDK modules Apple Health, Health Connect or Samsung Health. Make sure to initialize the corresponding configurations ThryveAppleHealthConfig, ThryveHealthConnectConfig and ThryveSamsungHealthConfig for correct functionality.

Parameter

Description

Mandatory

configs

List of ThryveSDKModulesConfig for imported SDK modules.

yes

When using the Apple Health module, make sure to define the data types in the ThryveAppleHealthConfig . This is only relevant for iOS integration.

Parameter

Description

Mandatory

dataTypes

The Apple Health data types Set<ThryveAppleHealthDataType> required by your app. Ensure to limit types to data described in your data privacy policy. Always ensure the configured dataTypes are consistent across your application. Please refer to this document to understand the data types.

yes

enableBackgroundSync

Configures background data synchronization on SDK initialization (retrieving data when your app is closed or idle). Default state is true which requires Background Delivery to be enabled for a HealthKit Capability.

Alternatively, use the executeBackgroundSync method in AppDelegate

When using the Health Connect module, make sure to define the data types in the ThryveHealthConnectConnectorConfig . This is only relevant for Android integration

Parameter

Description

Mandatory

dataTypes

Health Connect data types required by your app. Ensure to limit types to data described in your data privacy policy. Always ensure the configured dataTypes are consistent across your application. Please refer to this document to understand the data types.

no, defaults to all supported data types

enableBackgroundSync

Will request background data sync permissions. If permissions are granted, background tasks using WorkManager will be scheduled by the Thryve SDK.

no, defaults to true

enableReadHealthDataHistory

Will request historical data sync permissions. If permissions are granted, timeframes older than 30 days can be requested when using manual data synchronization methods.

no, defaults to true

When using the Samsung Health module, make sure to define the data types in the ThryveSamsungHealthConfig . This is only relevant for Android integration

Parameter

Description

Mandatory

dataTypes

The Samsung Health data types required by your app. Please refer to this document to understand the data types. Ensure to limit types to data described in your data privacy policy. Always ensure the configured dataTypes are consistent across your application.

no, defaults to all supported data types

enableBackgroundSync

Schedules background tasks using WorkManager for data synchronization when app is closed or idle.

no, defaults to true

Please ensure you have set-up your iOS and Android project with correct configuration for Apple HealthKit, .

Automatic Background Data Synchronization

We utilize different technologies for automatic background data retrieval on iOS and Android. On iOS, the Thryve SDK employs HealthKit’s native background synchronization API. For Android, synchronization is scheduled and managed via WorkManager.

The availability of background data synchronizations is configurable for Apple Healtsh, Samsung Health and Health Connect data sources in the corresponding config objects.

The ThryveHealthConnect and ThryveSamsungHealth modules perform background synchronization every 30 minutes once enableBackgroundSync is enabled in the configuration.

ThryveAppleHealth, on the other hand, triggers background synchronization whenever new data becomes available in Apple Health while the app is running in the background.

To enable background data synchronization (retrieving data when your app is closed or idle), use the executeBackgroundSync method within the didFinishLaunchingWithOptions function in AppDelegate right after connecting to Apple Health.

Apple mandates that this logic runs within the first few seconds of app startup for data delivery, hence its placement in AppDelegate. Refer to the sample code for further details.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // When Apple's Health app initiates contact, it triggers your application 
        // via didFinishLaunchingWithOptions. Once activated, HealthKit waits 
        // briefly to determine if your app wishes to renew its query contracts. 
        // Calling the relevant method as early as possible renews these contracts, 
        // enabling the app to fetch new data promptly from Apple Health.
        ThryveSDK.get().executeBackgroundSync(
                  dataSource: .apple,
                  dataTypes: ThryveAppleHealthDataType.allTypes)
        // Override point for customization after application launch.
        return true
    }

Ensure your project is configured correctly and Background Delivery is enabled in your apps HealthKit Capabilities as documented.

To enable background data synchronization (retrieving data when your app is closed or idle) in native Android, using Kotlin, enable background sync in the ThryveHealthConnectConfig .

val healthConnectConfig = ThryveHealthConnectConfig(
        dataTypes = ThryveHealthConnectDataType.entries.toList(),
        enableBackgroundSync = true,
        enableReadHealthDataHistory = true
    )

Background sync will only execute if the user has granted corresponding Health Connect permission.

To enable background data synchronization (retrieving data when your app is closed or idle) in native Android, using Kotlin, enable background sync in the ThryveSamsungHealthConfig .

val samsungHealthConfig = ThryveSamsungHealthConfig(
        dataTypes = ThryveSamsungHealthDataType.entries.toList(),
        enableBackgroundSync = true
    )

In React Native, using javascript or Typescript, enable enableBackgroundSync sync in your configuration

const thryveSDKConfig = {
    authId: appId,
    authSecret: appSecret,
    endUserAlias: "YOUR_UNIQUE_USER_IDENTIFIER",
    locale: 'en',
    config: [
      {
        source: Source.APPLE,
        dataTypes: appleHealthDataTypes,
      },
      {
        source: Source.HEALTH_CONNECT,
        dataTypes: healthConnectDataTypes,
        enableBackgroundSync: true,
        enableReadHealthDataHistory: true,
      },
      {
        source: Source.SAMSUNG,
        dataTypes: samsungHealthDataTypes,
        enableBackgroundSync = true,
      },
      {
        source: Source.SHENAI,
        apiKey: "SHEN_AI_API_KEY",
      },
    ],
  };
  thryveSDK.getOrCreate(thryveSDKConfig);

The background data sychronization in the Flutter SDK is enabled in the ThryveSDKConfig durint initialization. Check the Flutter SDK initialization section

Manual Data Synchronization

Manual data synchronization is recommended to ensure all recent data is available when the user opens your app. Therefore, we recommend using synchronize whenever your app moves to the foreground.

synchronize will ensure that both epoch and daily data added since the last data synchronization will be fetched from Apple Health, Health Connect, or Samsung Health. The initial execution of synchronize will fetch all data for today.

import ThryveCore
import ThryveAppleHealth

// synchronous function
func synchronize() {
  ThryveSDK.get().synchronize(
    dataSource: .apple,
    dataTypes: ThryveAppleHealthDataType.allTypes
  ) { (thryveResponse) in
    guard thryveResponse.successful else {
      thryveResponse.errors?.forEach { error in
        //synchronize failed process errors
        Logger.e { error }
      }
      return
    }
    //synchronize was successful
  }
}
    
// asynchronous function
func synchronize() {
  Task {
    let thryveResponse = await ThryveSDK.get().synchronize(
      dataSource: .apple,
      dataTypes: ThryveAppleHealthDataType.allTypes)
    guard thryveResponse.successful else {
      thryveResponse.errors?.forEach { error in
        //synchronize failed process errors
        Logger.e { error }
      }
      return
    }
    //synchronize was successful
  }
}

ThryveSDK.get().synchronize(dataSource = Source.HEALTH_CONNECT) { thryveResponse ->
    if (thryveResponse.successful) {
        // synchronization was successful
    } else {
        thryveResponse.errors.map { error -> // synchronization failed, process errors }
        }
    }
}

ThryveSDK.get().synchronize(dataSource = Source.SAMSUNG) { thryveResponse ->
    if (thryveResponse.successful) {
        // synchronization was successful
    } else {
        thryveResponse.errors.map { error -> // synchronization failed, process errors }
        }
    }
}

import { 
Source,
ThryveSamsungHealthDataType,
ThryveHealthConnectDataType,
ThryveAppleHealthDataType,
ThryveSDK 
} from '@thryve/react-native-sdk';

//Synchronize Apple Health data
export async function synchronize() {
  const sdk = new ThryveSDK().getOrCreate(thryvSDKConfig);
  try {
    const allAppleHealthDataTypes = Object.values(ThryveAppleHealthDataType);
    const response = await sdk.synchronize(Souce.APPLE, allAppleHealthDataTypes);
    if (response?.data) {
      //synchronize was successfull
    } else {
      //synchronize failed. process all errors.
      response.errors.forEach((error) => {
        console.log(`Apple Health synchronize error ${error}`);
      });
    }
  } catch (err) {
    console.error('❌ Unexpected error', err);
  }
}

//Synchronize Health Connect data
export async function synchronize() {
  const sdk = new ThryveSDK().getOrCreate(thryvSDKConfig);
  try {
    const allHealthConnectDataTypes = Object.values(ThryveHealthConnectDataType);
    const response = await sdk.synchronize(Souce.HEALTH_CONNECT, allHealthConnectDataTypes);
    if (response?.data) {
      //synchronize was successfull
    } else {
      //synchronize failed. process all errors.
      response.errors.forEach((error) => {
        console.log(`Health Connect synchronize error ${error}`);
      });
    }
  } catch (err) {
    console.error('❌ Unexpected error', err);
  }
}

//Synchronize Samsung Health data
export async function synchronize() {
  const sdk = new ThryveSDK().getOrCreate(thryvSDKConfig);
  try {
    const allSamsungHealthDataTypes = Object.values(ThryveSamsungHealthDataType);
    const response = await sdk.synchronize(Souce.SAMSUNG, allSamsungHealthDataTypes);
    if (response?.data) {
      //synchronize was successfull
    } else {
      //synchronize failed. process all errors.
      response.errors.forEach((error) => {
        console.log(`Samsung Health synchronize error ${error}`);
      });
    }
  } catch (err) {
    console.error('❌ Unexpected error', err);
  }
}

import 'package:module_apple_health/module_apple_health.dart';
import 'package:thryve_sdk/thryve_sdk.dart';

final class AppleHealthPageBloc {
  final ThryveSDK _thryveSDK;
  final Source _dataSource;
  List<HKConnectorType> _hkConnectorTypes;

  AppleHealthPageBloc(this._thryveSDK, this._hkConnectorTypes) : _dataSource = Source.apple;

  Future<ThryveResponse<void>> synchronize() => _thryveSDK.synchronize(_dataSource.id);

  Future<void> synchronizeAppleHealth() async {
    final ThryveResponse<void> response = await synchronize();

    if (!response.isSuccessful) {
      final Iterable<ThryveError> errors = response.errors.whereType<ThryveError>();

      for (final ThryveError error in errors) {
        //process each error here
      }

      throw StateError('Unable to synchronize all Apple Health data types.');
    }
  }
}

The manual data retrieval methods will return a ThryveResponse. This response will be true if the data is uploaded successfully. If issues occur during retrieval or upload, the response will be false, and a list of ThryveError will be provided. Each ThryveError contains details about the error encountered.

Historic data backfill

To access data predating the initial synchronization, the Thryve SDK provides methods for backfilling historical data. These methods allow synchronization of epoch and daily data within a specified timeframe.

We recommend using backfill methods only to fetch historic data, usually during the first connection or for a specific gap. Backfill should be used infrequently and should not run on a regular schedule.


import ThryveCore
import ThryveAppleHealth

func backfillEpoch() {
  ThryveSDK.get().backfillEpoch(
    dataSource: .apple,
    startDate: from,
    endDate: to,
    dataTypes: ThryveAppleHealthDataType.allTypes
  ) { (thryveResponse) in
    guard thryveResponse.successful else {
      thryveResponse.errors?.forEach { error in
        //synchronize failed process errors
        Logger.e { error }
      }
      return
    }
    //synchronize was successful
  }
}

func backfillDaily() {
  ThryveSDK.get().backfillDaily(
    dataSource: .apple,
    startDate: from,
    endDate: to,
    dataTypes: ThryveAppleHealthDataType.allTypes
  ) { (thryveResponse) in
    guard thryveResponse.successful else {
      thryveResponse.errors?.forEach { error in
        //synchronize failed process errors
        Logger.e { error }
      }
      return
    }
    //synchronize was successful
  }
}

ThryveSDK.get().backfillEpoch(
    dataSource = Source.HEALTH_CONNECT,
    startDate = Date().daysAgo(30),
    endDate = Date()
) { thryveResponse ->
    if (thryveResponse.successful) {
        // backfill was successful
    } else {
        thryveResponse.errors.map { error -> // backfill failed, process errors }
        }
    }
}

ThryveSDK.get().backfillDaily(
    dataSource = Source.HEALTH_CONNECT,
    startDate = Date().daysAgo(30),
    endDate = Date()
) { thryveResponse ->
    if (thryveResponse.successful) {
        // backfill was successful
    } else {
        thryveResponse.errors.map { error -> // backfill failed, process errors }
        }
    }
}

ThryveSDK.get().backfillEpoch(
    dataSource = Source.SAMSUNG,
    startDate = Date().daysAgo(30),
    endDate = Date()
) { thryveResponse ->
    if (thryveResponse.successful) {
        // backfill was successful
    } else {
        thryveResponse.errors.map { error -> // backfill failed, process errors }
        }
    }
}

ThryveSDK.get().backfillDaily(
    dataSource = Source.SAMSUNG,
    startDate = Date().daysAgo(30),
    endDate = Date()
) { thryveResponse ->
    if (thryveResponse.successful) {
        // backfill was successful
    } else {
        thryveResponse.errors.map { error -> // backfill failed, process errors }
        }
    }
}

import { 
Source,
ThryveSamsungHealthDataType,
ThryveHealthConnectDataType,
ThryveAppleHealthDataType,
ThryveSDK 
} from '@thryve/react-native-sdk';

//backfillEpoch Apple Health data
export async function backfillEpoch() {
  const sdk = new ThryveSDK().getOrCreate(thryvSDKConfig);
  try {
    const allAppleHealthDataTypes = Object.values(ThryveAppleHealthDataType);
    const response = await sdk.backfillEpoch(Souce.APPLE, startDate, endDate, allAppleHealthDataTypes);
    if (response?.data) {
      //backfillEpoch was successfull
    } else {
      //backfillEpoch failed. process all errors.
      response.errors.forEach((error) => {
        console.log(`Apple Health backfillEpoch error ${error}`);
      });
    }
  } catch (err) {
    console.error('❌ Unexpected error', err);
  }
}

//backfillDaily Apple Health data
export async function backfillEpoch() {
  const sdk = new ThryveSDK().getOrCreate(thryvSDKConfig);
  try {
    const allAppleHealthDataTypes = Object.values(ThryveAppleHealthDataType);
    const response = await sdk.backfillDaily(Souce.APPLE, startDate, endDate, allAppleHealthDataTypes);
    if (response?.data) {
      //backfillDaily was successfull
    } else {
      //backfillDaily failed. process all errors.
      response.errors.forEach((error) => {
        console.log(`Apple Health backfillDaily error ${error}`);
      });
    }
  } catch (err) {
    console.error('❌ Unexpected error', err);
  }
}

import 'package:module_apple_health/module_apple_health.dart';
import 'package:thryve_sdk/thryve_sdk.dart';

final class AppleHealthPageBloc {
  final ThryveSDK _thryveSDK;
  final Source _dataSource;
  List<HKConnectorType> _hkConnectorTypes;

  AppleHealthPageBloc(this._thryveSDK, this._hkConnectorTypes) : _dataSource = Source.apple;

  Future<ThryveResponse<void>> backfillEpoch(
    DateTime startDate,
    DateTime endDate,
  ) =>
      _thryveSDK.backfillEpoch(
          _dataSource.id, startDate, endDate, _hkConnectorTypes.map((e) => e.name).toList());

  Future<ThryveResponse<void>> backfillDaily(
    DateTime startDate,
    DateTime endDate,
  ) =>
      _thryveSDK.backfillDaily(
          _dataSource.id, startDate, endDate, _hkConnectorTypes.map((e) => e.name).toList());

  Future<void> backfillEpochAppleHealth(
    DateTime startDate,
    DateTime endDate,
  ) async {
    final ThryveResponse<void> response = await backfillEpoch(startDate, endDate);

    if (!response.isSuccessful) {
      final Iterable<ThryveError> errors = response.errors.whereType<ThryveError>();

      for (final ThryveError error in errors) {
        //process each error here
      }

      throw StateError('Unable to backfill all Apple Health data types.');
    }
  }
  
 Future<void> backfillDailyAppleHealth(
    DateTime startDate,
    DateTime endDate,
  ) async {
    final ThryveResponse<void> response = await backfillDaily(startDate, endDate);

    if (!response.isSuccessful) {
      final Iterable<ThryveError> errors = response.errors.whereType<ThryveError>();

      for (final ThryveError error in errors) {
        //process each error here
      }

      throw StateError('Unable to backfill all Apple Health data types.');
    }
  }
}

backfillEpoch fetches epoch data for the given timeframe, with a maximum of 30 days. If the difference between startDate and endDate is more than 30 days, the SDK will count from the end date 30 days back

backfillDaily fetches daily data for the given timeframe, with a maximum of 365 days. If the difference between startDate and endDate is more than 365 days, the SDK will count from the end date 365 days back

Parameter

Description

Mandatory

dataSource

The data source to synchronize data from. iOS defaults to .apple

yes, on Android. no, on iOS

dataTypes

The data types to synchronize. It defaults to the data types defined in the data source config.

startDate

The date to start data retrieval and synchronization from. It is applicable only to the backfiill functions

yes

endDate

The date to end data retrieval and synchronization on. It defaults to today and applicable only to the backfiill functions.

PreviousBuild your custom data source connection screen NextDirect bluetooth device connection

Last updated 2 months ago