qb-pc-sdk

pc广告 SDK 封装器 - PC端广告接入工具

✅ 系统兼容性：SDK 会自动检测运行环境，仅在 Windows 系统下加载广告。在 Mac、Linux、移动端等非 Windows 环境下会静默处理，不会报错，页面可正常使用。

适用场景

✅ 支持的场景

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（内容安全策略）限制，需要允许域名

接入示例（Electron）：

// 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);

<!-- 在您的网页中正常使用 SDK（内联版本，容灾100%达成） -->
<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://unpkg.com/qb-pc-sdk@latest/inline-loader.js"></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、移动端）自动跳过，不报错，不影响页面正常使用

安装

⭐ CDN 模式

### NPM 方式（模块化项目推荐）

适用于 Vue、React、Webpack、Vite 等模块化打包项目。**仅需安装 `qb-pc-sdk`，无需单独安装或引入 `qb-pc-ad-sdk-origin`**（底层 SDK 已作为依赖自动集成）。

```bash
npm install qb-pc-sdk

注意： 对于静态 HTML 网站或建站平台，强烈推荐使用 CDN 模式，而不是 NPM 方式。

方式一：NPM 接入（模块化项目）

适用于 Vue、React、Webpack、Vite 等模块化打包项目。只需引入 qb-pc-sdk，无需再 import qb-pc-ad-sdk-origin，底层 SDK 已内置在包内并自动挂载。

1. 基本用法（ES6 模块）

import AdSDK from "qb-pc-sdk";

const adSDK = new AdSDK({
  appId: "your-app-id", // 必填，替换为平台申请的应用 ID
  placementId: "your-placement-id", // 必填，替换为平台申请的广告位 ID
  container: "#ad-container", // 必填，广告挂载的容器：CSS 选择器或 DOM 元素
  onAdLoaded: (ad) => {
    console.log("✅ 广告加载成功", ad);
    const size = adSDK.getAdSize(); // 可获取当前广告尺寸
  },
  onAdError: (error, message) => {
    console.error("❌ 广告加载失败", message);
  },
  onAdExpose: () => console.log("👀 广告已曝光"),
  onAdClick: () => console.log("🖱️ 用户点击了广告"),
});

// 页面卸载或组件销毁时调用，避免内存泄漏
// adSDK.destroy();

⚠️ 重要：容器必须在实例化时已存在于 DOM 中。
若传入的是选择器（如 #ad-container），则创建 new AdSDK(...) 时，该元素必须已经被渲染；否则 SDK 不会发起广告请求，广告不会展示。在 Vue/React 等框架中请务必在容器已挂载后再创建实例（见下方 Vue2/Vue3 示例）。

2. Vue 2 项目接入

在 Vue 2 中，请使用 ref 获取容器 DOM，并在 mounted + $nextTick 之后再创建 AdSDK，确保容器已渲染。

示例：单文件组件

<template>
  <div class="ad-page">
    <!-- 广告容器：必须设置 ref，并保证有宽高 -->
    <div ref="adContainer" class="ad-container"></div>
  </div>
</template>

<script>
import AdSDK from "qb-pc-sdk";

export default {
  name: "AdPage",
  data() {
    return {
      adSDK: null,
    };
  },
  mounted() {
    this.$nextTick(() => {
      // 必须在 nextTick 后执行，确保 ref 已指向真实 DOM
      const container = this.$refs.adContainer;
      if (!container) return;

      this.adSDK = new AdSDK({
        appId: "your-app-id",
        placementId: "your-placement-id",
        container: container, // 推荐传 DOM 元素，避免选择器在 SPA 中拿不到
        onAdLoaded: (ad) => {
          console.log("✅ 广告加载成功", ad);
        },
        onAdError: (error, message) => {
          console.error("❌ 广告加载失败", message);
        },
      });
    });
  },
  beforeDestroy() {
    if (this.adSDK && typeof this.adSDK.destroy === "function") {
      this.adSDK.destroy();
    }
  },
};
</script>

<style scoped>
.ad-container {
  width: 400px;
  height: 220px;
  margin: 0 auto;
}
</style>

3. Vue 3 项目接入（Composition API）

在 Vue 3 中同样需要等容器挂载后再创建实例，使用 ref + onMounted + nextTick。

示例：<script setup>

<template>
  <div class="ad-page">
    <div ref="adContainerRef" class="ad-container"></div>
  </div>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount, nextTick } from "vue";
import AdSDK from "qb-pc-sdk";

const adContainerRef = ref(null);
let adSDK = null;

onMounted(() => {
  nextTick(() => {
    const container = adContainerRef.value;
    if (!container) return;

    adSDK = new AdSDK({
      appId: "your-app-id",
      placementId: "your-placement-id",
      container: container,
      onAdLoaded: (ad) => console.log("✅ 广告加载成功", ad),
      onAdError: (error, message) => console.error("❌ 广告加载失败", message),
    });
  });
});

onBeforeUnmount(() => {
  if (adSDK && typeof adSDK.destroy === "function") {
    adSDK.destroy();
  }
});
</script>

<style scoped>
.ad-container {
  width: 400px;
  height: 220px;
  margin: 0 auto;
}
</style>

Vue 3 Options API 写法与 Vue 2 类似：在 mounted 里用 this.$nextTick，用 this.$refs.xxx 取容器，在 beforeUnmount 里调用 adSDK.destroy()。

4. NPM 接入常见问题：广告不展示

若按上述方式接入后广告仍不展示，可按下面顺序排查：

| 可能原因 | 处理方式 | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 容器在实例化时不存在 | 在 Vue/React 中必须在容器已挂载后再 new AdSDK()，例如在 mounted + $nextTick（Vue2）或 onMounted + nextTick（Vue3）中创建，并优先传 DOM 元素（ref）而不是选择器。 | | 容器无宽高 | 给广告容器设置明确的 width、height（或通过布局保证有尺寸），否则广告可能不渲染。 | | 非 Windows 环境 | 本 SDK 仅在 Windows 系统下加载广告，Mac/Linux/移动端会静默跳过，属正常行为。 | | appId / placementId 错误 | 确认从平台复制的应用 ID、广告位 ID 与配置一致，且无多余空格。 | | 网络或接口异常 | 打开控制台查看是否有 onAdError 报错或网络请求失败；若出现 “SDK Load Timeout”，多为打包环境未正确包含底层依赖，可尝试重新安装：npm install qb-pc-sdk --force。 |

总结： NPM 接入只需 import AdSDK from 'qb-pc-sdk'，无需再引入 qb-pc-ad-sdk-origin；保证在容器已存在于 DOM 且具有宽高时再创建 AdSDK 实例，即可正常展示广告。

方式二：CDN 接入（静态 HTML 页面）

适用于直接在 HTML 页面中使用 <script> 标签引入的场景，无需打包工具。

完整示例

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>广告示例</title>
    <style>
      #ad-container {
        width: 400px;
        height: 220px;
        margin: 20px auto;
      }
    </style>
  </head>
  <body>
    <div id="ad-container"></div>
    <script src="https://unpkg.com/qb-pc-sdk@latest/inline-loader.js"></script>

    <!-- 使用 SDK -->
    <script>
      // 方式1：等待 SDK 加载完成事件（推荐）
      window.addEventListener("qb-pc-sdk-ready", function () {
        const adSDK = new window.AdSDK({
          appId: "your-app-id", // 替换为您在平台申请的应用ID
          placementId: "your-placement-id", // 替换为您的在平台申请的广告位ID
          container: "#ad-container",
          onAdLoaded: (ad) => {
            console.log("✅ 广告加载成功", ad);
          },
          onAdError: (error, message) => {
            console.error("❌ 广告加载失败", error, message);
          },
          onAdExpose: () => {
            console.log("👀 广告已曝光");
          },
          onAdClick: () => {
            console.log("🖱️ 用户点击了广告");
          },
        });
      });

      // 方式2：在 DOMContentLoaded 后轮询检查（兼容性更好）
      window.addEventListener("DOMContentLoaded", function () {
        const checkSDK = setInterval(function () {
          if (window.AdSDK) {
            clearInterval(checkSDK);

            const adSDK = new window.AdSDK({
              appId: "your-app-id",
              placementId: "your-placement-id",
              container: "#ad-container",
              onAdLoaded: (ad) => console.log("✅ 广告加载成功", ad),
              onAdError: (error, message) =>
                console.error("❌ 广告加载失败", error, message),
            });
          }
        }, 100);

        // 10秒超时
        setTimeout(function () {
          clearInterval(checkSDK);
          if (!window.AdSDK) {
            console.error("❌ SDK 加载超时，请检查网络连接");
          }
        }, 10000);
      });
    </script>
  </body>
</html>

CDN 版本指定

如果需要使用外部文件方式指定特定版本：

<script src="https://unpkg.com/qb-pc-sdk@latest/inline-loader.js"></script>

懒加载（.lazy-ad，推荐用于长页）

引用 SDK 后，可使用 懒加载：广告位仅在**即将进入视口（约 200px 内）**时再请求，避免「返回高、曝光低」。

用法： 在页面中放入带 class="lazy-ad" 的 div，并设置 data-app-id、data-ad-id（或 data-placement-id），无需再写任何 JS。

<!-- 引用 SDK -->
<script src="https://unpkg.com/qb-pc-sdk@latest/inline-loader.js"></script>

<!-- 广告位：进入视口约 200px 内时自动加载，每个位只请求一次 -->
<div class="lazy-ad" data-app-id="your-app-id" data-ad-id="your-placement-id"></div>

• data-app-id：应用 ID（必填）
• data-ad-id 或 data-placement-id：广告位 ID（必填）
• 同一页面可放多个 .lazy-ad，动态插入的也会被监听并懒加载

方式三：即插即用模式（推荐用于所有建站平台）

专为所有建站平台设计的零代码接入方式，客户只需复制粘贴即可使用，无需任何技术背景。

支持的建站平台：

• ✅ 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 的网站

多个广告位

支持在同一个页面中插入多个广告位，每个广告位使用独立的 <ins> 标签：

<!-- 广告位 1：横幅广告 (728x90) -->
<ins
  class="qb-adsbyqubian"
  style="display:block; width:728px; height:90px;"
  data-app-id="your-app-id"
  data-placement-id="your-placement-id-1"
>
</ins>

<!-- 广告位 2：中等尺寸 (400x220) -->
<ins
  class="qb-adsbyqubian"
  style="display:block; width:400px; height:220px;"
  data-app-id="your-app-id"
  data-placement-id="your-placement-id-2"
>
</ins>

<!-- 广告位 3：窄条横幅 (780x60) -->
<ins
  class="qb-adsbyqubian"
  style="display:block; width:780px; height:60px;"
  data-app-id="your-app-id"
  data-placement-id="your-placement-id-3"
>
</ins>
- 发布帖子，广告就会显示在该帖子中

**注意：** 这种方法只会在特定帖子中显示广告，不会在整个网站显示。

**推荐做法：** 如果不会操作，建议联系网站技术人员或 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>` 标签之前
2. **初始化调用**：`(window.qbAds = window.qbAds || []).push({})` 只需调用一次，建议放在最后一个广告位之后
3. **容器尺寸**：建议为每个 `<ins>` 标签设置明确的 `width` 和 `height`
4. **类名要求**：必须包含 `class="qb-adsbyqubian"`，否则广告不会被识别
5. **参数必填**：`data-app-id` 和 `data-placement-id` 必须填写正确，否则广告无法加载
6. **Discuz! 特殊说明**：如果使用模板文件方式，修改后需要清除缓存（后台 → 工具 → 更新缓存）

