npm - @cunpingtai/webad-react-ad-scripts - Versions diffs - 0.1.0 → 0.2.0 - Mend

@cunpingtai/webad-react-ad-scripts 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @cunpingtai/webad-react-ad-scripts
-面向 Next.js 和 TanStack React 项目的广告组件包。`AdsProvider` 从 WebAd Cloudflare Worker 读取当前站点策略；各广告组件根据策略决定是否渲染，并对脚本 URL 和参数做失败关闭校验。
+给 Next.js 和 TanStack React 项目使用的中央广告组件包。网站只写广告位名称，具体 Adsterra 参数和显示策略由 WebAd 后台按当前 hostname 下发。
 ## 安装
@@ -10,252 +10,80 @@ pnpm add @cunpingtai/webad-react-ad-scripts
 需要 React 18.3 或 React 19。
-## Next.js App Router
+## 根部接入
-新建一个客户端 Provider。`pageKey` 在每次真实路由切换时变化，因此同一广告位可以在新页面重新初始化；普通 state 更新不会重新加载广告。
+Next.js App Router：
 ```tsx
-// app/advertising-provider.tsx
 "use client";
 import { AdsProvider } from "@cunpingtai/webad-react-ad-scripts";
 import { usePathname } from "next/navigation";
-import type { ReactNode } from "react";
-export function AdvertisingProvider({ children }: { children: ReactNode }) {
+export function AdvertisingProvider({ children }: React.PropsWithChildren) {
   const pathname = usePathname();
   return (
-    <AdsProvider
-      endpoint="https://webad-control-plane.example.workers.dev"
-      pageKey={pathname}
-    >
+    <AdsProvider endpoint="https://a1.yumeref.com" pageKey={pathname}>
       {children}
     </AdsProvider>
   );
 }
 ```
-在根布局中挂载一次：
-```tsx
-// app/layout.tsx
-import { AdvertisingProvider } from "./advertising-provider";
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang="zh-CN">
-      <body>
-        <AdvertisingProvider>{children}</AdvertisingProvider>
-      </body>
-    </html>
-  );
-}
-```
-## TanStack Router / Start
+把 `AdvertisingProvider` 放在根 layout 中一次。TanStack Router 同理，在根路由读取 `state.location.pathname` 作为 `pageKey`。
-在根路由组件中读取当前 pathname：
+`pageKey` 只在真实路由切换时变化。不要传随机数、时间戳、Tab 状态或窗口宽度。
-```tsx
-import {
-  HeadContent,
-  Outlet,
-  Scripts,
-  createRootRoute,
-  useRouterState,
-} from "@tanstack/react-router";
-import { AdsProvider } from "@cunpingtai/webad-react-ad-scripts";
+## 后台配置
-export const Route = createRootRoute({ component: RootComponent });
+打开 `https://a1.yumeref.com/admin`，编辑对应站点：
-function RootComponent() {
-  const pathname = useRouterState({
-    select: (state) => state.location.pathname,
-  });
+- Social Bar、Popunder、Smartlink 每站各配置一个；
+- Banner 和 Native Banner 可以添加多个；
+- 每个页面广告位使用唯一名称，例如 `home-top`、`article-middle`、`sidebar-sticky`；
+- Banner 填脚本地址、广告 Key、宽度和高度；
+- Native Banner 填脚本地址和 Container ID。
-  return (
-    <html lang="zh-CN">
-      <head>
-        <HeadContent />
-      </head>
-      <body>
-        <AdsProvider
-          endpoint="https://webad-control-plane.example.workers.dev"
-          pageKey={pathname}
-        >
-          <Outlet />
-        </AdsProvider>
-        <Scripts />
-      </body>
-    </html>
-  );
-}
-```
+包会用浏览器当前 hostname 自动获取该站点配置，不需要额外传网站标识。
-不要给 `pageKey` 传 `Date.now()` 或随机数。它应当只在真实 SPA 路由切换时变化。
-## 广告组件
-Adsterra 提供的 zone key、脚本 URL 和容器 ID 由使用方传入。不要传整段 HTML。
-### Social Bar
+## 组件
 ```tsx
