Health Kit

Use the Point Health Kit to collect and upload health samples to the Point Database.

Overview

Point Health Kit abstracts the main functionalities from Apple's Health kit in order to collect and upload health samples in an optimized and easy-to-implement way.

All methods are optimized for performance and low battery draining, the SDK has several internal optimizations including a small sqlite database to control and avoid uploading duplicated samples, reducing the network requests and data usage.

⚠️ All health kit methods require previous user authorization on the data types. Check the Permissions session.

Setup

Calling setupHealthkitIntegration(queryTypes:) will instantiate HealthKitManager within the SDK and it will be available for you to use. As this is the only way to create an instance of HealthKitManager, we suggest calling it as soon as possible, just after setup(clientId:clientSecret:fitbitClientId:environment:).

When setting up, you will need to send an Array of QueryType. These are the types of Health data you wish to collect when using the SDK. Assume that all the following features of this article will only work for the types you define in this step.

setupSDK() {
    PointSDK.setup({
      clientId: "clientID",
      clientSecret: "clientSecret",
      environment: PointEnvironment.Development,
      verbose: true,
    });

    PointSDK.setupHealthkitIntegration({
      queryTypes: [
        //only use this param if you want to enable the SDK for specific types, removing this will enable all types
        QueryType.HeartRate,
        QueryType.StepCount,
        QueryType.Workout,
        QueryType.ActiveEnergyBurned,
        QueryType.BasalEnergyBurned,
      ],
    });
}

As HealthKit is only available on iOS devices, this function will have no effect on other devices, like MacOS or iPadOS.

Permissions

Request authorization for all types defined on SDK setup. It is recommended to do it before setting the user token or attempting to evoke other SDK methods.

async requestPermissions() {
    await PointSDK.requestAuthorizationsIfPossible();
}

Listeners

Listeners are tools to keep track of new samples added to Apple's Health. They run on top of HealthKit's background delivery, so they are able to work even when your app is on background. When a listener is set, it wakes up your app whenever a process adds new samples of the specified type, and then syncs those to the Point database.

Start

You need to start the listeners you wish to run. This must be done as soon as possible, such as when the app finishes launching.

You can start listeners for all types you have set up the SDK with.

async startListeners() {
    await PointSDK.startAllListeners();
}

You can also start a listener for just a specific type.

async startStepCountListener() {
    await PointSDK.startListenerForType({ type: QueryType.StepCount });
}

⚠️ If you plan on supporting background listeners, set up all your types as soon as possible in application launch, for more information see: Enable background delivery official docs

⚠️ For iOS 15 you must enable the HealthKit Background Delivery by adding the com.apple.developer.healthkit.background-delivery entitlement to your app.

⚠️ Since the listeners are meant to be started in application launch, on the very first usage/session the queries will fail and not stay alive. This is because you start listeners before asking for user permissions. If you want to collect data in background from the first moment, we recommend also calling the start methods once after requesting user permissions.

Stop

Stopping a listener will make any changes made on Apple's Health unnoticeable.

You can stop delivery for specific type.

async stopStepCountListener() {
    await PointSDK.stopListenerForType({ type: QueryType.StepCount });
}

Or you can stop all listeners.

async stopAllListeners() {
    await PointSDK.stopAllListeners();
}

⚠️ Avoid stopping the listeners in the application lifecycle. You are not required to stop them at any time and their lifecycles are handled by Point SDK. The listeners are automatically stopped on user logout and restarted on new logins. Only explicitly stop them on a special scenario.

Historical Data

Helper functions to get the user past data, optimized to handle large amounts of data, using multiple Tasks and uploading in batches.

Fetches and uploads the user past data for all types defined in the SDK setup. This is executed automatically when you set the user token for the first time in a session, so you don't need to call this function manually unless you turned automatic syncing off.

async syncAllHistoricalData() {
    await PointSDK.syncAllHistoricalData();
}

You can also run a manual sync for specific type, but we encourage not to do it and let the automated process handle that.

async syncHistoricalDataForType() {
    await PointSDK.syncHistoricalDataForType({ type: QueryType.StepCount });
}

All historical data methods will query samples from an interval before the oldest sample date of the given type. The interval can be from 1 to 6 months, with 3 as default. If the oldest sample is older than one year, no query will be done. The starting date of the query is limited to one year before the current date.

Automatic "historical data syncing" is enabled by default. To turn it off, just set shouldSyncData parameter as false on the setAccessToken method. We strongly recommend to keep it enabled to acquire more accurate and personalized user data.

Manual Sync

Runs a custom query and sync the result with Point database.

🔥 This is available only for debugging purposes. The SDK provides tools to automatically sync Health data, which are optimized for the Point Health Service needs. It's not recommended to use this function for any other purposes other than debugging, as this may cause unnacurate metrics or unnecessary workload.

async syncHeartRate() {
    await PointSDK.sync({
        type: QueryType;
        startDate?: string;
        endDate?: string;
        filterDuplicates?: boolean;
    });
}

💡 You can manually run any available query using a custom date range and other filters.

Next Steps

Learn more about the Fitbit integration.