qb-pc-sdk 1.1.8 → 1.1.9

package/README.md

@@ -2,10 +2,108 @@
 
 趣变广告 SDK 封装器 - PC端广告接入工具
 
-> ⚠️ **重要提示**：目前 PC SDK 仅支持 Windows 系统接入，Mac 系统会报错，接入时请注意。
+> ✅ **系统兼容性**：SDK 会自动检测运行环境，仅在 Windows 系统下加载广告。在 Mac、Linux、移动端等非 Windows 环境下会静默处理，不会报错，页面可正常使用。
 
 自动处理多级接口映射与原生渲染逻辑，简化广告接入流程。从 1.0.1 起，浏览器环境会自动加载底层依赖 `qb-pc-ad-sdk-origin`，常规打包场景开箱即用。
 
+## 适用场景
+
+### ✅ 支持的场景
+
+#### 1. PC 端网页（浏览器环境）
+
+**完全支持，推荐使用：**
+- ✅ **Windows 系统下的所有浏览器**
+  - Chrome、Edge、Firefox、360 浏览器、QQ 浏览器、搜狗浏览器等
+  - 支持所有现代浏览器（IE 11+）
+- ✅ **访问方式**
+  - 直接访问网页
+  - 通过书签访问
+  - 通过搜索引擎访问
+- ✅ **网页类型**
+  - 静态 HTML 网站
+  - 动态网站（PHP、ASP.NET、JSP 等）
+  - 单页应用（SPA）
+  - 第三方建站平台（WordPress、Discuz! 等）
+
+#### 2. PC 客户端（WebView 环境）
+
+**支持，需要满足以下条件：**
+
+- ✅ **基于 Chromium/CEF 的桌面应用**
+  - Electron 应用（如 VS Code、Discord、Slack 等）
+  - CEF（Chromium Embedded Framework）应用
+  - Tauri 应用
+  - NW.js 应用
+- ✅ **运行环境要求**
+  - 必须在 **Windows 系统** 上运行
+  - WebView 必须支持 JavaScript 和现代 Web API
+  - 必须允许加载外部 CDN 资源
+- ⚠️ **注意事项**
+  - 确保 WebView 运行在 Windows 系统上（Mac/Linux 上运行会静默处理）
+  - 确保网络连接正常（需要加载 CDN 资源）
+  - 如果应用有 CSP（内容安全策略）限制，需要允许 `pcsdk.qubiankeji.com` 域名
+
+**接入示例（Electron）：**
+```javascript
+// main.js
+const { app, BrowserWindow } = require('electron');
+
+function createWindow() {
+  const win = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true
+    }
+  });
+  
+  // 加载包含广告的网页
+  win.loadURL('https://your-website.com');
+}
+
+app.whenReady().then(createWindow);
+```
+
+```html
+<!-- 在您的网页中正常使用 SDK -->
+<ins class="qb-adsbyqubian"
+     style="display:block; width:400px; height:220px;"
+     data-app-id="your-app-id"
+     data-placement-id="your-placement-id">
+</ins>
+<script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js" async></script>
+<script>(window.qbAds = window.qbAds || []).push({});</script>
+```
+
+#### 3. 第三方建站平台
+
+**完全支持，推荐使用即插即用模式：**
+- ✅ WordPress、Discuz!、Drupal、Joomla 等 CMS
+- ✅ 凡科建站、建站之星等可视化建站工具
+- ✅ 有赞、微盟等电商平台
+- ✅ Hexo、Jekyll、Hugo 等静态网站生成器
+
+### ❌ 不支持的场景
+
+- ❌ **Mac 系统**：会自动检测并静默处理，不加载广告，页面正常运行
+- ❌ **Linux 系统**：会自动检测并静默处理，不加载广告，页面正常运行
+- ❌ **移动端**：会自动检测并静默处理，不加载广告，页面正常运行（请使用移动端专用 SDK）
+- ❌ **纯原生客户端**：非 WebView 环境的原生应用（如 C++、C# 原生应用，不包含浏览器引擎）
+- ❌ **无网络环境**：需要网络连接加载 CDN 资源
+
+### 🔍 环境检测机制
+
+SDK 会自动检测运行环境：
+- **Windows 系统**：✅ 正常加载和显示广告
+- **非 Windows 系统**：✅ 静默处理，不发起广告请求，页面正常运行，不会报错
+
+**检测逻辑：**
+- 通过 `navigator.platform` 和 `navigator.userAgent` 检测操作系统
+- 仅在检测到 Windows 系统时加载广告
+- 其他环境（Mac、Linux、移动端）自动跳过，不报错，不影响页面正常使用
+
 ## 安装
 
 ### NPM 方式（推荐）
