SDK / API / BLE Integration
SDK, 서버 API, BLE bridge는 모두 actual value가 아니라 Earswet output envelope를 먼저 소비해야 한다.
Common rule
파트너 앱과 펌웨어는 Earswet response를 값 또는 오류의 단순 구조로 처리하면 안 된다. response는 출력 가능성, 접근권한, 제한 사유, 정책 버전, evidence identity를 함께 담은 envelope이다. UI 표시, BLE characteristic 갱신, 서버 저장, 외부 API 재전송은 이 envelope 해석 이후에만 발생해야 한다.
Consumer responsibilities
| Consumer | Required behavior | Forbidden behavior |
|---|---|---|
| Mobile SDK | outputMode와 rawValueAccess를 먼저 해석 | raw getter를 직접 열어 수치를 표시 |
| BLE bridge | status, non-value, evidence characteristic을 actual characteristic과 분리 | 차단 상태에서 actual-value characteristic 갱신 |
| Server API | 외부 consumer에게 reasoned envelope 제공 | policy decision 이전 candidate를 raw payload로 반환 |
| Partner dashboard | reason code와 evidence identity를 support trace로 연결 | non-value를 단순 sensor failure로 치환 |
OEM handoff
OEM은 sensor_id, vendor_id, firmware version, calibration version, marker_id, unit, sampling_time, quality flag, raw_access_policy의 의미를 integration annex로 확정한다. 센서 내부 알고리즘 전체 공개가 아니라, output governance에 필요한 field semantics의 확정이 통합의 핵심이다.
Acceptance handoff
- SDK는 blocked, trend-only, remeasurement, limited state를 UI 상태로 구분해야 한다.
- BLE는 raw access false 상태에서 actual characteristic을 갱신하지 않아야 한다.
- Server API는 external consumer에게 candidate raw value 대신 governed envelope를 전달해야 한다.
- 각 통합 release는 acceptance scenario와 replay check를 다시 통과해야 한다.