## API

### 构造函数

```javascript
new AdSDK(config);

参数

• appId (string, 必需): 应用 ID，在平台申请的应用ID
• placementId (string, 必需): 广告位 ID，在平台申请的广告位ID
• container (string | HTMLElement, 必需): 广告容器选择器或 DOM 元素
• onAdLoaded (function, 可选): 广告加载成功回调，参数为广告实例和 AdSDK 实例
• onAdError (function, 可选): 广告加载失败回调，参数为错误对象和错误消息
• onAdExpose (function, 可选): 广告曝光回调
• onAdClick (function, 可选): 广告点击回调

实例方法

getAdSize()

获取广告尺寸信息。

const adSDK = new AdSDK({
  appId: "your-app-id",
  placementId: "your-placement-id",
  container: "#ad-container",
});

// 在广告加载成功后获取尺寸
adSDK.onAdLoaded = (ad) => {
  const size = adSDK.getAdSize();
  console.log("广告尺寸:", size);
  // 输出: { imageWidth: 640, imageHeight: 360, hasVideo: false, videoUrl: undefined }
};

返回值：

• imageWidth (number): 广告图片宽度（像素）
• imageHeight (number): 广告图片高度（像素）
• hasVideo (boolean): 是否有视频
• videoUrl (string | undefined): 视频URL（如果有）

destroy()

销毁广告实例，清理 DOM、解绑事件、释放资源。

const adSDK = new AdSDK({
  appId: "your-app-id",
  placementId: "your-placement-id",
  container: "#ad-container",
});

// 销毁广告
adSDK.destroy();

说明：

• 调用后会清空广告容器内容
• 会调用底层 SDK 的 destroy() 方法释放资源
• 广告会自动显示关闭按钮（右上角 ×），点击即可关闭
• 也可以手动调用 destroy() 方法销毁广告

广告尺寸自适应

广告会自动适应容器大小。建议在 CSS 中为容器设置明确的宽高：

#ad-container {
  width: 400px;
  height: 220px;
}

自适应规则：

• 广告会完全填充容器，不会超出
• 图片使用 object-fit: contain 模式，完整显示不裁剪
• 小尺寸容器（宽度<300px 或高度<200px）会自动应用优化样式
• 文字和按钮会根据容器大小自动调整

使用示例

NPM 方式示例

import AdSDK from "qb-pc-sdk";

const adSDK = new AdSDK({
  appId: "your-app-id",
  placementId: "your-placement-id",
  container: "#ad-container",
  onAdLoaded: (ad) => {
    console.log("✅ 广告加载成功");
    // 获取广告尺寸
    const size = adSDK.getAdSize();
    console.log("广告尺寸:", size);
  },
  onAdError: (error, message) => {
    console.error("❌ 广告加载失败:", message);
  },
  onAdExpose: () => {
    console.log("👀 广告已曝光");
  },
  onAdClick: () => {
    console.log("🖱️ 用户点击了广告");
  },
});

// 销毁广告示例
// 方式1：点击广告右上角的关闭按钮（自动销毁）
// 方式2：手动调用 destroy 方法
document.getElementById("close-ad-btn").addEventListener("click", () => {
  adSDK.destroy();
});

// 方式3：在组件销毁时调用（Vue/React）
// Vue
onBeforeUnmount(() => {
  if (adSDK) {
    adSDK.destroy();
  }
});

// React
useEffect(() => {
  return () => {
    if (adSDK) {
      adSDK.destroy();
    }
  };
}, []);

CDN 方式示例

参考项目中的 src/example-simple.html 文件，查看完整的使用示例。

注意事项

系统兼容性

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 环境下的功能

依赖

• qb-pc-ad-sdk-origin: 底层广告 SDK，作为 qb-pc-sdk 的 npm 依赖自动安装；接入时只需使用 qb-pc-sdk，无需单独安装或 import 该包。

License

MIT