---
title: 设备元数据
description: 返回采集所用设备的元数据（如平台、IP、位置）以及在该设备上检测到的风险信号的能力。
canonical: https://developer.unico.io/zh-CN/dual-api/capabilities/device-metadata
locale: zh-CN
generated_by: markdown-export
---

此能力返回用户进行采集时所用设备的数据，并与已签约的其他产品的结果一同返回。

### 功能说明

收集采集会话中所用设备的元数据以及在该设备上检测到的风险信号（数据详情见下文）。

它不是一项验证：它从不通过或拒绝流程，也从不导致流程失败。请在您自己的风险规则或内部决策引擎中使用这些数据。

### 输入项

无需额外字段。此能力使用流程已有的采集会话。

- **Web 和 Native 合约：** 在为您的账户签约的流程中启用。流程会在 `capacities` 中列出 `PROCESS_CAPACITY_DEVICE_METADATA`。
- **API 合约：** 在您的 API key 的 Recipe 中启用。

> **警告: 元数据依赖于 Unico SDK**
>
> 元数据由 Unico SDK 在采集过程中收集。API 集成可能使用 Unico SDK，也可能不使用：
>
> - **使用 Unico SDK 的 API：** 元数据照常返回。
> - **不使用 Unico SDK 的 API：** 没有元数据，响应为 `not_found`。

如需启用，请联系您的 Unico 对接人。

### 可能的响应

结果位于 `deviceMetadata` 对象中：

- **Web 和 Native 合约：** 位于[获取流程](/dual-api/developers/api-reference/web-sdk/get-process)的 `authenticationInfo.deviceMetadata` 中。
- **API 合约：** 位于[获取流程](/dual-api/developers/api-reference/api/get-process)的 `deviceMetadata` 中。

| `status` | 含义 |
|---|---|
| `found` | 已找到设备元数据。下列字段填入设备收集到的内容。 |
| `not_found` | 此次采集没有设备元数据，例如不使用 Unico SDK 的 API 流程。 |
| `unavailable` | 当时无法获取元数据。流程结果不受影响。 |

当 `status` 为 `found` 时：

| 字段 | 类型 | 描述 |
|---|---|---|
| `deviceId` | string | 设备标识符。 |
| `platform` | string | 采集来源平台，例如 `WEB`、`ANDROID`、`IOS`。 |
| `ip` | string | 设备的 IP 地址。 |
| `ipCountry` | string | IP 地址所属国家。 |
| `ipGeoCoordinates` | object | IP 地址的位置（`lat`、`lng`）。 |
| `gpsCoordinates` | object | 设备 GPS 报告的位置（`lat`、`lng`）。 |
| `osName` | string | 操作系统名称。 |
| `osVersion` | string | 操作系统版本。 |
| `browserName` | string | 浏览器名称。仅限 Web。 |
| `userAgent` | string | 浏览器 user agent。仅限 Web。 |
| `appStore` | string | 您的应用的安装来源应用商店。仅限原生 SDK。 |
| `detectedSignals` | array of strings | 在设备上检测到的风险信号组。未检测到任何信号时为空。 |

设备未收集的字段在 Web 和 Native 合约中缺失，在 API 合约中为 `null`。

`detectedSignals` 仅列出检测到的组。当某个组中至少有一个信号被发现时，该组即被视为检测到：

| 组 | 含义 |
|---|---|
| `origin_obfuscated` | 访问的真实来源被隐藏，例如通过 Tor 或反指纹工具。 |
| `untrusted_location` | 位置可能是虚假的，例如通过代理、VPN 或 GPS 伪装工具。 |
| `environment_altered` | 设备环境被篡改，例如模拟器，或已 root 或越狱的设备。 |
| `app_manipulated` | 应用被篡改、hook 或调试。 |
| `assisted_session` | 可能有他人在操控会话，例如通过屏幕共享或机器人。 |
| `payload_untrusted` | 设备发送的数据被篡改。 |

并非每个信号都存在于每个平台上，因此同一设备在 Web 和原生 SDK 上可能显示不同的组。

### 可用性

| 接入面 | 支持 |
|---|:-:|
| **SDK**（Android、iOS、Flutter）| ✅ |
| **Web**（iFrame、Redirect）| ✅ |

### 有效组合

设备元数据不属于[可用流程](/dual-api/capabilities/available-flows)中预先组合的 `flow` 目录。它在为您的账户签约的流程中（Web 和 Native 合约）或在您的 API key 的 Recipe 中（API 合约）启用，并可与 Web 和 SDK 集成中的任何其他 Unico 产品一起启用。

### 使用此能力的用例

它可以添加到 Web 和 SDK 集成中的任何 Unico 用例。