Vitals™ SDK 文件

中文（简体）

English
中文（繁體）

中文（简体）

English
中文（繁體）

Appearance

Android 快速入门指南 ​

快速入门 Android SDK 最简单的方法是下载并试用我们的 示例程式码。此外，您还可以按照本快速入门指南，快速建立您的首个 Android 健康测评应用程式。

完成本指南后，我们强烈建议您遵循我们的 软体开发指南，以确保 Vitals™ SDK 产生的健康测评结果准确可靠。

SDK Installation ​

请按照 下载 页面中的说明安装 Android SDK 并将其整合到您的专案中。

设定相机 ​

如 整合 Vitals™ 健康测评（VHA） 中所述，第一步是设定相机。首先，建立一个新专案并按照以下说明操作。

相机权限 ​

在开发 Android 应用程式时，您需要在 AndroidManifest.xml 档案中指定以下内容，以允许应用程式使用相机：

xml
<uses-permission android:name="android.permission.CAMERA" />

然后，在 MainActivity.kt 中使用以下程式码请求相机权限：

kotlin

import android.os.Bundle
import androidx.activity.enableEdgeToEdge
import androidx.appcompat.app.AppCompatActivity
import androidx.core.view.ViewCompat
import androidx.core.view.WindowInsetsCompat
import android.content.pm.PackageManager
import android.util.Log
import androidx.activity.result.contract.ActivityResultContracts
import androidx.core.content.ContextCompat
import android.Manifest

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        // ...
        
        // 在 onCreate() 函数末尾新增此程式码
        requestCameraPermission()
    }

    companion object {
        private const val TAG = "MainActivity"
        private const val REQUEST_CAMERA_PERMISSION_CODE = 10
        private const val CAMERA_PERMISSION = Manifest.permission.CAMERA
    }

    private fun requestCameraPermission() {
        val requestPermissionLauncher =
            registerForActivityResult(ActivityResultContracts.RequestPermission()) { isGranted: Boolean ->
                if (isGranted) {
                    setupCamera()
                } else {
                    Log.d(TAG, "没有相机权限") // TODO：请自行处理错误
                }
            }

        when (PackageManager.PERMISSION_GRANTED) {
            ContextCompat.checkSelfPermission(this, CAMERA_PERMISSION) -> {
                setupCamera()
            }

            else -> {
                requestPermissionLauncher.launch(CAMERA_PERMISSION)
            }
        }
    }

    override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<String>,
        grantResults: IntArray
    ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        when (requestCode) {
            REQUEST_CAMERA_PERMISSION_CODE -> {
                if ((grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED)) {
                    setupCamera()
                } else {
                    Log.d(TAG, "没有相机权限")
                }
                return
            }

            else -> {} // 忽略所有其他请求。
        }
    }

    private fun setupCamera() {
        // TODO：我们将在下一节中设定。
    }
}

Vital Sign Camera ​

如 Vital Sign Camera 中所述，在 Vitals™ SDK 中，我们提供了一个名为 VitalSignCamera 的特制相机组件。要设定它，要设定 VitalSignCamera，首先请在您的 XML 布局档案 activity_main.xml 中新增一个 FrameLayout 用于相机预览。

xml
<FrameLayout
    android:id="@+id/vital_sign_camera"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

接下来，在 MainActivity.kt 中，宣告 VitalSignCamera 属性：

kotlin
private lateinit var camera: VitalSignCamera

完成 VitalSignCameraEventHandler 接口，用于存取处理结果，例如人脸检测结果、条件检查 结果、扫描阶段和剩余秒数、生命体征等。

kotlin
class MainActivity : AppCompatActivity(), VitalSignCameraEventHandler {
    override fun onVideoFrameProcessed(result: ProcessFrameResult) {
        // TODO：将在后续章节中完成此回呼。 
    }
}

在上面「相机权限」部分宣告的 setupCamera 函数中，使用 createVitalSignCamera 方法建立 VitalSignCamera，然后呼叫 configure 来设定相机。最后，将 VitalSignCamera 绑定到 FrameLayout。例如：

kotlin
private fun setupCamera() {
    // 建立 Vital Sign Camera
    camera = createVitalSignCamera(this, lifecycle, this)

    // 配置相机属性和 Vitals™ 云端服务。
    camera.configure {
        isActive = true

        config = VitalSignEngineConfig().apply {
            serverId = ServerId.awsEnterpriseProd
            apiKey = "__YOUR_API_KEY__"
        }
    }

    // 将相机绑定到 FrameLayout
    findViewById<FrameLayout>(R.id.vital_sign_camera).addView(camera)
}

TIP 提示

在上述范例中，字串 __YOUR_API_KEY__ 应替换为您自己的 API 金钥。请联络我们以取得您的 API 金钥，它是存取 Vitals™ 云端服务的凭证。

运行应用程式，您现在应该能够看到相机预览。有关系统和相机设定的更多详细信息，请参阅 设定相机。

获取用户健康档案 ​

正如 整合 Vitals™ 健康测评（VHA） 中所述，我们必须收集用户的健康档案和病史数据，才能获得个人化的健康测评结果并提高测评的准确性。

您可以将收集到的用户健康档案提供给 camera.configure 区块中的 userInfo 属性。例如：

