qb-pc-sdk 1.2.7 → 1.2.9

package/README.md

@@ -158,7 +158,7 @@ SDK 会自动检测运行环境：
 
 ### NPM 方式（模块化项目推荐）
 
-适用于 Vue、React、Webpack、Vite 等模块化打包项目。
+适用于 Vue、React、Webpack、Vite 等模块化打包项目。**仅需安装 `qb-pc-sdk`，无需单独安装或引入 `qb-pc-ad-sdk-origin`**（底层 SDK 已作为依赖自动集成）。
 
 ```bash
 npm install qb-pc-sdk
@@ -203,59 +203,161 @@ npm install qb-pc-sdk
 
 ### 方式一：NPM 接入（模块化项目）
 
-适用于 Vue、React、Webpack、Vite 等模块化打包项目。
+适用于 Vue、React、Webpack、Vite 等模块化打包项目。**只需引入 `qb-pc-sdk`，无需再 `import qb-pc-ad-sdk-origin`**，底层 SDK 已内置在包内并自动挂载。
 
-#### ES6 模块导入
+#### 1. 基本用法（ES6 模块）
 
 ```javascript
 import AdSDK from 'qb-pc-sdk';
 
-// 使用
 const adSDK = new AdSDK({
-  appId: 'your-app-id',        // 替换为您在平台申请的应用ID
-  placementId: 'your-placement-id',  // 替换为您的在平台申请的广告位ID
-  container: '#ad-container',
+  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('❌ 广告加载失败', error, message);
-  },
-  onAdExpose: () => {
-    console.log('👀 广告已曝光');
+    console.error('❌ 广告加载失败', message);
   },
-  onAdClick: () => {
-    console.log('🖱️ 用户点击了广告');
-  }
+  onAdExpose: () => console.log('👀 广告已曝光'),
+  onAdClick: () => console.log('🖱️ 用户点击了广告'),
 });
+
+// 页面卸载或组件销毁时调用，避免内存泄漏
+// adSDK.destroy();
 ```
 
-#### Vue2 / Vue3 / React 等模块化环境
+**⚠️ 重要：容器必须在实例化时已存在于 DOM 中。**  
+若传入的是选择器（如 `#ad-container`），则创建 `new AdSDK(...)` 时，该元素必须已经被渲染；否则 SDK 不会发起广告请求，广告不会展示。在 Vue/React 等框架中请务必在**容器已挂载后再创建实例**（见下方 Vue2/Vue3 示例）。
 
-在某些模块化打包环境中（如 Vue2），如果自动加载失败，需要手动引入底层 SDK 并挂载到 `window`：
+#### 2. Vue 2 项目接入
 
-```javascript
-// main.js 或入口文件
-import '';
+在 Vue 2 中，请使用 **ref** 获取容器 DOM，并在 **mounted + $nextTick** 之后再创建 AdSDK，确保容器已渲染。
+
+**示例：单文件组件**
+
+```vue
+<template>
+  <div class="ad-page">
+    <!-- 广告容器：必须设置 ref，并保证有宽高 -->
+    <div ref="adContainer" class="ad-container"></div>
+  </div>
+</template>
+
+<script>
 import AdSDK from 'qb-pc-sdk';
-import OriginSDK from 'qb-pc-ad-sdk-origin';
 
-// 确保 GDTAdSDK 挂载到 window（模块化环境可能需要手动挂载）
-if (typeof window !== 'undefined' && !window.GDTAdSDK) {
-    window.GDTAdSDK = OriginSDK.default || OriginSDK.GDTAdSDK || OriginSDK;
+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**。
 
-// 之后在组件中使用
-new AdSDK({
-    appId: 'your-app-id',
-    placementId: 'your-placement-id',
-    container: '#ad-container',
-    onAdLoaded: (ad) => console.log('✅ 广告加载成功', ad),
-    onAdError: (error, message) => console.error('❌ 广告加载失败', error, message)
+**示例：`<script setup>`**
+
+```vue
+<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>
 ```
 
-> **提示**：如果遇到 "SDK Load Timeout" 错误，通常是 `window.GDTAdSDK` 未正确挂载，请按照上述方式手动挂载。
+**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 页面）
 
@@ -862,7 +964,7 @@ useEffect(() => {
 
 ## 依赖
 
-- `qb-pc-ad-sdk-origin`: 底层广告 SDK（已自动在浏览器环境加载）
+- `qb-pc-ad-sdk-origin`: 底层广告 SDK，作为 `qb-pc-sdk` 的 npm 依赖自动安装；**接入时只需使用 `qb-pc-sdk`，无需单独安装或 import 该包**。
 
 ## License