Sonar Provider Lifecycle
Connect and disconnect native health providers while preserving clear permission and deletion behavior.
Connection Model
A native provider connection belongs to one Sonar user and one mobile application installation. V1 permits only one owning installation for each provider, so Apple Health, Health Connect, and Samsung Health can each appear at most once for the user.
The SDK session and provider connection have separate lifecycles. Signing out revokes one installation’s SDK session without deleting imported data. Disconnecting a provider affects that provider for the user without revoking SDK sessions or changing other providers.
Connect a Provider
Check Availability
The SDK verifies that the native health store is installed, supported, and enabled for the registered mobile application.
Request Permissions
The SDK requests the complete Sonar-supported read set. If the user authorizes at least one supported type, the provider can connect and synchronize that subset.
Record the Connection
The SDK explicitly connects the provider with Sonar. This operation is idempotent: calling it for an active provider returns the existing connection.
Start Synchronization
The SDK begins with the most recent 30 days and continues backwards for up to two years according to the synchronization lifecycle.
Applications use the public SDK’s connect(provider) and disconnect(provider) methods. Sonar owns the transport and server-side connection records behind that interface.
Disconnect a Provider
Explicit disconnect is a deletion operation:
- The SDK stops new reads and forgets synchronization progress that Sonar has not accepted for that provider.
- Sonar marks the provider disconnecting and rejects later uploads for it.
- Sonar asynchronously deletes the provider connection, configuration, raw data, and normalized records.
- Other providers and SDK sessions remain active.
Disconnect is idempotent. The SDK reports the provider’s new state while cleanup is running:
{
"provider": "health_connect",
"status": "disconnecting"
}Calling disconnect again returns the current state without creating another cleanup operation. Once cleanup has finished, the provider state is disconnected.
Disconnecting a provider affects only its owning installation and does not change another provider or installation. A second installation cannot connect that same provider until cleanup has finished.
Observe Provider State
Disconnect does not return a separate operation ID. getProviderState(provider) and observeState expose one of four connection states:
| State | Meaning |
|---|---|
connecting | Permissions or the Sonar connection are being established |
connected | The provider can synchronize |
disconnecting | New uploads are rejected while stored data is deleted |
disconnected | Cleanup is complete and the provider can be connected again |
The SDK stores its desired state and last observed state on the device. Sonar remains authoritative, so the SDK reads the provider state again after an application restart or before resuming synchronization.
Customer backends can inspect established provider connections through GET /v1/users/{id}. Each entry reports status: connected, its connection timestamp, and its nullable latest synchronization timestamp. The public API does not expose cleanup progress in V1. The owning SDK observes disconnecting, and the device.disconnected webhook confirms that cleanup has completed.
Permission and Application Events
| Event | Result |
|---|---|
| Partial authorization | Synchronize the authorized data types |
| Permission revoked | Stop the affected reads; retain imported data |
| Temporary provider failure | Retain local cursors and retry later |
| Application sign-out or user switch | Revoke that installation’s SDK session; retain imported data |
| Application uninstall | Let the SDK session expire through inactivity; retain imported data |
| Explicit provider disconnect | Delete that provider’s imported data and configuration |
| Sonar user deletion | Revoke every session and delete all user data |
Permission loss never triggers deletion automatically. Only an explicit provider disconnect or user deletion removes existing data.
If the owning installation is lost or uninstalled, your backend can disconnect the provider with DELETE /v1/users/{id}/devices/{provider}. This deletes that provider’s imported data and releases it for another installation after cleanup. Revoking the lost SDK session is a separate action and does not delete imported data.
Reconnect and Resynchronize
Reconnect on the owning installation uses the same SDK session when it is still valid. If provider cleanup is still running, connect returns pending_cleanup. Call connect again later; the SDK also tries once when it resumes on a later application launch. After connection succeeds, it starts a new recent-to-historical import from device storage.
For a safe full replay without deletion, use resync(provider). A destructive rebuild remains an explicit sequence: disconnect, wait for cleanup, reconnect, and import up to two years again.
Return to the SDK Interface or SDK Synchronization, or continue to iOS (Swift), Android (Kotlin), or React Native.