站长广告 Pro (SiteAdPro) - 配置说明与使用手册

站长广告 Pro · SiteAdPro

Yojack 出品的 Z-BlogPHP 全站广告管理套件。覆盖 30 个可插入广告位（顶底通栏、对联浮层、弹窗、列表插入、侧栏、文章正文、搜索/404 等），零改主题模板 Hook 自动注入；支持 PC/移动分素材、可视化向导、大模型 AI 流式生成、投放规则引擎、曝光点击统计、JSON 备份迁移与 BlumaAd 无缝升级。

🌐 演示预览：https://ztwd.cn 作者网站

🚀 推荐工作流程（5 步上线）

素材库：用「可视化向导」或「AI 生成」创建广告 HTML/CSS/JS，或点内置预设模板。
广告位：新增广告位 → 选择 Slot 位置 → 绑定素材 → 配置投放规则（页面/设备/分类/弹窗等）。
保存：点击导航栏右侧「保存配置」或按Ctrl+S/⌘+S（广告位页保存当前展开项）。
开启展示：将列表行「展示中」开关打开，前台即可输出。
统计 / 设置：在「统计」看曝光点击；在「设置」调全局策略、诊断主题 Hook、导出 JSON 备份。

⚙️ 插件后台各配置页详细说明

TAB 1 概览 (Dashboard)

插件首页仪表盘，进入后台默认 Tab，一眼掌握运行状态。
📊 今日曝光 / 点击 / CTR：当天全站汇总；CTR = 点击 ÷ 曝光 × 100%。
🟢 活跃广告位：当前「展示中」且通过定时窗口校验的配置数量。
📍 已用 Slot：至少有一条配置的插入位置数 / 全部 30 个 Slot，帮助评估覆盖度。
🔧 主题兼容：Hook 注入是否正常；异常时进入「设置 → 主题兼容诊断」查看详情。
📝 最近操作：保存、删除、导入等审计日志摘要（操作者与时间）。

TAB 2 广告位 (Placements) — 列表与批量

全站广告投放核心页，每条配置对应前台一个 Slot 上的一次投放（侧栏 Slot 可建多条随机插入）。
➕ + 新增广告位：弹窗选择 Slot 与可选素材，确认后出现在折叠列表。
☑️ 批量操作：全选 → 批量开启/关闭；下拉选素材 →「应用到选中」批量写入 PC 内容。
🔀 单行开关：「展示中 / 已关闭」滑块控制是否前台输出；切换后自动保存。
✏️ 编辑 / 复制 / 删除：轻量弹窗改位置与素材；复制可快速克隆到新 Slot；删除需二次确认。
▸ 展开面板：点击行首箭头展开完整表单；URL 带 &open=ID 可自动展开指定项。

TAB 2 广告位 (Placements) — 展开编辑面板

展开后分为四个紧凑区块，统一使用右上角「保存配置」或Ctrl+S保存（无单独保存栏）。
① 位置与素材（一行五列）：广告位位置 · 绑定素材 · 应用素材 · 开始时间 · 结束时间。
② 投放规则与权重：同 Slot 竞争策略、权重、页面/设备 Pill 多选、分类树可视化勾选、蜘蛛隐藏、每日上限、弹窗行为、访客关闭记忆等。
③ 前台预览：编辑 HTML/CSS 时实时渲染；弹窗/浮层类 fixed 元素在预览 iframe 内自动转为相对定位便于查看。
④ 广告内容：PC HTML、移动 HTML（留空用 PC）、CSS、JS；原样注入前台，定位由插件 slot-position.css 处理。

TAB 3 素材库 (Materials)

