51 lines
2.7 KiB
Markdown
51 lines
2.7 KiB
Markdown
# AdCloud React SDK
|
|
|
|
面向开发者和 coding agent 的广告云埋点与广告推送系统 React SDK，配套 `adcloud-server`。
|
|
|
|
当前为开发脚手架，提供健康检查客户端及 React Hook；埋点与广告推送功能待实现。
|
|
|
|
## 开发
|
|
|
|
```sh
|
|
npm ci
|
|
npm run typecheck
|
|
npm run build
|
|
```
|
|
|
|
## 使用
|
|
|
|
本包尚未发布。先运行 `npm run build`，再在 React 项目中安装本地目录：
|
|
|
|
```sh
|
|
npm install /absolute/path/to/adcloud-react-sdk
|
|
```
|
|
|
|
```tsx
|
|
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 不持有身份管理接口的服务端凭据。
|