pc广告 SDK 封装器 - 更新说明
npm install qb-pc-sdkpc广告 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（内容安全策略）限制，需要允许 file.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`
style="display:block; width:400px; height:220px;"
data-app-id="your-app-id"
data-placement-id="your-placement-id">
#### 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 内联代码模式对接，这是最简单、最可靠、容灾效果最好的接入方式。
#### ⭐ 内联版本（最推荐，容灾100%达成）
为什么推荐内联模式？
- ✅ 容灾100%达成：即使主 CDN 域名挂了，内联代码依然会运行并自动切换到备用 CDN
- ✅ 2秒超时保护：如果主 CDN 2秒内没有响应，自动切换到备用 CDN，避免长时间等待
- ✅ 极简内联代码：内联代码只负责容灾和异步加载，代码极小（约 0.4KB），几乎不阻塞页面
- ✅ 无需维护外部文件：逻辑直接内联在 HTML 中，不依赖外部文件，部署简单
- ✅ 自动版本更新：使用 @latest 自动获取最新版本，无需手动更新代码loader.min.js
- ✅ 环境检测自动更新：Windows/Mac 环境检测逻辑在 中，未来支持 Mac 时客户无需修改内联代码async
- ✅ 一次接入，永久有效：客户只需复制粘贴一次内联代码，后续所有功能更新（包括环境检测逻辑）自动生效
- ✅ 完全异步加载：使用 属性，不阻塞页面渲染
推荐所有客户使用此方式对接！
使用方法：
`html`
架构说明：
- 内联代码（客户复制粘贴）：
- 只负责容灾判断（2秒超时）和异步加载 loader.min.js
- 代码极小（约 0.4KB），执行时间 < 1ms，几乎不阻塞页面
- 客户只需复制粘贴一次，永久有效
- loader.min.js（从CDN自动加载，约 2.3KB）：
- 包含 Windows/Mac 环境检测逻辑
- 包含加载 的完整逻辑和2秒超时机制https://unpkg.com/qb-pc-sdk@latest/loader.min.js
- 主 CDN：
- 备用 CDN：
- 自动热更新：使用 自动获取最新版本，包含最新的环境检测逻辑https://unpkg.com/qb-pc-sdk@latest/core.min.js
- core.min.js（从CDN自动加载，约 300KB）：
- SDK核心功能
- 主 CDN：
- 备用 CDN：
- 自动热更新：使用 自动获取最新版本
核心优势：
- ✅ 一次接入，永久有效：客户只需复制粘贴一次内联代码，后续所有功能更新（包括环境检测逻辑、SDK功能）自动生效
- ✅ 未来扩展无需修改：如果未来支持 Mac 端展示广告，只需更新 loader.min.js，客户无需修改任何内联代码
- ✅ 完全异步加载：不阻塞页面渲染，不影响首屏加载速度
- ✅ 推荐用于所有生产环境
适用于 Vue、React、Webpack、Vite 等模块化打包项目。仅需安装 qb-pc-sdk，无需单独安装或引入 qb-pc-ad-sdk-origin（底层 SDK 已作为依赖自动集成）。
`bash`
npm install qb-pc-sdk
注意： 对于静态 HTML 网站或建站平台，强烈推荐使用 CDN 内联代码模式，而不是 NPM 方式。
内联引导器已完全支持异步加载：
1. 内联代码本身：代码极小（约 0.5KB），执行时间 < 1ms，几乎不阻塞页面
2. loader.min.js 加载：使用 async = true 异步加载，不阻塞页面渲染
3. core.min.js 加载：由 loader.min.js 异步加载，不阻塞页面渲染
4. 2秒超时保护：如果主 CDN 2秒内没有响应，自动切换到备用 CDN，避免长时间等待
推荐放置位置：
- ✅ 最佳：放在
标签之前，页面内容先渲染
- ✅ 也可以：放在 中，由于代码极小且异步，影响很小示例（推荐放在页面底部）：
`html
页面标题