@@ -16,10 +114,10 @@ npm install qb-pc-sdk
 
 ### CDN 方式
 
-无需安装，直接在 HTML 中引入一个文件即可（使用 jsdelivr CDN，国内访问更快更稳定）：
+无需安装，直接在 HTML 中引入一个文件即可：
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/qb-pc-sdk@latest/qb-pc-sdk.js"></script>
+<script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js"></script>
 ```
 
 ## 使用方法
@@ -104,8 +202,7 @@ new AdSDK({
     <div id="ad-container"></div>
 
     <!-- 只需引入一个文件，会自动加载底层 SDK 和封装 SDK -->
-    <!-- 使用 jsdelivr CDN（国内访问更快更稳定） -->
-    <script src="https://cdn.jsdelivr.net/npm/qb-pc-sdk@latest/qb-pc-sdk.js"></script>
+    <script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js"></script>
     
     <!-- 使用 SDK -->
     <script>
@@ -164,20 +261,29 @@ new AdSDK({
 如果需要使用特定版本，可以指定版本号：
 
 ```html
-<!-- 使用最新版本（推荐使用 jsdelivr CDN，国内访问更快更稳定） -->
-<script src="https://cdn.jsdelivr.net/npm/qb-pc-sdk@latest/qb-pc-sdk.js"></script>
-
-<!-- 使用指定版本 -->
-<script src="https://cdn.jsdelivr.net/npm/qb-pc-sdk@1.1.3/qb-pc-sdk.js"></script>
+<!-- 使用最新版本 -->
+<script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js"></script>
 ```
 
-### 方式三：WordPress 即插即用模式（推荐用于建站平台）
+### 方式三：即插即用模式（推荐用于所有建站平台）
+
+专为**所有建站平台**设计的**零代码接入方式**，客户只需复制粘贴即可使用，无需任何技术背景。
 
-专为 WordPress 等建站平台设计的**零代码接入方式**，客户只需复制粘贴即可使用，无需任何技术背景。
+**支持的建站平台：**
+- ✅ **WordPress** - 在文章或页面中插入 HTML 代码块
+- ✅ **Discuz!** - 在模板文件中插入 HTML 代码（X3.5 及所有版本）
+- ✅ **其他 CMS** - Drupal、Joomla、Typecho、帝国CMS、织梦CMS、PHPCMS 等
+- ✅ **静态网站生成器** - Hexo、Jekyll、Hugo、VuePress、VitePress、GitBook 等
+- ✅ **建站工具** - 凡科建站、建站之星、建站宝盒、上线了、微企点等
+- ✅ **电商平台** - 有赞、微盟、Shopify（自定义页面）、Magento 等
+- ✅ **博客平台** - 新浪博客、网易博客、CSDN、博客园等（支持 HTML 编辑）
+- ✅ **普通 HTML 网站** - 任何支持 HTML 和 JavaScript 的网站
 
-#### 基本用法
+**核心特点：** 纯 HTML + JavaScript，不依赖任何框架，适用于所有支持 HTML 的建站平台。
 
-在需要展示广告的位置插入以下代码：
+#### 基本用法（一键复制粘贴）
+
+**步骤 1：** 复制以下代码
 
 ```html
 <ins class="qb-adsbyqubian"
