interval-health-band-plugin

v2.0.0

Published

3 days ago

Capacitor plugin for Interval Health Smart Band

Downloads

119

0High
0Medium
0Low

interval-health

capacitor plugin native

interval-health-band-plugin

Capacitor plugin for Interval Health Smart Band

Install

npm install interval-health-band-plugin
npx cap sync

iOS Configuration

To use this plugin on iOS, you must add the following privacy descriptions to your ios/App/App/Info.plist file:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app requires Bluetooth to connect to and sync data with your smart band.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app requires Bluetooth to connect to and sync data with your smart band.</string>

Android Configuration

To use this plugin on Android, ensure you have the following permissions in your android/app/src/main/AndroidManifest.xml:

<!-- Bluetooth Permissions -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<!-- Required for BLE scanning on older Android versions -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Known Platform Discrepancies (iOS vs Android)

While this plugin unifies the outer JSON wrapper and pagination behavior across both platforms to prioritize the iOS format (e.g., {"arrayDetailActivityData": [...]}), the inner properties of the returned dictionaries for historical data still reflect the underlying native Android/iOS SDKs:

Step Data (getDetailedActivityData): The property names inside the step coordinate objects differ slightly between the Android SDK and the iOS BleSDK.
Sleep Data (getDetailSleepData): The sleep stage property names and timestamp formats differ between Android and iOS.

Recommendation: Your frontend application layer should check the running Capacitor platform (Capacitor.getPlatform()) and map the inner properties of these history arrays accordingly.

API

initialize()

initialize() => Promise<void>

getMacAddress()

getMacAddress() => Promise<void>

getBatteryLevel()

getBatteryLevel() => Promise<void>

getDeviceVersion()

getDeviceVersion() => Promise<void>

getTime()

getTime() => Promise<void>

setTime(...)

setTime(options?: { year?: number | undefined; month?: number | undefined; day?: number | undefined; hour?: number | undefined; minute?: number | undefined; second?: number | undefined; } | undefined) => Promise<void>

| Param | Type | | ------------- | -------------------------------------------------------------------------------------------------------------- | | options | { year?: number; month?: number; day?: number; hour?: number; minute?: number; second?: number; } |

getPersonalInfo()

getPersonalInfo() => Promise<void>

setPersonalInfo(...)