kotlin
private fun setupCamera() {
    // ...

    // 向 Vitals™ SDK 提供用户健康档案
    camera.configure {
        // ...

        userInfo = UserInfo().apply {
            age = 25.0
            gender = Gender.Male
            userId = "__YOUR_USER_ID__"
        }
    }

    // ...
}

TIP 提示

在上面的范例中，字串__YOUR_USER_ID__应替换为您自己的使用者 ID。请联络我们以取得您的使用者 ID，该 ID 指定了 Vitals™ 云端服务的订阅方案。扫描所获得的生命体征会因订阅方案而异，每个方案都提供一组独特的生命体征。

更多详细信息，请参阅 获取用户健康档案 页面。

扫描生命体征 ​

要开始扫描，您只需呼叫 VitalSignCamera 元件的 startScanning() API 即可。

首先，在您的 XML 布局档案中建立一个开始按钮来启动扫描。

xml
<Button
    android:id="@+id/start_button"
    android:layout_width="250dp"
    android:layout_height="50dp"
    android:text="开始扫描" />

设定 onClick 监听器，并呼叫 startScanning() API。

kotlin
override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    findViewById<Button>(R.id.start_button).setOnClickListener { 
        camera.startScanning() 
    }
}

呼叫 API 后，元件将开始透过相机扫描人脸，持续时间为 30 秒。扫描成功后，将传回生命体征讯息。您可以透过 onVideoFrameProcessed 回呼函数记录扫描进度并观察任何错误。此回调函数以每秒 30Hz 的频率（此频率取决于相机的帧率）传回处理结果。

kotlin
override fun onVideoFrameProcessed(result: ProcessFrameResult) {
    // 如果扫描正在进行，则列印扫描阶段和剩余秒数。
    if (result.healthResult.stage != GetHealthStage.idle) {
        Log.d(TAG, "扫描阶段=${result.healthResult.stage}, 剩余秒数=${result.healthResult.remainingTime}")
    }

    // 若有错误则列印
    if (result.healthResult.error != null) {
        Log.d(TAG, "错误=${result.healthResult.error}")
    }
}

运行应用程式，将你的脸部置于相机预览的中央，点击“开始扫描”按钮。将你的脸部移出相机预览范围，模拟「人脸遗失」错误。你应该在Logcat中看到类似这样的内容：

2025-01-10 10:50:12.144 17560-17773 MainActivity            ai.panoptic.wvs.androidsdksampleapp   D  扫描阶段=collectingData, 剩余秒数=22.919
2025-01-10 10:50:12.180 17560-17773 MainActivity            ai.panoptic.wvs.androidsdksampleapp   D  扫描阶段=collectingData, 剩余秒数=22.882
2025-01-10 10:50:12.251 17560-17773 MainActivity            ai.panoptic.wvs.androidsdksampleapp   D  错误=ai.panoptic.wvs.engine.VSException: face lost
2025-01-10 10:50:12.315 17560-17773 MainActivity            ai.panoptic.wvs.androidsdksampleapp   D  错误=ai.panoptic.wvs.engine.VSException: face lost

有关处理扫描过程的更多详细信息，请参阅 扫描生命体征 页面。

取得并显示健康测评结果 ​

VitalSignCamera 组件会透过 onVideoFrameProcessed 回呼函数传回健康测评结果。在下面的示例程式码中，它会检查心率是否已准备好，并在准备好后将其显示在控制台中。

kotlin
// 更新了 onVideoFrameProcessed 回呼函数
override fun onVideoFrameProcessed(result: ProcessFrameResult) {
    // ...

    // 取得心率结果
    if (result.healthResult.health != null) {
        Log.d(TAG, "心率=${result.healthResult.health?.vitalSigns?.heartRate}")
    }
}

运行应用程式并进行扫描，30秒后，您将能够看到以下心率结果：

2025-01-10 11:02:44.352 20011-20351 MainActivity            ai.panoptic.wvs.androidsdksampleapp   D  扫描阶段=analyzingData, 剩余秒数=0.099999905
2025-01-10 11:02:44.502 20011-20351 MainActivity            ai.panoptic.wvs.androidsdksampleapp   D  扫描阶段=analyzingData, 剩余秒数=0.06799984
2025-01-10 11:02:44.502 20011-20351 MainActivity            ai.panoptic.wvs.androidsdksampleapp   D  心率=81.22924984224709
2025-01-10 11:02:44.646 20011-20351 MainActivity            ai.panoptic.wvs.androidsdksampleapp   D  心率=81.22924984224709

Vitals™ SDK 中提供了更多生命体征测评结果，我们也提供了测评结果的解读指南。更多信息，请参阅 取得并显示健康测评结果 页面。


🎉🎉🎉 恭喜！ 🎉🎉🎉

您已完成您的第一个 Vitals™ 应用程式！


WARNING 重要提示

本指南仅提供使用 Android SDK 的最小可行产品 (MVP)，我们 Vitals™ 云端服务仍提供更多功能和更多操作，以确保测评结果准确可靠。例如：检查扫描条件、使用 信号质量 指标等等。更多详情，请参阅 软体开发指南 页面、示例程式码 或 API 参考。

版权所有 © 2021-至今 PanopticAl Ltd. 保留所有权利。