Initialize anonymous identity and track registered events

README.md

@@ -32,3 +32,17 @@ export function ServerStatus() {
 ```
 
 非组件场景可以使用 `createClient({ baseUrl }).health()`。
+
+## 事件初始化与上报
+
+将 `AdCloudProvider` 挂到应用入口，默认在用户进入、组件挂载时初始化匿名身份；`useAdCloud().track` 会等待同一个初始化请求完成。
+客户端需配置 `baseUrl`、`appId`、应用 `collectionKey` 和可选 `eventVersion`（默认 1），并在后台注册、发布对应自定义事件。
+例如 `client.track('add_cart', { product_id: 'camera', quantity: 1, category_id: 'digital' })`。
+
+`createClient(...).initialize()` 可用于非 Provider 接入，首次 track 也会自动初始化。提供 `autoInitialize={false}` 可延后 Provider 初始化；track 仍会初始化。
+请求使用 credentials: include，匿名 token 默认保存在按 API 地址和应用隔离的 localStorage，可传入 storage: null 禁用或提供自定义存储。服务器仍提供 HttpOnly Cookie；不能靠设备指纹跨站识别。
+`prepareEvent` 创建带固定 event_id / occurred_at 的可序列化请求，`sendEvent` 可重试同一请求；不要为同一次重试重新调用 track，否则会生成新 ID。本版没有自动重试、离线队列或批量发送。
+服务器错误（未注册、参数错误、凭据错误）作为 Promise rejection 返回调用方。Provider 初始化失败抛出错误，可使用 React ErrorBoundary。
+仅 collectionKey 可配置到 SDK；不得放入 server_key、management_key 或平台 SERVICE_TOKEN。客户端事件是行为信号，不作为付款、投递结果或广告计费的可信证据。
+
+检查：`npm test` 包含 TypeScript 构建和初始化、身份恢复、幂等请求及应用隔离测试。