> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spikeapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS SDK Backfill

> Backfill historical data from Apple HealthKit.

## Backfill from Apple HealthKit

Data is stored exclusively on the device (iPhone). Backfilling is possible from the moment the application user grants permissions and is limited by:

* What data the user has on their device
* What permissions your app has been granted (read access for specific data types)
* User's health app settings or deletions
* Your retention policy settings

## Manual Data Extraction Required

Because Apple doesn't offer any other communication except HealthKit framework, you **must query needed data manually** to backfill. Before data is extracted, it won't be available to your backend over API calls. Enabling background data delivery also won't perform the backfill as it's designed for new data events.

## Implementation

To implement backfill functionality, query historical data using the SDK's statistics methods for your desired date range:

```swift theme={null}
import SpikeSDK

// Example: Backfill last 7 days of steps data
let calendar = Calendar.current
let today = Date()

for dayOffset in 0..<7 {
    guard let startDate = calendar.date(byAdding: .day, value: -dayOffset, to: today) else { continue }
    guard let endDate = calendar.date(byAdding: .day, value: 1, to: startDate) else { continue }
    
    do {
        let statistics = try await spikeConnection.getStatistics(
            ofTypes: [.steps],
            from: startDate,
            to: endDate,
            interval: .day,
            filter: StatisticsFilter(providers: [.apple])
        )
        
        // Process the statistics data
        for statistic in statistics {
            print("Steps for \(statistic.start): \(statistic.value)")
        }
    } catch {
        // Handle specific error types for better user experience
        if let hkError = error as? HKError {
            switch hkError.code {
            case .errorAuthorizationNotDetermined:
                print("Authorization not determined. Request permissions first.")
            case .errorAuthorizationDenied:
                print("Access denied. Guide user to Health app settings.")
            default:
                print("HealthKit error: \(hkError.localizedDescription)")
            }
        } else {
            print("Error fetching statistics for \(startDate): \(error.localizedDescription)")
        }
    }
}
```

## Best Practices

### Performance and User Experience

* Keep the backfill process asynchronous for the best user experience
* Segment requests into smaller date ranges to ensure optimal performance
* Implement rate limiting to avoid overwhelming the HealthKit store
* Consider implementing a progress indicator for longer backfill operations

### Privacy and Security

* Handle permissions gracefully — users may grant partial access
* Consider allowing users to control the backfill scope (date range, data types)
* Comply with relevant regulations such as GDPR for user data protection

### Error Handling

* Implement robust error handling for authorization failures
* Gracefully handle scenarios where data is unavailable or incomplete
* Manage data conflicts and duplicates effectively to maintain data integrity
* Provide meaningful feedback to users about data access issues
* Guide users to Health app settings when permissions are denied

### Data Management

* Avoid storing HealthKit data outside the HealthKit store unless necessary
* If external storage is required, ensure data is encrypted and secure
* Validate data before processing to ensure accuracy and consistency
* Respect a user's ability to revoke permissions at any time