-import { AdsterraSocialBar } from "@cunpingtai/webad-react-ad-scripts";
-<AdsterraSocialBar
-  slotId="global-social-bar"
-  scriptSrc="https://social.ads-cdn.example/social.js"
-/>;
-```
-Social Bar 在一次完整页面加载中最多初始化一次，仅在 `adsterra-full` 模式显示。
-### Native Banner
-```tsx
-import { AdsterraNativeBanner } from "@cunpingtai/webad-react-ad-scripts";
-<AdsterraNativeBanner
-  slotId="article-native-1"
-  scriptSrc="https://native.ads-cdn.example/widget/invoke.js"
-  containerId="container-native-example"
-  className="my-native-ad"
-/>;
-```
-`containerId` 必须与该 Native Banner 代码对应，并且在当前文档中唯一。
-### Banner 320×50、300×250、728×90
-同一个组件支持不同固定尺寸：
-```tsx
-import { AdsterraBanner } from "@cunpingtai/webad-react-ad-scripts";
-<AdsterraBanner
-  slotId="mobile-top"
-  scriptSrc="https://banner.ads-cdn.example/mobile/invoke.js"
-  zoneKey="exampleMobileZone"
-  width={320}
-  height={50}
-/>
-<AdsterraBanner
-  slotId="content-box"
-  scriptSrc="https://banner.ads-cdn.example/box/invoke.js"
-  zoneKey="exampleBoxZone"
-  width={300}
-  height={250}
-  params={{ placement: "article" }}
-/>
-<AdsterraBanner
-  slotId="desktop-top"
-  scriptSrc="https://banner.ads-cdn.example/wide/invoke.js"
-  zoneKey="exampleWideZone"
-  width={728}
-  height={90}
-/>;
-```
-组件按 Adsterra 原始代码的方式设置 `window.atOptions` 并加载 `invoke.js`，不会自行增加外层 iframe。多个 Banner 会串行初始化，避免互相覆盖 `atOptions`。
-### Smartlink
-```tsx
-import { AdsterraSmartlink } from "@cunpingtai/webad-react-ad-scripts";
-<AdsterraSmartlink
-  href="https://links.example/go?key=example"
-  className="download-button"
->
-  Continue
-</AdsterraSmartlink>;
-```
-Smartlink 是普通 `<a>`，默认新窗口打开，并固定带有 `noopener noreferrer sponsored`。
-### Popunder
-```tsx
-import { AdsterraPopunder } from "@cunpingtai/webad-react-ad-scripts";
-<AdsterraPopunder
-  slotId="global-popunder"
-  scriptSrc="https://pop.ads-cdn.example/pop.js"
-/>;
-```
-Popunder 在一次完整页面加载中最多初始化一次，仅在 `adsterra-full` 模式显示。
-## 策略与显示规则
-| Worker 返回模式   | Native Banner | Banner | Smartlink | Social Bar | Popunder |
-| ----------------- | ------------- | ------ | --------- | ---------- | -------- |
-| `none`            | 否            | 否     | 否        | 否         | 否       |
-| `adsense`         | 否            | 否     | 否        | 否         | 否       |
-| `adsense-limited` | 是            | 是     | 否        | 否         | 否       |
-| `adsterra-safe`   | 是            | 是     | 是        | 否         | 否       |
-| `adsterra-full`   | 是            | 是     | 是        | 是         | 是       |
-AdSense Auto Ads 等全局脚本仍由 Worker 配置中的 `providers.*.scripts` 加载。Adsterra 广告位脚本由上述组件加载，因此使用组件方案时通常把 Worker 的 `adsterra.safeScripts` 和 `adsterra.fullScripts` 留空，避免重复加载。
-## 生命周期与去重
-- 同一个 `pageKey` 中，相同 `slotId` 只初始化一次。
-- React 普通 re-render、Strict Mode effect 重放和同页重新挂载不会产生第二次广告请求。
-- `pageKey` 改变后，Native Banner 和 Banner 可以按新的 page view 重新初始化。
-- Social Bar 和 Popunder 无法可靠卸载，因此一次完整文档生命周期只初始化一次；SPA 路由切换不会重复加载。
-- 不要使用随机 React `key`，也不要因为 resize、Tab、FAQ 展开或游戏状态变化而改变 `pageKey`。
-## AdsProvider 参数与状态
-```ts
-type AdsProviderProps = {
-  endpoint: string;
-  pageKey: string;
-  timeoutMs?: number; // 默认 3000
-  nonce?: string;
-  onStatusChange?: (status: AdsProviderStatus) => void;
-  children: React.ReactNode;
-};
-```
-状态包括 `loading-config`、`disabled`、`loading-scripts`、`ready` 和 `error`。例如：
-```tsx
-<AdsProvider
-  endpoint="https://webad-control-plane.example.workers.dev"
-  pageKey={pathname}
-  nonce={cspNonce}
-  onStatusChange={(status) => {
-    if (status.state === "error") {
-      console.error("Advertising unavailable", status.reason);
-    }
-  }}
->
-  {children}
-</AdsProvider>
+import {
+  AdsterraBanner,
+  AdsterraNativeBanner,
+  AdsterraPopunder,
+  AdsterraSmartlink,
+  AdsterraSocialBar,
+} from "@cunpingtai/webad-react-ad-scripts";
+<AdsterraBanner placement="home-top" />
+<AdsterraNativeBanner placement="article-middle" />
+<AdsterraSmartlink className="download-button">
+  继续下载
+</AdsterraSmartlink>
+<AdsterraSocialBar />
+<AdsterraPopunder />
 ```
-配置请求、响应格式或组件参数无效时，组件失败关闭，不插入对应广告脚本。
+Banner 和 Native Banner 还支持 `className`、`style`。组件找不到对应配置、类型不匹配或当前策略不允许时会返回 `null`。
-## 脚本域名与 CSP
+## 策略
-每个组件的 `scriptSrc` 必须：
+| 模式              | Banner / Native | Smartlink | Social Bar / Popunder |
+| ----------------- | --------------- | --------- | --------------------- |
+| `none`            | 否              | 否        | 否                    |
+| `adsense`         | 否              | 否        | 否                    |
+| `adsense-limited` | 是              | 否        | 否                    |
+| `adsterra-safe`   | 是              | 是        | 否                    |
+| `adsterra-full`   | 是              | 是        | 是                    |
-- 使用 HTTPS；
-- hostname 精确存在于 Worker 的 `ALLOWED_SCRIPT_HOSTS_JSON`；
-- 不包含账号密码、显式端口或 URL fragment。
+同一个 `pageKey` 中，同一个 `placement` 只初始化一次。普通 React re-render 和 Strict Mode 不会重复请求；真实 SPA 路由切换后可以重新初始化。Social Bar 和 Popunder 在整个文档生命周期各只加载一次。
-站点 CSP 至少需要在 `connect-src` 允许 Worker 地址，在 `script-src` 允许实际广告脚本 origin。使用 nonce 时，把同一个 nonce 传给 `AdsProvider`。Smartlink 是链接而不是脚本，它的 hostname 不需要放入脚本 allowlist，除非同一 hostname 也用于加载脚本。
+## CSP
-## 发布前真实页面验证
+站点 CSP 的 `connect-src` 需要允许 `https://a1.yumeref.com`，`script-src` 需要允许后台中实际填写的广告脚本域名。`ALLOWED_SCRIPT_HOSTS_JSON` 只约束 Worker 集中加载的 provider 脚本，不约束这些站点广告位脚本。
-第三方广告脚本可能依赖它被插入页面时的执行环境。首次发布前，请在 Adsterra 已批准的测试域名上分别验证五种组件，尤其确认 Banner 的 `invoke.js` 能正常生成广告且没有 `document.write` 错误。未完成这一步前不要发布生产版本。
+完整的页面布局和广告数量规则见仓库中的 `docs/site-ad-integration-guide.md`。