@@ -185,11 +291,21 @@ new AdSDK({
      data-app-id="your-app-id"
      data-placement-id="your-placement-id">
 </ins>
-<!-- 使用 jsdelivr CDN（国内访问更快更稳定） -->
-<script src="https://cdn.jsdelivr.net/npm/qb-pc-sdk@latest/qb-pc-sdk.js" async></script>
+<script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js" async></script>
 <script>(window.qbAds = window.qbAds || []).push({});</script>
 ```
 
+**步骤 2：** 替换参数
+- 将 `your-app-id` 替换为您的应用 ID
+- 将 `your-placement-id` 替换为您的广告位 ID
+- 根据需要调整 `width` 和 `height`（广告位尺寸）
+
+**步骤 3：** 粘贴到您的网站
+- 在需要显示广告的位置粘贴代码
+- 保存并刷新页面即可看到广告
+
+**💡 提示：** 如果页面有多个广告位，脚本只需引入一次，放在页面底部即可。
+
 #### 多个广告位
 
 支持在同一个页面中插入多个广告位，每个广告位使用独立的 `<ins>` 标签：
@@ -217,8 +333,7 @@ new AdSDK({
 </ins>
 
 <!-- 脚本只需引入一次，放在页面底部即可 -->
-<!-- 使用 jsdelivr CDN（国内访问更快更稳定） -->
-<script src="https://cdn.jsdelivr.net/npm/qb-pc-sdk@latest/qb-pc-sdk.js" async></script>
+<script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js" async></script>
 <script>(window.qbAds = window.qbAds || []).push({});</script>
 ```
 
@@ -266,6 +381,221 @@ new AdSDK({
 - ✅ **多广告位**：支持在同一个页面中插入多个广告位
 - ✅ **事件回调**：支持监听广告加载、点击、曝光等事件
 
+#### Discuz! 论坛接入详细步骤
+
+**Discuz! X3.5 及所有版本都支持接入，推荐使用最简单的方法二（广告位功能）。**
+
+##### 方法一：使用 Discuz! 广告位功能（最简单，推荐！）
+
+**这是最简单的方法，不需要修改模板文件，适合所有用户：**
+
+1. **登录 Discuz! 后台**
+   - 访问：`http://您的域名/admin.php`
+   - 输入管理员账号密码登录
+
+2. **进入广告管理**
+   - 点击左侧菜单：**运营** → **广告**
+   - 或者直接访问：`http://您的域名/admin.php?action=adv&operation=ad&adtype=`
+
+3. **添加新广告**
+   - 点击 **添加广告** 按钮
+   - 选择广告位类型（如：**页头通栏广告**、**页尾通栏广告** 等）
+   - 填写广告名称（随便填，如：趣变广告）
+
+4. **填写广告代码（包含脚本，一次搞定）**
+   - 在 **广告 HTML 代码** 框中，粘贴以下**完整代码**（包含脚本，不需要单独找模板文件）：
+
+```html
+<ins class="qb-adsbyqubian"
+     style="display:block; width:728px; height:90px; margin:10px auto;"
+     data-app-id="your-app-id"
+     data-placement-id="your-placement-id">
+</ins>
+<script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js" async></script>
+<script>(window.qbAds = window.qbAds || []).push({});</script>
+```
+
+   - 将 `your-app-id` 和 `your-placement-id` 替换为您的实际 ID
+   - **重要：** 把脚本代码也一起粘贴进去，这样就不需要找模板文件了！
+
+5. **保存广告**
+   - 点击 **提交** 保存广告
+   - 返回后台首页，点击 **工具** → **更新缓存**
+
+6. **完成！** 刷新前台页面即可看到广告
+
+**💡 提示：** 如果后续要添加更多广告位，只需要：
+- 再添加一个新广告，只粘贴 `<ins>` 标签部分（不需要再粘贴脚本）
+- 脚本已经在第一个广告中加载过了，后续广告会自动识别
+
+**⚠️ 重要：必须同时添加广告位标签和脚本！**
+
+只添加脚本代码是不够的，还必须添加 `<ins class="qb-adsbyqubian">` 标签。完整步骤如下：
+
+1. **在需要显示广告的位置添加广告位标签**（例如：在帖子内容区域、页面顶部等）：
+
+```html
+<ins class="qb-adsbyqubian"
+     style="display:block; width:728px; height:90px; margin:10px auto;"
+     data-app-id="your-app-id"
+     data-placement-id="your-placement-id">
+</ins>
+```
+
+2. **在 footer.htm 中添加脚本**（只需添加一次）：
+
+```html
+<script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js" async></script>
+<script>(window.qbAds = window.qbAds || []).push({});</script>
+```
+
+**如果广告没有显示，请检查：**
+- 是否添加了 `<ins class="qb-adsbyqubian">` 标签（必须添加）
+- `data-app-id` 和 `data-placement-id` 是否正确填写
+- 浏览器控制台（F12）是否有错误信息
+- Network 标签中是否成功加载了 SDK 文件
+
+##### 方法二：在模板文件中插入（需要修改模板）
+
+**如果方法一找不到模板文件，可以尝试这个方法：**
+
+1. **登录后台** → **界面** → **风格管理**
+
+2. **找到当前使用的风格**
+   - 看到风格列表后，找到当前正在使用的风格（通常显示为"默认"或"当前"）
+   - 点击该风格右侧的 **编辑** 按钮
+
+3. **查找模板文件**
+   - 左侧会显示文件列表，找到以下文件之一：
+     - **footer.htm** - 页面底部（推荐，在文件末尾添加）
+     - **header.htm** - 页面头部（在 `</head>` 之前添加）
+     - **forum/viewthread.htm** - 帖子内容页（在帖子内容区域添加）
+
+4. **如果还是找不到，使用 FTP 工具**
+   - 使用 FTP 工具（如 FileZilla）连接服务器
+   - 进入路径：`/template/当前风格名称/`
+   - 找到 `footer.htm` 或 `header.htm` 文件
+   - 下载到本地，用记事本打开编辑，再上传回去
+
+5. **插入广告代码**
+   - 在合适位置插入广告代码（见方法一的第4步）
+   - 在 `</body>` 标签之前添加脚本（见方法一的第5步）
+   - 保存文件
+
+6. **清除缓存**
+   - 后台 → **工具** → **更新缓存**
+
+##### 方法三：最简单的方法（如果以上都不会）
+
+**如果以上方法都不会操作，可以联系技术人员帮忙，或者使用以下最简单的方法：**
+
+1. **在任意帖子或页面中插入代码**
+   - 发一个新帖子，或者编辑现有帖子
+   - 切换到 **HTML 模式**（如果支持）
+   - 粘贴完整的广告代码（包括脚本）：
+
+```html
+<ins class="qb-adsbyqubian"
+     style="display:block; width:728px; height:90px; margin:10px auto;"
+     data-app-id="your-app-id"
+     data-placement-id="your-placement-id">
+</ins>
+<script src="https://pcsdk.qubiankeji.com:50000/qb-pc-sdk/qb-pc-sdk.js" async></script>
+<script>(window.qbAds = window.qbAds || []).push({});</script>
+```
+
+   - 发布帖子，广告就会显示在该帖子中
+
+**注意：** 这种方法只会在特定帖子中显示广告，不会在整个网站显示。
+
+**推荐做法：** 如果不会操作，建议联系网站技术人员或 Discuz! 开发者帮忙接入。
+
+#### WordPress 接入详细步骤
+
+**WordPress 是最流行的建站平台，接入非常简单：**
+
+##### 方法一：使用 HTML 代码块（推荐，最简单）
+
+1. **登录 WordPress 后台**
+   - 访问：`http://您的域名/wp-admin`
+   - 输入管理员账号密码登录
+
+2. **编辑文章或页面**
+   - 进入 **文章** → **所有文章** 或 **页面** → **所有页面**
+   - 点击要编辑的文章/页面，或创建新文章/页面
+
+3. **添加 HTML 代码块**
+   - 点击 **+** 添加区块
+   - 搜索并选择 **自定义 HTML** 或 **HTML** 区块
+   - 粘贴完整的广告代码（包含 `<ins>` 标签和脚本）
+
+4. **保存并发布**
+   - 点击 **更新** 或 **发布** 按钮
+   - 刷新前台页面即可看到广告
+
+##### 方法二：使用主题编辑器（适合全站显示）
+
+1. **登录后台** → **外观** → **主题编辑器**
+
+2. **选择模板文件**
+   - 选择 `footer.php`（页面底部）或 `header.php`（页面头部）
+   - 在合适位置粘贴广告代码
+
+3. **保存文件**
+   - 点击 **更新文件** 保存
+   - 刷新前台页面查看效果
+
+**💡 提示：** 如果使用子主题，建议在子主题中修改，避免主题更新时丢失代码。
+
+#### 其他建站平台快速接入
+
+##### 凡科建站、建站之星等可视化建站工具
+
+1. **进入网站编辑模式**
+   - 登录建站平台后台
+   - 进入网站编辑/设计模式
+
+2. **添加 HTML 模块**
+   - 在页面中拖入 **HTML 代码** 或 **自定义代码** 模块
+   - 粘贴完整的广告代码
+
+3. **保存并发布**
+   - 保存修改
+   - 发布网站
+   - 刷新页面查看广告
+
+##### Hexo、Jekyll、Hugo 等静态网站生成器
+
+1. **找到模板文件**
+   - Hexo：`themes/您的主题/layout/_partial/footer.ejs` 或类似文件
+   - Jekyll：`_includes/footer.html` 或 `_layouts/default.html`
+   - Hugo：`layouts/partials/footer.html` 或 `layouts/_default/baseof.html`
+
+2. **插入广告代码**
+   - 在合适位置（如 `</body>` 标签之前）粘贴广告代码
+   - 保存文件
+
+3. **重新生成网站**
+   - 运行 `hexo generate`、`jekyll build` 或 `hugo` 等命令
+   - 部署到服务器
+
+##### 有赞、微盟等电商平台
+
+1. **进入页面装修**
+   - 登录商家后台
+   - 进入 **店铺装修** 或 **页面设计**
+
+2. **添加自定义代码模块**
+   - 拖入 **自定义 HTML** 或 **代码模块**
+   - 粘贴广告代码
+
+3. **保存并发布**
+   - 保存装修
+   - 发布页面
+   - 在店铺前台查看效果
+
+**⚠️ 注意：** 部分平台可能限制自定义代码，如无法添加，请联系平台客服或使用其他接入方式。
+
 #### 注意事项
 
 1. **脚本引入**：`<script src="...">` 只需引入一次，建议放在页面底部或 `</body>` 标签之前
@@ -273,6 +603,7 @@ new AdSDK({
 3. **容器尺寸**：建议为每个 `<ins>` 标签设置明确的 `width` 和 `height`
 4. **类名要求**：必须包含 `class="qb-adsbyqubian"`，否则广告不会被识别
 5. **参数必填**：`data-app-id` 和 `data-placement-id` 必须填写正确，否则广告无法加载
+6. **Discuz! 特殊说明**：如果使用模板文件方式，修改后需要清除缓存（后台 → 工具 → 更新缓存）
 
 ## API
 
@@ -305,7 +636,7 @@ const adSDK = new AdSDK({
   container: '#ad-container'
 });
 
-// 在广告加载成功后获取尺寸
+// 在广告加载成功后获取尺寸 
 adSDK.onAdLoaded = (ad) => {
   const size = adSDK.getAdSize();
   console.log('广告尺寸:', size);
@@ -419,10 +750,22 @@ useEffect(() => {
 
 ## 注意事项
 
-1. **系统兼容性**：目前 PC SDK 仅支持 Windows 系统，Mac 系统会报错
-2. **容器尺寸**：建议为广告容器设置明确的宽高（width 和 height）
-3. **CDN 加载**：CDN 方式会自动加载底层 SDK 和封装 SDK，无需手动引入多个文件
-4. **网络环境**：CDN 方式需要网络连接，如果网络不稳定可能导致加载失败
+### 系统兼容性
+
+1. **Windows 系统**：✅ 完全支持，正常加载和显示广告
+2. **Mac 系统**：✅ 自动检测并静默处理，不加载广告，页面正常运行，不会报错
+3. **Linux 系统**：✅ 自动检测并静默处理，不加载广告，页面正常运行，不会报错
+4. **移动端**：✅ 自动检测并静默处理，不加载广告，页面正常运行，不会报错（请使用移动端专用 SDK）
+
+**环境检测机制：** SDK 会自动检测运行环境，仅在 Windows 系统下加载广告，其他环境静默处理，确保页面不会报错。
+
+### 使用注意事项
+
+1. **容器尺寸**：建议为广告容器设置明确的宽高（width 和 height），确保广告正常显示
+2. **CDN 加载**：CDN 方式会自动加载底层 SDK 和封装 SDK，无需手动引入多个文件
+3. **网络环境**：CDN 方式需要网络连接，如果网络不稳定可能导致加载失败
+4. **PC 客户端接入**：如果您的应用是基于 WebView 的 PC 客户端（如 Electron、CEF），需要确保 WebView 运行在 Windows 系统上
+5. **HTTPS 要求**：建议在 HTTPS 环境下使用，部分浏览器可能限制 HTTP 环境下的功能
 
 ## 依赖