Heartbeat

Heartbeat is a periodic http request that CommCare makes in order to exchange some key data points with the server.

Hearbeat is meant to be a very light weight request so that CommCare Android can make these requests frequently if needed without utilizing too many resources or putting the system under load. CommCare begins attempting to submit a heartbeat immediately after a mobile user's login and will retry sending a heartbeat request regularly until one succeeds, with appropriate backoffs and based on network availability. Currently at-most-one request is expected per user login session.

The HTTP endpoint for the Heartbeat is defined the CommCare app's profile.xml file as

<property key="heartbeat-url" value="https://www.commcarehq.org/a/domain/phone/heartbeat/app_id/?build_profile_id=" force="true"/>

A Heartbeat request sends the follwing info to the server as HTTP request parameters -

1. cc_version : CommCare version installed on user's phone
2. app_version" Version of the CommCare app installed
3. num_quarantined_forms: Number of quarantined forms present on user's phone for the particular CommCare app
4. num_unsent_forms: Number of unsent forms present on user's phone for the particular CommCare app
5. last_sync_time: Time at which user last synced
6. current_drift: Current time drift which is the difference between server time and current phone time
7. max_drift_since_last_heartbeat: Max time drift since last hearbeat which is the maximum time difference ever ecountered between phone and server time after the last hearbeat
8. app_id: The ID of the CommCare application currently installed on the client

In turn, Heartbeat receives following info from the server in response -

1. Version of the most recently released CommCare apk
2. Version of the most recently released CommCare app build

CommCare Android can then use this info to prompt the user to update to latest versions of CommCare or CommCare app. This information is present in the response body as json

{
  "latest_apk_version": {},
  "latest_ccz_version": {},
  "app_id": ""
}

where "app_id" is always copied directly from the app_id HTTP param included in the request

Heartbeat can also used as a support mechanism to force certain actions on mobile for eg. on recieving a json key value pair as "force_logs":true in response , CommCare Android can fire up a forced log submission uploading the local device logs to the server.