可复用广告代码包，多条广告位可引用同一素材；修改素材后需在广告位「应用素材」才会同步到已保存内容。
🎨 内置预设：组合广告、图片横幅、自适应文字链等，新建页点卡片一键填充。
📋 列表字段：ID（用于短代码 {#SiteAdPro id=N#}）、名称、编辑/删除。
➕ + 新建素材：导航栏右侧蓝钮，进入创作工作室。

STUDIO 新建 / 编辑素材 · 创作工作室

三种创建方式，Tab 切换，结果填入下方 HTML / CSS / JS 区。
📝 代码编辑：手写 HTML/CSS/JS，适合联盟代码或复杂特效；右侧 iframe 实时预览。
🧙 可视化向导：图片横幅（URL+链接+宽度）、文字链接组（文字|链接 每行一条）、联盟代码包裹 responsive 容器。
🤖 AI 生成：自然语言描述广告样式，选类型/主色/链接；需先在「AI 大模型接口配置」保存 API Key。
💾 保存素材：表单顶部独立「保存素材」按钮（与全局「保存配置」不同，仅保存当前素材）。

AI AI 流式生成过程弹窗

点击「AI 生成代码」后立即弹出，SSE 实时展示大模型工作过程（与 SeoGeo Pro 同级流式体验）。
🧠 思考过程：若模型支持 reasoning_content 等推理链，逐 token 滚动显示。
📤 生成输出：JSON / 代码 content 流式输出；不支持独立思考链的模型也会在此区实时显示 token。
✅ 完成：自动解析 JSON 填入 HTML/CSS/JS，刷新右侧预览；「复制全部」可导出完整日志便于排查。

TAB 4 统计 (Statistics)

曝光 / 点击 / CTR 数据分析，前台 frontend.js 异步上报至 api/track.php。
📈 近 7 日趋势：按日汇总曝光、点击、CTR。
🎯 按广告位投放：各 pl_ID + Slot 分项对比（统计 ID 实际为广告位 ID，非素材 ID）。
📍 按 Slot：哪个插入位置整体流量最大。
⚙️ 懒加载曝光：在「设置」开启后，广告进入视口才计曝光，数据更贴近真实可见量。

TAB 5 设置 (Settings) · 导入导出 · 主题诊断

全局策略与运维，修改后点右上角「保存配置」。
🔌 总开关：关闭后全站不输出广告，配置保留。
🕷️ 对蜘蛛隐藏：全局默认；单条广告位可单独覆盖。
📄 列表每 N 条插入：list_between 密度 2–20。
🎲 同 Slot 多投放默认策略：全部展示 / 权重抽一条 / 随机一条。
👁️ 懒加载曝光 · PJAX 重绑：适配长页与无刷新主题。
🔍 主题兼容诊断：检测关键 Hook；针对 jcode 等主题给出侧栏短代码等修复建议。
💾 JSON 导入 / 导出：整站备份迁移；合并或替换模式。

TAB 6 AI 大模型接口配置 (LLM API)

AI 生成广告的「发电机」，交互对齐 SeoGeo Pro 独立 Tab。
🔘 启用 AI 生成广告：滑块开关；关闭后素材页 AI Tab 不可用。
🤖 接口提供商：DeepSeek / OpenAI / 自定义 OpenAI 兼容（如 agnes-ai 等）。
🔑 API Key：password 输入，聚焦或输入时显示明文；留空保存表示不修改已存 Key。
🌐 Endpoint / Model：留空 Endpoint 用官方默认；可填完整 .../chat/completions 地址。
🧪 测试联通性 / 测试生成：读取已保存配置发真实请求；请先保存再测。
💾 保存：导航栏「保存配置」或Ctrl+S。

TAB 7 操作手册 (In-Plugin Manual)

插件内置百科全书，无需离开后台即可查阅。
📑 左侧目录：快速入门、各 Tab 说明、投放规则字段、AI、短代码、30 个 Slot ID 一览、FAQ 等。
📖 右侧正文：每个按钮/字段均有「用途 + 使用方法」说明，含Ctrl+S快捷键提示。
🔗 本 readme.html 为应用中心展示版，含各页截图；后台「操作手册」Tab 为在线动态版。

EDITOR 文章编辑扩展

编辑文章（非独立页）时，编辑器下方自动出现 SiteAdPro 面板。
📌 段落后插入（第 N 段）：控制 article_paragraph Slot 插入在第几段之后（1=第一段后，2=第二段后…）。
需先在广告位页创建并开启 article_paragraph 配置；正文前/后/中间由广告位页统一管理。

FRONTEND 前台广告效果与行为

访客侧自动能力（无需主题改模板）：
🎯 30 个 Slot：顶栏、对联、弹窗、列表间、侧栏随机、文章段落、搜索/404 等。
👆 点击统计：广告区内链接点击上报。
❌ 关闭记忆：弹窗/浮层允许关闭后 localStorage 记录 N 天内不再展示。
📱 PC / 移动分素材：移动 HTML 留空则回退 PC 内容。
📎 短代码：{#SiteAdPro id=3#} 按素材输出；{#SiteAdPro slot=header_bar#} 按 Slot 规则输出；兼容 {#BlumaAd ...#}。

📍 30 个广告位 Slot 分组速查

分组	代表 Slot ID	说明
全站框架	`global_head` `global_footer`	Head/Footer 统计与脚本
顶底通栏	`header_bar` `footer_bar`	页面顶/底通栏
浮层	`float_couplet_left` `float_corner_br`	对联、四角固定、漂浮
弹窗	`popup_delay` `popup_exit`	延时/离开/点击弹窗
列表	`list_between`	每 N 篇文章插入一条
侧栏	`sidebar`	可多条，随机插入侧栏模块
文章	`article_paragraph`	段落后/正文前中后
页面	`search_top` `error_404`	搜索页、404 页

完整 ID 列表见后台「操作手册 → 广告位 ID 一览」。

站长广告 Pro · by Yojack