@cunpingtai/webad-react-ad-scripts

给 Next.js 和 TanStack React 项目使用的中央广告组件包。网站只写广告位名称，具体 Adsterra 参数和显示策略由 WebAd 后台按当前 hostname 下发。

安装

pnpm add @cunpingtai/webad-react-ad-scripts

如果 pnpm 报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION，请在使用方项目根目录的 pnpm-workspace.yaml 中只豁免本包，然后重新安装：

minimumReleaseAgeExclude:
  - "@cunpingtai/webad-react-ad-scripts"

这是使用方项目的供应链等待策略，不是包安装失败。也可以设置 minimumReleaseAge: 0 完全关闭检查，但不推荐。详见完整接入指南。

需要 React 18.3 或 React 19。

根部接入

Next.js App Router：

"use client";

import { AdsProvider } from "@cunpingtai/webad-react-ad-scripts";
import { usePathname } from "next/navigation";

export function AdvertisingProvider({ children }: React.PropsWithChildren) {
  const pathname = usePathname();
  return (
    <AdsProvider endpoint="https://a1.yumeref.com" pageKey={pathname}>
      {children}
    </AdsProvider>
  );
}

把 AdvertisingProvider 放在根 layout 中一次。TanStack Router 同理，在根路由读取 state.location.pathname 作为 pageKey。

pageKey 只在真实路由切换时变化。不要传随机数、时间戳、Tab 状态或窗口宽度。

本地开发环境不会显示广告。localhost、*.localhost、127.0.0.1 和 ::1 不会请求中央配置。

后台配置

打开 https://a1.yumeref.com/admin，编辑对应站点：

• Social Bar、Popunder、Smartlink 每站各配置一个；
• Banner 和 Native Banner 可以添加多个；
• 当前统一使用三个 Banner 名称：placement-728x90、placement-320x50、placement-300x250；Native Banner 使用 placement-native；
• Banner 填脚本地址、广告 Key、宽度和高度；
• Native Banner 填脚本地址和 Container ID。

包会用浏览器当前 hostname 自动获取该站点配置，不需要额外传网站标识。

组件

import {
  AdsterraBanner,
  AdsterraNativeBanner,
  AdsterraPopunder,
  AdsterraSmartlink,
  AdsterraSocialBar,
} from "@cunpingtai/webad-react-ad-scripts";

<AdsterraBanner placement="placement-728x90" />
<AdsterraBanner placement="placement-300x250" />
<AdsterraNativeBanner placement="placement-native" />

<AdsterraSmartlink className="download-button">
  继续下载
</AdsterraSmartlink>

<AdsterraSocialBar />
<AdsterraPopunder />

这些是后台广告位名称，不是自动识别的尺寸参数；后台配置的尺寸必须与名称对应。同一页面中的同一个 placement 只加载一次。Banner 和 Native Banner 还支持 className、style。组件找不到对应配置、类型不匹配或当前策略不允许时会返回 null。

策略

| 模式 | Banner / Native | Smartlink | Social Bar / Popunder | | ----------------- | --------------- | --------- | --------------------- | | none | 否 | 否 | 否 | | adsense | 否 | 否 | 否 | | adsense-limited | 是 | 否 | 否 | | adsterra-safe | 是 | 是 | 否 | | adsterra-full | 是 | 是 | 是 |

同一个 pageKey 中，同一个 placement 只初始化一次。普通 React re-render 和 Strict Mode 不会重复请求；真实 SPA 路由切换后可以重新初始化。Social Bar 和 Popunder 在整个文档生命周期各只加载一次。

CSP

站点 CSP 的 connect-src 需要允许 https://a1.yumeref.com，script-src 需要允许后台中实际填写的广告脚本域名。ALLOWED_SCRIPT_HOSTS_JSON 只约束 Worker 集中加载的 provider 脚本，不约束这些站点广告位脚本。

完整的页面布局和广告数量规则见仓库中的 docs/site-ad-integration-guide.md。