设备标识扩展

需要在事件中附带企业自有设备或风险信号时，可配置 Provider。它是可选能力，Web 和 Android 的标准创建入口支持注入；iOS 标准创建入口目前不支持。基础事件采集不依赖 Provider。

接入时需明确以下边界：

• candidateId 仅作辅助关联，不替代业务用户 ID 或安装标识。
• SDK 按字段名过滤已知敏感字段；Provider 自身仍需确保输出不含敏感信息。
• Provider 超时或失败不会阻止业务事件记录。

---

返回哪些数据

Provider 输出由 SDK 规范化为 context.provider 中的 Observation。事件创建时会复制当时可用的结果；后续身份变化不会改写已经入队的事件。

1. 允许返回的字段

Provider 只返回以下字段；SDK 将合格结果写入事件的 context.provider：

字段	类型	说明	示例
providerVersion	String	适配器内部版本或规则包标识	"v2.4.1"
candidateId	String	受控候选标识符（非硬件唯一 ID）	"cand_a8f901c2"
confidence	Number	置信度打分，取值范围 0.0 ~ 1.0	0.85
signals	Object	脱敏后的环境与风控特征键值对	{"riskBand": "low"}
riskHints	Object	针对服务端的处置建议提示	{"needCaptcha": false}
expiresAt	Integer	证据绝对过期时间戳（毫秒级 Epoch）	1758451200000

2. SDK 补充的字段

SDK 自行填写观测时间、平台、版本和 Provider 名称；接入代码无需生成这些字段。

3. 自动脱敏与截断防护

SDK 在接纳 Provider 数据前执行有界处理：

1. SDK 按完整字段名移除已知身份、凭据和设备原始信号字段；不是任意关键词扫描，也不会检查自由文本是否含敏感值。
2. 输出总量不超过 16 KiB；字符串最多 512 字符，嵌套对象和数组也有容量限制。
3. 如果候选标识、置信度、信号和风险提示均无有效值，SDK 不会附加 Provider 结果。

---

平台身份作用域与生命周期

缓存受有效期和当前身份约束。账号切换后，新事件不会复用旧账号的 Provider 结果；已记录事件仍保留记录时的数据。

---

多端接入实现

1. Web / TypeScript

import { TrackBusinessSDK } from '@track-business/sdk-web';
import type { DeviceIntelligenceEvidenceProvider, ProviderEvidence } from '@track-business/sdk-web';

const enterpriseProvider: DeviceIntelligenceEvidenceProvider = {
  name: 'enterprise-risk-engine',
  async identify({ identity, consent }): Promise<ProviderEvidence | null> {
    // 仅在用户授予合规同意后执行
    if (consent !== 'STANDARD' && consent !== 'ADVANCED') return null;

    return {
      providerVersion: '2.0.0',
      candidateId: 'risk-candidate-482', // 适配器生成的候选值，不直接复制身份或硬件标识
      confidence: 0.9,
      signals: { environmentScore: 'safe' },
      riskHints: { highRiskUser: false },
      expiresAt: Date.now() + 10 * 60 * 1000, // 10 分钟有效期
    };
  },
};

const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  provider: enterpriseProvider,
  providerOptions: {
    requiredConsent: 'STANDARD',
    timeoutMs: 150, // Provider 单次求值超时
  },
  policy: { providerPolicy: { enabled: true } },
});

2. Android (Kotlin / Java)

Kotlin

import com.trackbusiness.sdk.TrackBusinessConfig
import com.trackbusiness.sdk.TrackBusinessSDK
import com.trackbusiness.sdk.models.ConsentState
import com.trackbusiness.sdk.models.IdentityState
import com.trackbusiness.sdk.models.ProviderEvidence
import com.trackbusiness.sdk.models.ProviderOptions
import com.trackbusiness.sdk.models.SDKPolicy
import com.trackbusiness.sdk.provider.DeviceIntelligenceEvidenceProvider
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

val sdk = TrackBusinessSDK.create(
    context = applicationContext,
    endpoint = endpoint,
    projectKey = projectKey,
    config = TrackBusinessConfig(
      policy = SDKPolicy(providerEnabled = true),
      providerOptions = ProviderOptions(requiredConsent = "STANDARD", timeoutMs = 200L),
      evidenceProvider = object : DeviceIntelligenceEvidenceProvider {
        override val name = "enterprise-risk-engine"

        override suspend fun identify(
            identity: IdentityState,
            consent: ConsentState,
        ): ProviderEvidence? {
            if (consent.level != "STANDARD" && consent.level != "ADVANCED") return null

            return ProviderEvidence(
                providerVersion = "2.0.0",
                candidateId = "risk-candidate-482",
                confidence = 0.85,
                signals = buildJsonObject { put("riskLevel", "low") },
                riskHints = buildJsonObject { put("reviewRequired", false) },
                expiresAt = System.currentTimeMillis() + 600_000L,
            )
        }
      },
    ),
)

Java

Java 宿主无需调用 Kotlin 协程，使用明确的回调式接口：

JavaDeviceIntelligenceEvidenceProvider provider = new JavaDeviceIntelligenceEvidenceProvider() {
    @Override
    public String getName() {
        return "enterprise-risk-engine";
    }

    @Override
    public void identify(IdentityState identity, ConsentState consent, JavaProviderCallback callback) {
        callback.onResult(new JavaProviderEvidence(
            "2.0.0",
            "candidate-approved",
            0.85,
            System.currentTimeMillis() + 600_000L
        ));
    }
};

TrackBusinessConfig config = TrackBusinessConfig.builder()
    .providerEnabled(true)
    .javaEvidenceProvider(provider)
    .build();

TrackBusinessSDK sdk = TrackBusinessSDK.create(context, endpoint, projectKey, config);

3. iOS (Swift)

iOS 标准工厂 TrackBusinessSDK.create(...) 暂不支持注入 DeviceIntelligenceEvidenceProvider。低层初始化器不配置标准工厂的持久队列与默认 Transport，不能作为替代接入方式。

---

接入测试

可先让 Provider 返回固定的非敏感测试值，检查事件中的 context.provider。再测试超时、异常和账号切换，确认事件仍能记录且不会沿用旧结果。

---

验收要点

接入企业自研 Evidence Provider 后，按以下清单验证行为：

• [ ] 未达到所需授权等级时，Provider 不执行。
• [ ] Provider 失败或超时后，业务事件仍可记录。
• [ ] 敏感字段被过滤，换账号后的事件不携带旧账号候选标识。