Track Business SDK

主题外观

最新
文档版本
最新文档✓2026.11.0
AI 文档索引 ↗

授权与隐私 ​

按业务要求设置初始授权状态，并明确允许采集的事件和属性。SDK 提供技术控制；授权告知、同意记录及应用隐私申报由接入方负责。

本页适用于 Web、Android、iOS 客户端。服务端接入需由业务服务在调用 SDK 前判断是否允许上报。

选择初始状态 ​

配置行为使用场景
默认 GRANTED + MINIMAL创建或恢复身份，接收获准事件并调度上传宿主已确认允许基础采集
PENDING不创建身份、不打开分析存储、不请求网络、不缓存事件需要等待用户授权
DENIED停止采集并清理 SDK 自有状态已知用户拒绝或撤回授权

MINIMAL、STANDARD、ADVANCED 表示可采集的数据范围。SDK 的默认状态不代表应用已取得用户授权；需要事前授权时使用 PENDING。应用应保存用户的决定，并在每次创建 SDK 时传入对应状态。setOptOut(true) 仅暂停采集，不替代授权决定。

授权后开始采集 ​

需要事前授权时，先以 PENDING 初始化；Android/iOS 的初始化参数见各平台接入指南。

typescript
import { TrackBusinessSDK } from '@track-business/sdk-web';

const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  initialConsent: { status: 'PENDING' },
});
await sdk.ready();

// 仅在宿主确认用户已同意相应采集后调用
await sdk.grantConsent('STANDARD');
const state = sdk.getConsentState();
kotlin
// sdk 创建时已配置 ConsentDecision.pending()
sdk.grantConsent("STANDARD")
val state = sdk.getConsentState()
swift
// sdk 创建时已配置 initialConsent: .pending
sdk.grantConsent(level: "STANDARD")
let state = sdk.getConsentState()

PENDING 期间的事件与身份修改不会补发。授权后 SDK 恢复可用的本地身份，或创建新身份。

授权激活失败时不会开始采集。Web 请处理 grantConsent() 的错误；Android/iOS 可使用完成回调确认结果。

自动采集的授权要求 ​

事件所需等级见事件与属性字典。手动 $pageview、$app_start、$app_end 最低为 MINIMAL；$sdk_lifecycle、曝光和异常事件要求 STANDARD。Web SPA 路由自动采集插件默认要求 STANDARD，仅有默认 MINIMAL 授权时不会启用。

自动采集还需单独启用对应能力；页面和会话规则见身份与生命周期。

精确位置需要单独的位置授权，基础分析授权不会自动开启。

撤回授权 ​

用户撤回时调用 denyConsent()：

typescript
await sdk.denyConsent();
kotlin
sdk.denyConsent()
swift
sdk.denyConsent()

SDK 会停止采集与发送，并清理自有身份和待发事件；重新授权后使用新身份。需要确认清理完成时，请检查异步结果或完成回调。

本地清理不能删除接收端已有的数据。服务端数据删除需按项目的数据主体权利流程执行。clearUserProperties() 是分析属性操作，不能替代隐私擦除；账号退出的 API 选择见身份与生命周期。

浏览器存储被清除后，应用需重新提供授权决定；有事前授权要求时仍以 PENDING 启动。

敏感字段处理 ​

SDK 在事件入队和上传前，递归检查 properties 与 context 中的字段名。客户端与四种服务端 SDK 使用相同规则：

字段类别默认处理
密码：password、passwd、passcode、pwd替换为 "[REDACTED]"
凭据：token、access_token、refresh_token、id_token、auth_token、bearer_token、session_token、secret、client_secret、client_key、api_key、private_key替换为 "[REDACTED]"
请求凭据：authorization、cookie、set_cookie替换为 "[REDACTED]"
证件及金融凭据：id_card、id_number、national_id、ssn、credit_card、card_number、cvv、cvc替换为 "[REDACTED]"
联系方式与业务 ID，例如 phone、email、user_id默认保留；由项目配置是否脱敏

匹配时忽略大小写，并去除字段名中的非字母数字字符后进行完整名称匹配。例如 access_token 与 Access-Token 等价，tokenizerVersion 不命中 token。对象和数组中的字段同样处理；命中后数字、布尔值或对象也会被替换为字符串。

添加项目字段规则 ​

以下 Web 示例额外过滤手机号与业务 ID：

typescript
const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  privacyPolicy: {
    redactedPropertyNames: ['phone', 'phone_number', 'user_id'],
  },
});

phone 与 phone_number 是两个不同名称，需要分别配置；增加项目规则不会关闭默认凭据保护。iOS 通过创建参数 privacyPolicy 配置 PrivacyPolicy.redactedPropertyNames。Android 当前公开工厂不提供该字段，额外的业务字段应在宿主构造属性时移除或替换。服务端的属性过滤配置见对应语言的 API 文档。

采集前检查 ​

字段名规则无法识别任意自由文本中嵌入的秘密，也不处理事件身份字段。请按业务审查事件名、属性、页面 URL 和身份来源，避免将原始凭据传给 SDK。字段脱敏不代替用途授权或访问控制。

存储与诊断 ​

  • storageAllowed=false 关闭普通分析数据的持久存储，不等于拒绝授权。获准事件仍可通过内存队列尝试上传，页面或进程结束后不能恢复未发送数据。
  • 持久队列初始化失败时可能降级内存；检查 Health/Diagnostics 中的实际后端，参见离线队列。
  • SDK 不会自动上传诊断报告。需要排查时，可按错误码与诊断读取本地状态。
  • 诊断报告不导出完整事件正文，但事件名、错误摘要等可能包含接入方自定义内容；分享前检查并移除敏感信息。

应用商店申报 ​

Android 按实际启用的能力核对Google Play 数据安全申报。iOS 核心隐私清单不含精确位置；使用 TrackBusinessLocation 时需计入该模块的数据类别。最终申报应覆盖整个应用及全部 SDK，参见App Store 隐私申报。