43 lines
1.5 KiB
Markdown
43 lines
1.5 KiB
Markdown
# AGENTS.md — @app/adsense
|
||
|
||
## 职责
|
||
|
||
Google AdSense 接入：**幂等脚本加载** + React 广告位组件。与业务/框架解耦，可被 Astro island 或纯 React 使用。
|
||
|
||
## 结构
|
||
|
||
```
|
||
src/
|
||
loader.ts # loadAdSense / pushAdSense
|
||
types.ts # AdSensePushCommand + Window.adsbygoogle
|
||
react/AdSlot.tsx # <ins class="adsbygoogle"> 组件
|
||
index.ts # 核心导出
|
||
react/index.ts # React 入口（exports: "@app/adsense/react"）
|
||
```
|
||
|
||
## 导出
|
||
|
||
- `@app/adsense`：`loadAdSense`、`pushAdSense`、类型
|
||
- `@app/adsense/react`：`AdSlot`
|
||
|
||
## 行为要点
|
||
|
||
- `loadAdSense(adClient)`：仅浏览器生效；SSR no-op。同一 `adClient` 复用 Promise；页面已有脚本会识别复用；**不支持同时加载多个发布商 ID**。
|
||
- `pushAdSense()`：向 `window.adsbygoogle` 队列 push，渲染已挂载的 `<ins>`。
|
||
- `AdSlot` 属性用 `adSlot` / `adClient`（刻意避开 Astro 的 `slot` / `client:*` 保留字）。挂载后自动 load + push，按 `adClient#adSlot` 去重。
|
||
|
||
## 修改指南
|
||
|
||
- 保持加载幂等；失败时重置 `scriptPromise` 以便重试（见 `loader.ts`）。
|
||
- 不要在本包读 env 或写死 publisher ID——由调用方传入 `adClient`。
|
||
- SSR 安全：凡触碰 `document` / `window` 先判 `typeof`。
|
||
- 新广告格式优先扩展 `AdSlot` props（`format` / `layout` / `layoutKey`…），不要让调用方手写 `<ins>`。
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
yarn workspace @app/adsense typecheck
|
||
yarn workspace @app/adsense lint
|
||
yarn workspace @app/adsense build
|
||
```
|