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. 保留所有權利。