Reliable Cache for Data Sync

Concept

After historical health data is pulled from the device to the App, the device usually no longer keeps that history. If the App process exits, fails to persist, or has not stored the record after the callback, that history may be lost permanently.

Reliable cache means: delivery is complete only when the App confirms, not when the callback is fired.

Core rules:

| Historical data only | Today’s data is not stored in reliable cache; it still resumes by sync progress | | Off by default | Keep it off if the App does not implement confirm-and-store, to avoid repeated callbacks |

Ownership flow:

Device history → SDK local reliable cache → App stores and consume → local copy removed
                      ↑
              Not consumed: delivered again on next sync

Entry point: sdk.syncData

Behavior

When enabled:

• Historical data received during sync is retained locally
• After the App confirms with consumeReliableCacheRecord, the local copy is removed
• Unconfirmed records are delivered again through the data callback on the next startSync
• Today’s data is not stored in reliable cache

When to Call

Notes:

• Do not re-enable for every startSync in the same process
• After process restart, enable again
• Do not toggle the switch while sync is running
• Expired records are cleaned automatically; the App does not need a separate purge API

APIs

setReliableCacheEnable

Enable or disable reliable cache.

• Parameters:
  • enable: true on, false off; default off
  • completion: return code, 0 success

After enable, later startSync calls use reliable cache. After disable, new records are not cached and unconfirmed local copies are not replayed; use clearReliableCacheRecords to delete existing copies.

isReliableCacheEnabled

Query whether reliable cache is enabled.

• Parameters:
  • completion: true if enabled

consumeReliableCacheRecord

Confirm one received record and delete its local copy so later syncs do not deliver it again.

• Parameters:
  • type: same type as in the startSync data callback
  • year / month / day: date fields that identify the record in the callback JSON
  • hour / minute / second: use 0 for day-based data; use full time for per-session data, matching the callback JSON
  • completion: 0 success; 5 not found; 7 type cannot be mapped

May be called inside the data callback. If the file is not written yet, returns success and marks pending confirmation. Effective only when reliable cache is enabled.

clearReliableCacheRecords

Clear all reliable cache records for the current device. Does not depend on the enable switch. Does not affect other devices, sync progress, or today’s data resume.

• Parameters:
  • completion: return code, 0 success

Example

Swift:

// Call once after bind / reconnect, before the first sync
sdk.syncData.setReliableCacheEnable(enable: true) { _ in }

sdk.syncData.startSync { progress in
} funcData: { type, jsonStr, errorCode in
    guard errorCode == 0, !jsonStr.isEmpty else { return }
    // Confirm only after the App has stored the record
    // year/month/day from callback JSON; day-based hour/minute/second = 0
    sdk.syncData.consumeReliableCacheRecord(
        type: type,
        year: 2026,
        month: 8,
        day: 21,
        hour: 0,
        minute: 0,
        second: 0
    ) { code in
        print("consume code:\(code)")
    }
} funcCompleted: { errorCode in
    print("sync done errCode:\(errorCode)")
}

// On unbind of the current device or reset
sdk.syncData.clearReliableCacheRecords { code in
    print("clear code:\(code)")
}

Kotlin:

// Call once after bind / reconnect, before the first sync
sdk.syncData.setReliableCacheEnable(true) { }

sdk.syncData.startSync(
    { progress -> },
    { type, jsonStr, errorCode ->
        if (errorCode != 0 || jsonStr.isEmpty()) return@startSync
        // Confirm only after the App has stored the record
        // year/month/day from callback JSON; day-based hour/minute/second = 0
        sdk.syncData.consumeReliableCacheRecord(
            type = type,
            year = 2026,
            month = 8,
            day = 21,
            hour = 0,
            minute = 0,
            second = 0
        ) { code ->
            println("consume code:$code")
        }
    },
    { errorCode ->
        println("sync done errCode:$errorCode")
    }
)

// On unbind of the current device or reset
sdk.syncData.clearReliableCacheRecords { code ->
    println("clear code:$code")
}