Sonar SDK Synchronization
Synchronize recent, historical, and incremental native health data without routing it through your backend.
Supported Data
When a user connects a native provider, the SDK requests read access to every data type Sonar supports for that provider. It synchronizes everything that is both available in the health store and authorized by the user.
Partial authorization does not fail the connection. The SDK continues with authorized data types and exposes the current permission state to the mobile app. Native synchronization is read-only and never writes records to Apple Health, Health Connect, or Samsung Health.
See Supported Native Data for the exact provider matrix and the API resource that exposes each normalized result.
Synchronization Order
Synchronize Recent Data
The SDK reads the most recent 30 days first. New data always takes priority so current health information becomes available quickly.
Continue Through History
After recent data is queued, the SDK works backwards from day 31 for up to two years or as far as the provider and granted permissions allow.
Maintain Incremental State
After the initial import, the SDK uses HealthKit anchors, Health Connect changes tokens, or Samsung Health cursors to read only new, updated, and deleted records.
Prioritize New Changes
Incremental changes interrupt historical work when necessary. Historical synchronization resumes from its locally stored position afterward.
Automatic Synchronization
Connecting a provider starts its initial synchronization automatically. Afterward, the SDK listens for native changes and uses platform background opportunities to keep the provider current. Mobile operating systems decide when background work can run, so delivery is not guaranteed to be immediate.
When the mobile app returns to the foreground, the SDK resumes queued work and unfinished history. The app does not need a timer or its own upload scheduler.
Immediate Sync
Call sync() when the user expects fresh data immediately, such as when opening a health dashboard after completing a workout. It requests new changes for all connected providers and then resumes unfinished historical work.
const result = await Sonar.sync();
// "started" or "already_running"This is an immediate incremental pull, not a full reread. Calls made while synchronization is active join the current run.
Safe Resynchronization
Call resync(provider) when data appears to be missing, a native cursor becomes invalid, or a new SDK version supports additional record types.
await Sonar.resync("apple_health");The SDK preserves the provider connection and all data already stored by Sonar. It resets that provider’s local read position, synchronizes the recent 30 days, and continues backwards for up to two years. Replayed records are deduplicated during processing.
The resynchronization request is persisted on the device, resumes after application restarts, and coalesces repeated calls. Incremental changes continue to take priority over historical replay.
Resynchronization never deletes server data. A destructive rebuild requires an explicit disconnect and reconnect.
Device-Owned Progress
Synchronization progress belongs to the SDK and is persisted on the device. The mobile app observes recent, historical, incremental, retry, and reauthorization states through the public SDK interface.
There is no separate server-side progress or completion request. The mobile app observes active SDK work locally, while lastSuccessfulSyncAt records the most recent accepted synchronization. If the application is reinstalled and local state is lost, the SDK starts a new recent-to-historical import; Sonar’s data processing deduplicates records already received.
Reliability and Retry
The SDK owns native reads, batching, secure uploads, cursor advancement, and retry. Customers never construct health-data payloads or call an upload endpoint.
If the SDK does not receive an acceptance response, it does not advance the native read position. A later foreground, observer, or operating-system background opportunity reads and sends that work again. Repeated delivery is safe because normalization deduplicates the underlying health records.
The SDK advances native progress only after Sonar durably accepts the corresponding records. Authentication failures trigger normal SDK session recovery; network errors, rate limits, and temporary server failures retain work for retry.
Data Availability
An accepted upload is not necessarily queryable immediately. Sonar first processes the rolling 30-day window, makes that recent data available through the API, and emits one subject.synced webhook. The customer backend can begin reading daily metrics, workouts, sleep, scores, or timeseries without waiting for the complete historical import.
Older history continues in the background. Sonar consolidates those batches using a quiet window with a maximum wait, coalescing sustained backfill activity instead of sending a webhook for every upload. Later subject.synced webhooks indicate that additional normalized data is available.
This availability contract is uniform across Apple Health, Health Connect, and Samsung Health even though the records and history exposed by each platform differ.
Continue to Provider Lifecycle, return to the Mobile SDK overview, or choose iOS (Swift), Android (Kotlin), or React Native.