事件级位置快照

Web、iOS 和 Android 支持由宿主应用显式提供、仅用于单个事件的位置快照。SDK 不读取设备位置、不申请定位权限，也不会缓存坐标或自动为其他事件附加位置。

接入顺序

明确业务用途并取得用户授权。若需读取设备位置，由应用处理系统定位权限和精度设置。
用户同意后调用 grantLocationConsent()。位置授权默认关闭，且每次启动都需重新确认。Android/iOS 也可在创建时传入 initialLocationConsent: true，前提是本次启动已确认授权。
获取坐标、坐标系和采样时间，调用 trackWithLocation。授权缺失或坐标非法时，事件仍会记录，但不附加 context.geo。
用户撤销授权时调用 revokeLocationConsent()，等待其完成后再把清理视为完成。SDK 会从待发、已租约和死信队列删除整条含位置事件，同时保留无位置事件。已经发出并到达网络的请求无法召回；服务端已接收的数据删除应由宿主的服务端隐私流程处理。

// Web；坐标和授权状态由应用提供。
await sdk.grantLocationConsent();
sdk.trackWithLocation(
  'store_visit',
  { storeId: 'store_42' },
  {
    latitude: 31.2304,
    longitude: 121.4737,
    coordinateSystem: 'WGS84',
    observedAt: Date.now(),
    accuracyMeters: 25,
  },
);
await sdk.revokeLocationConsent();

kotlin

// Android；Java 应用使用 Map 重载、LocationSnapshot 与 SDKActionCallback。
sdk.grantLocationConsent()
sdk.trackWithLocation(
    "store_visit", mapOf("storeId" to "store_42"),
    LocationSnapshot(31.2304, 121.4737, "WGS84", System.currentTimeMillis(), 25.0),
)
sdk.revokeLocationConsent() // Kotlin suspend；Java 使用 callback 重载。

swift

// iOS 可选模块 TrackBusinessLocation。核心包不声明精确位置。
import Foundation
import TrackBusinessLocation
sdk.grantLocationConsent()
sdk.trackWithLocation("store_visit", properties: ["storeId": .string("store_42")],
    location: LocationSnapshot(latitude: 31.2304, longitude: 121.4737,
        coordinateSystem: "WGS84", observedAt: Int64(Date().timeIntervalSince1970 * 1000),
        accuracyMeters: 25))
try sdk.revokeLocationConsent()

事件与队列语义

context.geo 只包含 latitude、longitude、coordinateSystem、observedAt 和可选 accuracyMeters。纬度范围为 [-90, 90]，经度为 [-180, 180]，坐标系只允许 WGS84、GCJ02、BD09，采样时间不能在未来且不能早于事件创建时间 5 分钟。无效快照不进入事件。重试保留创建时的原始快照与 eventId；通用预置上下文和 beforeSend 不能注入或改写 context.geo。

撤销后重新授权只对新事件生效，不会恢复旧事件的位置。清理失败时 SDK 会向宿主报告错误，位置授权仍保持关闭；宿主应处理错误并确认清理结果。

重新启动且未续授位置授权时，SDK 会在发送前清除本地待发位置事件。App 与 H5 集成不会绕过授权：Android 会移除转发事件中的 geo；WebView 如需记录位置，应单独设计授权与桥接流程。诊断报告和日志不应记录原始坐标。

隐私与发布核对

使用该能力的应用应按实际用途、授权流程、精度、保留期、服务端处理和共享对象更新自己的隐私说明。SDK 没有定义服务端位置数据保留或删除 SLA。
Android 核心库不声明位置权限；宿主若读取设备位置，由宿主配置权限并核对 Google Play Data Safety。Google 的数据安全说明将精确位置单列，并要求开发者包含 SDK 处理的数据。
iOS 核心包不声明精确位置。需要宿主注入经纬度时再链接可选模块 TrackBusinessLocation，该模块的隐私清单声明 PreciseLocation。未链接该模块的 App 不会从本 SDK 聚合出精确位置。Apple 的隐私清单说明要求第三方 SDK 描述其可收集的数据类型；宿主仍须核对最终 App 的隐私标签与实际流程。Android 继续把宿主注入接口留在核心库，且不声明定位权限。

接入验证

未授予位置用途授权时，确认事件不含 context.geo。
授权后发送有效位置快照，核对接收记录中的坐标系、采样时间和业务事件；测试记录中不要保存原始坐标。
在隔离测试环境中暂时断网，创建位置事件和普通事件，撤销授权并等待完成，再恢复网络；确认未发送的位置事件已被删除，普通事件仍可上报。
重启应用，确认未重新授权前不发送位置事件。若宿主读取系统位置，另行验证权限拒绝、精度设置和撤销流程。

上传确认方法见数据校验，应用披露见 Google Play 数据安全和 App Store 隐私。

事件级位置快照 ​

接入顺序 ​

事件与队列语义 ​

隐私与发布核对 ​

接入验证 ​

事件级位置快照

接入顺序

事件与队列语义

隐私与发布核对

接入验证