AdCloud React SDK

面向开发者和 coding agent 的广告云埋点与广告推送系统 React SDK，配套 adcloud-server。

当前为开发脚手架，提供健康检查客户端及 React Hook；埋点与广告推送功能待实现。

开发

npm ci
npm run typecheck
npm run build

使用

本包尚未发布。先运行 npm run build，再在 React 项目中安装本地目录：

npm install /absolute/path/to/adcloud-react-sdk

import { useHealth } from "@entroia/adcloud-react-sdk";

export function ServerStatus() {
  const { data, error, loading } = useHealth("http://localhost:8000");
  if (loading) return <p>加载中</p>;
  if (error) return <p>{error.message}</p>;
  return <p>{data?.status}</p>;
}

非组件场景可以使用 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 初始化失败通过可选 onInitializationError 回调报告，不中断客户页面。仅 collectionKey 可配置到 SDK；不得放入 server_key、management_key 或平台 SERVICE_TOKEN。客户端事件是行为信号，不作为付款、投递结果或广告计费的可信证据。

检查：npm test 包含 TypeScript 构建和初始化、身份恢复、幂等请求及应用隔离测试。

登录/身份缝合后，可把受控登录接口返回的新匿名身份传给 client.updateIdentity，更新 SDK 缓存；退出登录调用 client.resetIdentity，签发新匿名身份并覆盖本地存储。SDK 不持有身份管理接口的服务端凭据。