package/dist/index.d.ts CHANGED Viewed

@@ -30,46 +30,30 @@ type AdsProviderProps = {
 };
 declare function AdsProvider({ endpoint, pageKey, timeoutMs, nonce, onStatusChange, children, }: AdsProviderProps): react.JSX.Element;
-type AdsterraParams = Record<string, string | number | boolean>;
 type AdsterraBannerProps = {
-    slotId: string;
-    scriptSrc: string;
-    zoneKey: string;
-    width: number;
-    height: number;
-    params?: AdsterraParams;
+    placement: string;
     className?: string;
     style?: CSSProperties;
 };
-declare function AdsterraBanner({ slotId, scriptSrc, zoneKey, width, height, params, className, style, }: AdsterraBannerProps): react.JSX.Element | null;
+declare function AdsterraBanner({ placement, className, style, }: AdsterraBannerProps): react.JSX.Element | null;
 type AdsterraNativeBannerProps = {
-    slotId: string;
-    scriptSrc: string;
-    containerId: string;
+    placement: string;
     className?: string;
     style?: CSSProperties;
 };
-declare function AdsterraNativeBanner({ slotId, scriptSrc, containerId, className, style, }: AdsterraNativeBannerProps): react.JSX.Element | null;
+declare function AdsterraNativeBanner({ placement, className, style, }: AdsterraNativeBannerProps): react.JSX.Element | null;
 type AdsterraSmartlinkProps = {
-    href: string;
     children: ReactNode;
     target?: HTMLAttributeAnchorTarget;
     className?: string;
 };
-declare function AdsterraSmartlink({ href, children, target, className, }: AdsterraSmartlinkProps): react.JSX.Element | null;
+declare function AdsterraSmartlink({ children, target, className, }: AdsterraSmartlinkProps): react.JSX.Element | null;
-type AdsterraSocialBarProps = {
-    slotId: string;
-    scriptSrc: string;
-};
-type AdsterraPopunderProps = {
-    slotId: string;
-    scriptSrc: string;
-};
-declare function AdsterraSocialBar(props: AdsterraSocialBarProps): react.JSX.Element;
-declare function AdsterraPopunder(props: AdsterraPopunderProps): react.JSX.Element;
+type AdsterraSocialBarProps = Record<string, never>;
+type AdsterraPopunderProps = Record<string, never>;
+declare function AdsterraSocialBar(_props: AdsterraSocialBarProps): react.JSX.Element;
+declare function AdsterraPopunder(_props: AdsterraPopunderProps): react.JSX.Element;
 export { AdsProvider, type AdsProviderProps, type AdsProviderStatus, AdsterraBanner, type AdsterraBannerProps, AdsterraNativeBanner, type AdsterraNativeBannerProps, AdsterraPopunder, type AdsterraPopunderProps, AdsterraSmartlink, type AdsterraSmartlinkProps, AdsterraSocialBar, type AdsterraSocialBarProps };