setPersonalInfo(options: { age?: number; height?: number; weight?: number; stepLength?: number; gender?: number; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------------ | | options | { age?: number; height?: number; weight?: number; stepLength?: number; gender?: number; } |

getDeviceInfo()

getDeviceInfo() => Promise<void>

Retrieves Device Info (distance, 12h mode, temperature unit, etc)

setDeviceInfo(...)

setDeviceInfo(options: { distanceUnitMile?: boolean; is12Hour?: boolean; temperatureUnitFahrenheit?: boolean; wristOnEnable?: boolean; nightModeEnable?: boolean; socialDistanceEnable?: boolean; baseHeartRate?: number; screenBrightness?: number; dialInterface?: number; }) => Promise<void>

| Param | Type | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options | { distanceUnitMile?: boolean; is12Hour?: boolean; temperatureUnitFahrenheit?: boolean; wristOnEnable?: boolean; nightModeEnable?: boolean; socialDistanceEnable?: boolean; baseHeartRate?: number; screenBrightness?: number; dialInterface?: number; } |

getDynamicHeartRate(...)

getDynamicHeartRate(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

getStaticHeartRate(...)

getStaticHeartRate(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

getHrvData(...)

getHrvData(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

startScan()

startScan() => Promise<void>

stopScan()

stopScan() => Promise<void>

connect(...)

connect(options: { macAddress: string; autoConnect?: boolean; }) => Promise<void>

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | { macAddress: string; autoConnect?: boolean; } |

disconnect()

disconnect() => Promise<void>

pair(...)

pair(options: { macAddress: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------ | | options | { macAddress: string; } |

factoryReset()

factoryReset() => Promise<void>

addListener('onBandData', ...)

addListener(eventName: 'onBandData', listenerFunc: (data: BandDataResponse) => void) => Promise<PluginListenerHandle>

Listeners for returning asynchronous data

| Param | Type | | ------------------ | -------------------------------------------------------------------------------- | | eventName | 'onBandData' | | listenerFunc | (data: BandDataResponse) => void |

Returns: Promise<PluginListenerHandle>

addListener('onBandRawData', ...)

addListener(eventName: 'onBandRawData', listenerFunc: (data: any) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | ----------------------------------- | | eventName | 'onBandRawData' | | listenerFunc | (data: any) => void |

Returns: Promise<PluginListenerHandle>

addListener('onDeviceDiscovered', ...)

addListener(eventName: 'onDeviceDiscovered', listenerFunc: (device: DiscoveredDevice) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | ---------------------------------------------------------------------------------- | | eventName | 'onDeviceDiscovered' | | listenerFunc | (device: DiscoveredDevice) => void |

Returns: Promise<PluginListenerHandle>

addListener('onConnectionStateChange', ...)

addListener(eventName: 'onConnectionStateChange', listenerFunc: (data: { state: string; }) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | -------------------------------------------------- | | eventName | 'onConnectionStateChange' | | listenerFunc | (data: { state: string; }) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners

getDetailedActivityData(...)

getDetailedActivityData(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

getTotalActivityData(...)

getTotalActivityData(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

getDetailSleepData(...)

getDetailSleepData(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

getAutomaticSpo2Data(...)

getAutomaticSpo2Data(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

getManualSpo2Data(...)

getManualSpo2Data(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

getActivityModeData(...)

getActivityModeData(options: { mode: number; dateOfLastData: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { mode: number; dateOfLastData: string; } |

enterActivityMode(...)

enterActivityMode(options: { mode: ActivityMode; }) => Promise<void>

Starts a real-time activity recording on the watch. You MUST call sendActivityHeartbeat every 1 second after starting.

| Param | Type | | ------------- | ---------------------------------------------------------------- | | options | { mode: ActivityMode; } |

exitActivityMode()

exitActivityMode() => Promise<void>

Exits the currently running activity mode.

sendActivityHeartbeat(...)

sendActivityHeartbeat(options: { distance: number; paceSeconds: number; gpsSignal: number; }) => Promise<void>

Required 1-second ping payload to keep the watch tracking the activity. If GPS is unavailable, send 0s.

| Param | Type | | ------------- | -------------------------------------------------------------------------- | | options | { distance: number; paceSeconds: number; gpsSignal: number; } |

getAutomaticMeasurement(...)

getAutomaticMeasurement(options: { dataType: AutoMeasurementType; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------------------------------------------------------------- | | options | { dataType: AutoMeasurementType; } |

setAutomaticMeasurement(...)

setAutomaticMeasurement(options: AutoMeasurementOptions) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | AutoMeasurementOptions |

startRealTimeSteps(...)

startRealTimeSteps(options: { enable: boolean; tempEnable: boolean; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { enable: boolean; tempEnable: boolean; } |

startHealthMeasurement(...)

startHealthMeasurement(options: { type: HealthMeasurementType; enable: boolean; durationMs?: number; }) => Promise<void>

Starts or stops a live health measurement stream. type: HRV (1), HR (2), SpO2 (3), Temperature (4 - iOS only) durationMs: Required for Android only (e.g. 120000 for 2 mins)

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------------------------------ | | options | { type: HealthMeasurementType; enable: boolean; durationMs?: number; } |

parseData(...)

parseData(options: { data: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------ | | options | { data: string; } |

Interfaces

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

BandDataResponse

| Prop | Type | Description | | ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | type | string | The human-readable type of the mapped data (e.g. 'batteryLevel', 'macAddress') Will be 'error' if a parsing exception occurs. | | isComplete | boolean | Boolean indicating if this is the final packet for the requested data query | | data | any | The payload object/array holding the underlying metrics. Omitted for 'set' commands. | | message | string | Optional error message returned only when type is 'error' |

DiscoveredDevice

| Prop | Type | | ---------------- | ------------------- | | name | string | | macAddress | string | | rssi | number |

AutoMeasurementOptions

| Prop | Type | Description | | ------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dataType | AutoMeasurementType | | | enable | boolean | | | intervalTime | number | | | startHour | number | | | startMinute | number | | | endHour | number | | | endMinute | number | | | weeks | number | Bitmask for days of the week. Combine values from AutoMeasurementWeekDays using bitwise OR (|). For example, Monday and Tuesday: AutoMeasurementWeekDays.Monday | AutoMeasurementWeekDays.Tuesday Default is 255 (AllDays). |

Enums

ActivityMode

| Members | Value | | ---------------- | --------------- | | RUN | 0 | | CYCLING | 1 | | BADMINTON | 2 | | FOOTBALL | 3 | | TENNIS | 4 | | YOGA | 5 | | BREATH | 6 | | DANCE | 7 | | BASKETBALL | 8 | | WALK | 9 | | WORKOUT | 10 | | CRICKET | 11 | | HIKING | 12 | | AEROBICS | 13 | | PINGPONG | 14 | | ROPEJUMP | 15 | | SITUPS | 16 | | VOLLEYBALL | 17 |

AutoMeasurementType

| Members | Value | | ----------------- | -------------- | | HeartRate | 1 | | SpO2 | 2 | | Temperature | 3 | | HRV | 4 |

HealthMeasurementType

| Members | Value | | ----------------- | -------------- | | HRV | 1 | | HR | 2 | | SpO2 | 3 | | Temperature | 4 |

Data Formats & Responses

The following sections detail the specific payload structures required to invoke the measurement listeners, alongside their corresponding JSON responses emitted through the onBandData event listener.

Step Count Summary (`getTotalActivityData`)

Request

IntervalHealthBandPlugin.getTotalActivityData({
    mode: 0,             // 0: Read Latest, 1: Read specific date
    dateOfLastData: ""   // e.g., "y.M.d H:m:s" if mode is 1
});

Response (onBandData)

{
  "isComplete": true,
  "type": "totalActivityData",
  "data": {
    "arrayTotalActivityData": [
      {
        "distance": "0",
        "step": "4",
        "calories": "0",
        "date": "2026.02.24 16:20:38"
      }
    ]
  }
}

Step Count Details (`getDetailedActivityData`)

Provides 5-minute interval blocks tracking real-time movement throughout the day.

Request

IntervalHealthBandPlugin.getDetailedActivityData({
    mode: 0,
    dateOfLastData: ""
});

Response (onBandData)

{
  "isComplete": true,
  "type": "detailActivityData",
  "data": {
    "arrayDetailActivityData": [
      {
        "step": 36,
        "calories": 2.5,
        "distance": 0.05,
        "date": "2026.02.24 10:30:00"
      }
    ]
  }
}

Sleep Data Details (`getDetailSleepData`)

Categorizes sleep states (Light, Deep, Awake) segmented over chunks during the night.

Request

IntervalHealthBandPlugin.getDetailSleepData({
    mode: 0,
    dateOfLastData: ""
});

Response (onBandData)

{
  "isComplete": true,
  "type": "detailSleepData",
  "data": {
    "arrayDetailSleepData": [
      {
        "sleepUnitLength": 5, // 5 minutes per array item 
        "date": "2026.02.24 02:00:00",
        "arraySleep": [3, 3, 3, 2, 2, 1] // 1: Awake, 2: Light Sleep, 3: Deep Sleep
      }
    ]
  }
}

Auto Measurements (`getAutomaticMeasurement` / `setAutomaticMeasurement`)

Programmatically configure the smart band to read vitals (HR, SpO2, Temperature, HRV) independently on a custom schedule.

Request (Set Configuration)

import { AutoMeasurementType, AutoMeasurementWeekDays } from 'interval-health-band-plugin';

IntervalHealthBandPlugin.setAutomaticMeasurement({ 
    dataType: AutoMeasurementType.HeartRate, // 1: HR, 2: SpO2, 3: Temp, 4: HRV
    enable: true,
    intervalTime: 30, // Test every 30 minutes
    startHour: 9,     // From 9 AM
    startMinute: 0,
    endHour: 22,      // To 10 PM
    endMinute: 0,
    weeks: AutoMeasurementWeekDays.AllDays // Active constantly (255)
});

Response (Get Configuration onBandData) When invoking getAutomaticMeasurement({ dataType: 1 }), the watch responds with the current configuration values via the getAutomaticState type:

{
  "isComplete": true,
  "type": "getAutomaticState",
  "data": {
    "dataType": 1,
    "enable": true,
    "intervalTime": 30,
    "startHour": 9,
    "startMinute": 0,
    "endHour": 22,
    "endMinute": 0,
    "weeks": 255
  }
}

Dynamic Heart Rate (`getDynamicHeartRate`)

Fetches all-day continuous background heart rate readings.

Request

IntervalHealthBandPlugin.getDynamicHeartRate({
    mode: 0,
    dateOfLastData: ""
});

Response (onBandData)

{
  "isComplete": true,
  "type": "dynamicHeartRate",
  "data": {
    "arrayDynamicHeartRate": [
      {
        "date": "2026.02.24 10:30:00",
        "arrayDynamicHR": [75, 76, 75, 78, 80, 82, 80, 78, 77, 76, 75, 74]
      }
    ]
  }
}

Static Heart Rate (`getStaticHeartRate`)

Fetches manual heart rate measurements triggered on-demand by the user.

Request

IntervalHealthBandPlugin.getStaticHeartRate({
    mode: 0,
    dateOfLastData: ""
});

Response (onBandData)

{
  "isComplete": true,
  "type": "staticHeartRate",
  "data": {
    "arrayStaticHeartRate": [
      {
        "date": "2026.02.24 11:15:00",
        "onceHeartValue": 85
      }
    ]
  }
}

HRV Data (`getHrvData`)

Fetches historical Heart Rate Variability (HRV) and related cardiovascular metrics from the watch.

Request

IntervalHealthBandPlugin.getHrvData({
    mode: 0,
    dateOfLastData: ""
});

Response (onBandData)

{
  "isComplete": true,
  "type": "hrvData",
  "data": {
    "arrayHrvData": [
      {
        "date": "2026.02.24 10:30:00",
        "hrv": "30",
        "vascularAging": "14",
        "heartRate": "75",
        "systolicBP": "120",
        "diastolicBP": "80",
        "stress": "20" // Android-only field
      }
    ]
  }
}

Auto SpO2 Data (`getAutomaticSpo2Data`)

Fetches historically logged background measurement data for SpO2.

Emits event type "automaticSpo2Monitoring".

Request

IntervalHealthBandPlugin.getAutomaticSpo2Data({
    mode: 0,
    dateOfLastData: ""
});

Manual SpO2 Data (`getManualSpo2Data`)

Fetches SpO2 readings specifically triggered by the "Manual blood oxygen test" on the watch.

Emits event type "bloodOxygen". Note: This unifies the underlying Android SDK Obtain_The_data_of_manual_blood_oxygen_test command with the iOS DataType 43.

Request

IntervalHealthBandPlugin.getManualSpo2Data({
    mode: 0,
    dateOfLastData: ""
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

interval-health-band-plugin

Install

iOS Configuration

Android Configuration

Known Platform Discrepancies (iOS vs Android)

API

initialize()

getMacAddress()

getBatteryLevel()

getDeviceVersion()

getTime()

setTime(...)

getPersonalInfo()

setPersonalInfo(...)

getDeviceInfo()

setDeviceInfo(...)

getDynamicHeartRate(...)

getStaticHeartRate(...)

getHrvData(...)

startScan()

stopScan()

connect(...)

disconnect()

pair(...)

factoryReset()

addListener('onBandData', ...)

addListener('onBandRawData', ...)

addListener('onDeviceDiscovered', ...)

addListener('onConnectionStateChange', ...)

removeAllListeners()

getDetailedActivityData(...)

getTotalActivityData(...)

getDetailSleepData(...)

getAutomaticSpo2Data(...)

getManualSpo2Data(...)

getActivityModeData(...)

enterActivityMode(...)

exitActivityMode()

sendActivityHeartbeat(...)

getAutomaticMeasurement(...)

setAutomaticMeasurement(...)

startRealTimeSteps(...)

startHealthMeasurement(...)

parseData(...)

Interfaces

PluginListenerHandle

BandDataResponse

DiscoveredDevice

AutoMeasurementOptions

Enums

ActivityMode

AutoMeasurementType

HealthMeasurementType

Data Formats & Responses

Step Count Summary (getTotalActivityData)

Step Count Details (getDetailedActivityData)

Sleep Data Details (getDetailSleepData)

Auto Measurements (getAutomaticMeasurement / setAutomaticMeasurement)

Dynamic Heart Rate (getDynamicHeartRate)

Static Heart Rate (getStaticHeartRate)

HRV Data (getHrvData)

Auto SpO2 Data (getAutomaticSpo2Data)

Manual SpO2 Data (getManualSpo2Data)

Step Count Summary (`getTotalActivityData`)

Step Count Details (`getDetailedActivityData`)

Sleep Data Details (`getDetailSleepData`)

Auto Measurements (`getAutomaticMeasurement` / `setAutomaticMeasurement`)

Dynamic Heart Rate (`getDynamicHeartRate`)

Static Heart Rate (`getStaticHeartRate`)

HRV Data (`getHrvData`)

Auto SpO2 Data (`getAutomaticSpo2Data`)

Manual SpO2 Data (`getManualSpo2Data`)