> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elata.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# 指标与分数

> 使用 @elata-biosciences/app-metrics 记录事件和分数，并为生物特征评分做贡献。

## 概述

`@elata-biosciences/app-metrics` 为你的应用提供按用户存储的**事件记录**和**分数**，以及用于为用户跨应用生物特征评分做贡献的 `reportAffect`。

```bash theme={null}
npm install @elata-biosciences/app-metrics
```

```ts theme={null}
import { createMetricsClient } from '@elata-biosciences/app-metrics';

const metrics = createMetricsClient();
await metrics.ready();

await metrics.record({ type: 'level_complete', data: { level: 3, time: 42 } });
await metrics.saveScore({ value: 1200, meta: { level: 3 } });

const best = await metrics.loadScores({ order: 'value_desc', limit: 10 });
const recent = await metrics.query({ type: 'level_complete', limit: 20 });
```

数据仅限于（用户，应用）组合，绝不会跨应用共享。Elata 会保留一份本地副本，并为已登录用户同步到其账户，使数据跟随用户跨设备。这些记录也是你的[分析数据](/cn/apps/operate/analytics-and-health)的来源。

***

## API

| 方法 | 作用 |
| - | - |
| `ready()` | 与 Elata 的连接建立后 resolve |
| `record({ type, data })` | 存储一条事件记录 |
| `query({ type?, since?, until?, limit? })` | 读取记录 |
| `clear()` | 删除该用户在此应用中的所有记录 |
| `saveScore({ value, meta? })` | 存储一个数值分数 |
| `loadScores({ order?, since?, until?, limit? })` | 读取分数。`order` 为 `"value_desc"` 或 `"timestamp_desc"`。 |
| `reportAffect(report)` | 为生物特征评分贡献一次会话结果（见下文） |
| `dispose()` | 销毁客户端 |

### 限制

* 每条记录最多 64 KB。
* 每个（用户，应用）组合有 5 MB 存储配额。
* 超出限制时，调用会以 `quota_exceeded`、`invalid_payload` 或 `rate_limited` 失败。

错误以 `MetricsClientError` 抛出，其 `code` 为上述宿主错误码之一，或 `handshake_timeout`、`disposed`、`transport`。

***

## reportAffect

`reportAffect` 向 Elata 发送**派生的会话结果**（绝不是原始信号），用于为用户的跨应用生物特征评分做贡献。

```ts theme={null}
const result = await metrics.reportAffect({
  dimension: 'calm',      // 'calm' | 'stress' | 'focus'
  baselineValue: 0.42,    // 0..1
  sessionValue: 0.61,     // 0..1
  delta: 0.19,            // -1..1
  meanHr: 68,             // 可选，会话平均心率
  signalQuality: 0.85,    // 0..1
  confidence: 0.8,        // 0..1
  source: 'rppg',
  durationSec: 300,
});
// result: { accepted, calibrating, score }
```

| 结果字段 | 含义 |
| - | - |
| `accepted` | 若样本被丢弃（例如质量过低）则为 `false` |
| `calibrating` | 在用户样本足够形成稳定评分之前为 `true` |
| `score` | 校准完成后的用户评分（0 到 100），否则为 `null` |

必须同时满足以下两点，否则调用会以 `scope_denied` 失败：

1. **你的应用拥有 `biometrics` 权限。** 请联系 Elata 团队为你的应用开启。
2. **用户已同意。** 使用 [`elata:consent:request`](/cn/apps/platform/consent-and-insights) 请求同意。Elata 还会在服务器端针对每个样本重新检查同意状态。

***

## 面向宿主

该包还提供宿主入口 `@elata-biosciences/app-metrics/host`（`createMetricsHost`），供 Elata 自身使用。应用开发者不需要它。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.