qb-pc-sdk 1.1.2 → 1.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,74 +1,59 @@
1
1
  # qb-pc-sdk
2
2
 
3
- 趣变广告 SDK 封装器 - PC端广告接入工具
4
- 目前PC SDK仅支持Windows系统接入,接入Mac会报错,接入时请注意。
5
- 自动处理多级接口映射与原生渲染逻辑,简化广告接入流程。
6
- 从 1.0.1 起,浏览器环境会自动加载底层依赖 `qb-pc-ad-sdk-origin`,常规打包场景开箱即用。
3
+ 趣变广告 SDK 封装器 - PC端广告接入工具
4
+
5
+ > ⚠️ **重要提示**:目前 PC SDK 仅支持 Windows 系统接入,Mac 系统会报错,接入时请注意。
6
+
7
+ 自动处理多级接口映射与原生渲染逻辑,简化广告接入流程。从 1.0.1 起,浏览器环境会自动加载底层依赖 `qb-pc-ad-sdk-origin`,常规打包场景开箱即用。
7
8
 
8
9
  ## 安装
9
10
 
11
+ ### NPM 方式(推荐)
12
+
10
13
  ```bash
11
14
  npm install qb-pc-sdk
12
15
  ```
13
16
 
17
+ ### CDN 方式
18
+
19
+ 无需安装,直接在 HTML 中引入一个文件即可:
20
+
21
+ ```html
22
+ <script src="https://unpkg.com/qb-pc-sdk@latest/qb-pc-sdk.js"></script>
23
+ ```
24
+
14
25
  ## 使用方法
15
26
 
16
- ### ES6 模块方式(开箱即用)
27
+ ### 方式一:NPM 接入(模块化项目)
17
28
 
18
- #### 方式一:默认导入
29
+ 适用于 Vue、React、Webpack、Vite 等模块化打包项目。
30
+
31
+ #### ES6 模块导入
19
32
 
20
33
  ```javascript
21
34
  import AdSDK from 'qb-pc-sdk';
22
35
 
23
36
  // 使用
24
37
  const adSDK = new AdSDK({
25
- appId: 'your-app-id',
26
- placementId: 'your-placement-id',
27
- container: '#ad-container',
28
- onAdLoaded: (ad) => {
29
- console.log('广告加载成功', ad);
30
- },
31
- onAdError: (error, message) => {
32
- console.error('广告加载失败', error, message);
33
- },
34
- onAdExpose: () => {
35
- console.log('广告已曝光');
36
- },
37
- onAdClick: () => {
38
- console.log('广告被点击');
39
- }
40
- });
41
- ```
42
-
43
- #### 方式二:命名导入
44
-
45
- ```javascript
46
- import { AdSDKWrapper } from 'qb-pc-sdk';
47
-
48
- // 使用(注意这里使用的是 AdSDKWrapper)
49
- const adSDK = new AdSDKWrapper({
50
- appId: 'your-app-id',
51
- placementId: 'your-placement-id',
38
+ appId: 'your-app-id', // 替换为您在平台申请的应用ID
39
+ placementId: 'your-placement-id', // 替换为您的在平台申请的广告位ID
52
40
  container: '#ad-container',
53
41
  onAdLoaded: (ad) => {
54
- console.log('广告加载成功', ad);
42
+ console.log('广告加载成功', ad);
55
43
  },
56
44
  onAdError: (error, message) => {
57
- console.error('广告加载失败', error, message);
45
+ console.error('广告加载失败', error, message);
58
46
  },
59
47
  onAdExpose: () => {
60
- console.log('广告已曝光');
48
+ console.log('👀 广告已曝光');
61
49
  },
62
50
  onAdClick: () => {
63
- console.log('广告被点击');
51
+ console.log('🖱️ 用户点击了广告');
64
52
  }
65
53
  });
66
54
  ```
67
55
 
68
- > **注意**:`AdSDK` / `AdSDKWrapper` 是同一个类。
69
- > 在浏览器打包场景(webpack/Vite 等)无需再单独 `import 'qb-pc-ad-sdk-origin'`,入口已在有 `window` 时自动 `require` 底层 SDK。若在极端沙箱/SSR 场景下未能挂载 `window.GDTAdSDK`,可手动在入口补充 `import 'qb-pc-ad-sdk-origin';` 作为兜底。
70
-
71
- #### Vue2 / Vue3 / React 等模块化环境(推荐方式)
56
+ #### Vue2 / Vue3 / React 等模块化环境
72
57
 
73
58
  在某些模块化打包环境中(如 Vue2),如果自动加载失败,需要手动引入底层 SDK 并挂载到 `window`:
74
59
 
@@ -88,37 +73,101 @@ new AdSDK({
88
73
  appId: 'your-app-id',
89
74
  placementId: 'your-placement-id',
90
75
  container: '#ad-container',
91
- onAdLoaded: (ad) => console.log('广告加载成功', ad),
92
- onAdError: (error, message) => console.error('广告加载失败', error, message)
76
+ onAdLoaded: (ad) => console.log('广告加载成功', ad),
77
+ onAdError: (error, message) => console.error('广告加载失败', error, message)
93
78
  });
94
79
  ```
95
80
 
96
81
  > **提示**:如果遇到 "SDK Load Timeout" 错误,通常是 `window.GDTAdSDK` 未正确挂载,请按照上述方式手动挂载。
97
82
 
98
- ### 浏览器直接引入(不经打包)
83
+ ### 方式二:CDN 接入(静态 HTML 页面)
84
+
85
+ 适用于直接在 HTML 页面中使用 `<script>` 标签引入的场景,无需打包工具。
86
+
87
+ #### 完整示例
99
88
 
100
89
  ```html
101
- <!-- 先引入底层 SDK(本地或 CDN 其一) -->
102
- <script src="/qb-pc-ad-sdk.v1.0.0.js"></script>
103
- <!-- 或 CDN 示例: -->
104
- <!-- <script src="https://unpkg.com/qb-pc-ad-sdk-origin/dist/qb-pc-ad-sdk.v1.0.0.js"></script> -->
105
-
106
- <!-- 再引入封装后的 qb-pc-sdk(UMD,本仓库 src/ad-sdk-wrapper.js) -->
107
- <script src="./src/ad-sdk-wrapper.js"></script>
108
- <script>
109
- // 使用 window.AdSDK
110
- const ad = new window.AdSDK({
111
- appId: 'your-app-id',
112
- placementId: 'your-placement-id',
113
- container: '#ad-container',
114
- onAdLoaded: (ad) => {
115
- console.log('广告加载成功', ad);
116
- },
117
- onAdError: (error, message) => {
118
- console.error('广告加载失败', error, message);
119
- }
120
- });
121
- </script>
90
+ <!DOCTYPE html>
91
+ <html lang="zh-CN">
92
+ <head>
93
+ <meta charset="UTF-8">
94
+ <title>广告示例</title>
95
+ <style>
96
+ #ad-container {
97
+ width: 400px;
98
+ height: 220px;
99
+ margin: 20px auto;
100
+ }
101
+ </style>
102
+ </head>
103
+ <body>
104
+ <div id="ad-container"></div>
105
+
106
+ <!-- 只需引入一个文件,会自动加载底层 SDK 和封装 SDK -->
107
+ <script src="https://unpkg.com/qb-pc-sdk@latest/qb-pc-sdk.js"></script>
108
+
109
+ <!-- 使用 SDK -->
110
+ <script>
111
+ // 方式1:等待 SDK 加载完成事件(推荐)
112
+ window.addEventListener('qb-pc-sdk-ready', function() {
113
+ const adSDK = new window.AdSDK({
114
+ appId: 'your-app-id', // 替换为您在平台申请的应用ID
115
+ placementId: 'your-placement-id', // 替换为您的在平台申请的广告位ID
116
+ container: '#ad-container',
117
+ onAdLoaded: (ad) => {
118
+ console.log('✅ 广告加载成功', ad);
119
+ },
120
+ onAdError: (error, message) => {
121
+ console.error('❌ 广告加载失败', error, message);
122
+ },
123
+ onAdExpose: () => {
124
+ console.log('👀 广告已曝光');
125
+ },
126
+ onAdClick: () => {
127
+ console.log('🖱️ 用户点击了广告');
128
+ }
129
+ });
130
+ });
131
+
132
+ // 方式2:在 DOMContentLoaded 后轮询检查(兼容性更好)
133
+ window.addEventListener('DOMContentLoaded', function() {
134
+ const checkSDK = setInterval(function() {
135
+ if (window.AdSDK) {
136
+ clearInterval(checkSDK);
137
+
138
+ const adSDK = new window.AdSDK({
139
+ appId: 'your-app-id',
140
+ placementId: 'your-placement-id',
141
+ container: '#ad-container',
142
+ onAdLoaded: (ad) => console.log('✅ 广告加载成功', ad),
143
+ onAdError: (error, message) => console.error('❌ 广告加载失败', error, message)
144
+ });
145
+ }
146
+ }, 100);
147
+
148
+ // 10秒超时
149
+ setTimeout(function() {
150
+ clearInterval(checkSDK);
151
+ if (!window.AdSDK) {
152
+ console.error('❌ SDK 加载超时,请检查网络连接');
153
+ }
154
+ }, 10000);
155
+ });
156
+ </script>
157
+ </body>
158
+ </html>
159
+ ```
160
+
161
+ #### CDN 版本指定
162
+
163
+ 如果需要使用特定版本,可以指定版本号:
164
+
165
+ ```html
166
+ <!-- 使用最新版本 -->
167
+ <script src="https://unpkg.com/qb-pc-sdk@latest/qb-pc-sdk.js"></script>
168
+
169
+ <!-- 使用指定版本 -->
170
+ <script src="https://unpkg.com/qb-pc-sdk@1.1.3/qb-pc-sdk.js"></script>
122
171
  ```
123
172
 
124
173
  ## API
@@ -131,11 +180,11 @@ new AdSDK(config)
131
180
 
132
181
  #### 参数
133
182
 
134
- - `appId` (string, 必需): 应用 ID
135
- - `placementId` (string, 必需): 广告位 ID
183
+ - `appId` (string, 必需): 应用 ID,在平台申请的应用ID
184
+ - `placementId` (string, 必需): 广告位 ID,在平台申请的广告位ID
136
185
  - `container` (string | HTMLElement, 必需): 广告容器选择器或 DOM 元素
137
- - `onAdLoaded` (function, 可选): 广告加载成功回调
138
- - `onAdError` (function, 可选): 广告加载失败回调
186
+ - `onAdLoaded` (function, 可选): 广告加载成功回调,参数为广告实例和 AdSDK 实例
187
+ - `onAdError` (function, 可选): 广告加载失败回调,参数为错误对象和错误消息
139
188
  - `onAdExpose` (function, 可选): 广告曝光回调
140
189
  - `onAdClick` (function, 可选): 广告点击回调
141
190
 
@@ -161,6 +210,7 @@ adSDK.onAdLoaded = (ad) => {
161
210
  ```
162
211
 
163
212
  **返回值**:
213
+
164
214
  - `imageWidth` (number): 广告图片宽度(像素)
165
215
  - `imageHeight` (number): 广告图片高度(像素)
166
216
  - `hasVideo` (boolean): 是否有视频
@@ -182,6 +232,7 @@ adSDK.destroy();
182
232
  ```
183
233
 
184
234
  **说明**:
235
+
185
236
  - 调用后会清空广告容器内容
186
237
  - 会调用底层 SDK 的 `destroy()` 方法释放资源
187
238
  - 广告会自动显示关闭按钮(右上角 ×),点击即可关闭
@@ -193,55 +244,48 @@ adSDK.destroy();
193
244
 
194
245
  ```css
195
246
  #ad-container {
196
- width: 200px;
197
- height: 120px;
247
+ width: 400px;
248
+ height: 220px;
198
249
  }
199
250
  ```
200
251
 
201
252
  **自适应规则**:
253
+
202
254
  - 广告会完全填充容器,不会超出
203
255
  - 图片使用 `object-fit: contain` 模式,完整显示不裁剪
204
256
  - 小尺寸容器(宽度<300px 或高度<200px)会自动应用优化样式
205
257
  - 文字和按钮会根据容器大小自动调整
206
258
 
207
- ### 示例
259
+ ## 使用示例
208
260
 
209
- #### 基本使用
261
+ ### NPM 方式示例
210
262
 
211
263
  ```javascript
212
- const AdSDK = require('qb-pc-sdk');
264
+ import AdSDK from 'qb-pc-sdk';
213
265
 
214
266
  const adSDK = new AdSDK({
215
267
  appId: 'your-app-id',
216
268
  placementId: 'your-placement-id',
217
269
  container: '#ad-container',
218
270
  onAdLoaded: (ad) => {
219
- console.log('广告加载成功');
271
+ console.log('广告加载成功');
272
+ // 获取广告尺寸
273
+ const size = adSDK.getAdSize();
274
+ console.log('广告尺寸:', size);
220
275
  },
221
276
  onAdError: (error, message) => {
222
- console.error('广告加载失败:', message);
277
+ console.error('广告加载失败:', message);
223
278
  },
224
279
  onAdExpose: () => {
225
- console.log('广告已曝光');
280
+ console.log('👀 广告已曝光');
226
281
  },
227
282
  onAdClick: () => {
228
- console.log('广告被点击');
283
+ console.log('🖱️ 用户点击了广告');
229
284
  }
230
285
  });
231
- ```
232
-
233
- #### 销毁广告示例
234
-
235
- ```javascript
236
- const adSDK = new AdSDK({
237
- appId: 'your-app-id',
238
- placementId: 'your-placement-id',
239
- container: '#ad-container'
240
- });
241
286
 
287
+ // 销毁广告示例
242
288
  // 方式1:点击广告右上角的关闭按钮(自动销毁)
243
- // 广告渲染时会自动显示关闭按钮
244
-
245
289
  // 方式2:手动调用 destroy 方法
246
290
  document.getElementById('close-ad-btn').addEventListener('click', () => {
247
291
  adSDK.destroy();
@@ -265,6 +309,17 @@ useEffect(() => {
265
309
  }, []);
266
310
  ```
267
311
 
312
+ ### CDN 方式示例
313
+
314
+ 参考项目中的 `src/example-simple.html` 文件,查看完整的使用示例。
315
+
316
+ ## 注意事项
317
+
318
+ 1. **系统兼容性**:目前 PC SDK 仅支持 Windows 系统,Mac 系统会报错
319
+ 2. **容器尺寸**:建议为广告容器设置明确的宽高(width 和 height)
320
+ 3. **CDN 加载**:CDN 方式会自动加载底层 SDK 和封装 SDK,无需手动引入多个文件
321
+ 4. **网络环境**:CDN 方式需要网络连接,如果网络不稳定可能导致加载失败
322
+
268
323
  ## 依赖
269
324
 
270
325
  - `qb-pc-ad-sdk-origin`: 底层广告 SDK(已自动在浏览器环境加载)
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "qb-pc-sdk",
3
- "version": "1.1.2",
4
- "description": "趣变广告 SDK 封装器 - 修复广告自适应问题,添加关闭按钮",
3
+ "version": "1.1.4",
4
+ "description": "趣变广告 SDK 封装器 - 更新静态资源cdn引入",
5
5
  "main": "index.js",
6
6
  "files": [
7
7
  "index.js",
8
+ "qb-pc-sdk.js",
8
9
  "src/",
9
10
  "README.md"
10
11
  ],
package/qb-pc-sdk.js ADDED
@@ -0,0 +1,95 @@
1
+ /**
2
+ * qb-pc-sdk CDN 统一入口文件
3
+ * 自动加载底层 SDK 和封装 SDK,只需引入一个文件即可使用
4
+ *
5
+ * 使用方式:
6
+ * <script src="https://unpkg.com/qb-pc-sdk@latest/qb-pc-sdk.js"></script>
7
+ *
8
+ * 然后直接使用 window.AdSDK
9
+ */
10
+ (function(global) {
11
+ 'use strict';
12
+
13
+ const window = typeof global !== 'undefined' && global.window ? global.window : (typeof window !== 'undefined' ? window : global);
14
+ const document = window.document;
15
+
16
+ if (!document) {
17
+ console.error('[qb-pc-sdk] 需要在浏览器环境中使用');
18
+ return;
19
+ }
20
+
21
+ // 防止重复加载
22
+ if (window._qbPcSdkLoading || window.AdSDK) {
23
+ return;
24
+ }
25
+
26
+ window._qbPcSdkLoading = true;
27
+
28
+ // 获取当前脚本的版本号(从URL中提取)
29
+ const getCurrentVersion = function() {
30
+ const scripts = document.getElementsByTagName('script');
31
+ for (let i = 0; i < scripts.length; i++) {
32
+ const src = scripts[i].src || '';
33
+ const match = src.match(/qb-pc-sdk@([\d.]+)/);
34
+ if (match) {
35
+ return match[1];
36
+ }
37
+ }
38
+ return 'latest'; // 默认使用 latest
39
+ };
40
+
41
+ const version = getCurrentVersion();
42
+ const baseUrl = 'https://unpkg.com';
43
+
44
+ // 动态加载脚本
45
+ const loadScript = function(url, callback) {
46
+ const script = document.createElement('script');
47
+ script.src = url;
48
+ script.async = true;
49
+ script.onload = function() {
50
+ if (callback) callback();
51
+ };
52
+ script.onerror = function() {
53
+ console.error('[qb-pc-sdk] 加载失败:', url);
54
+ window._qbPcSdkLoading = false;
55
+ };
56
+ document.head.appendChild(script);
57
+ };
58
+
59
+ // 第一步:加载底层 SDK
60
+ const originSdkUrl = `${baseUrl}/qb-pc-ad-sdk-origin@latest/dist/qb-pc-ad-sdk.v1.0.0.js`;
61
+
62
+ loadScript(originSdkUrl, function() {
63
+ // 检查底层 SDK 是否加载成功
64
+ if (!window.GDTAdSDK) {
65
+ console.error('[qb-pc-sdk] 底层 SDK 加载失败,请检查网络连接');
66
+ window._qbPcSdkLoading = false;
67
+ return;
68
+ }
69
+
70
+ console.log('[qb-pc-sdk] ✅ 底层 SDK 加载成功');
71
+
72
+ // 第二步:加载封装 SDK
73
+ const wrapperSdkUrl = `${baseUrl}/qb-pc-sdk@${version}/src/ad-sdk-wrapper.js`;
74
+
75
+ loadScript(wrapperSdkUrl, function() {
76
+ // 检查封装 SDK 是否加载成功
77
+ if (!window.AdSDK) {
78
+ console.error('[qb-pc-sdk] 封装 SDK 加载失败,请检查网络连接');
79
+ window._qbPcSdkLoading = false;
80
+ return;
81
+ }
82
+
83
+ console.log('[qb-pc-sdk] ✅ 封装 SDK 加载成功,可以使用 window.AdSDK');
84
+ window._qbPcSdkLoading = false;
85
+
86
+ // 触发加载完成事件
87
+ const event = new CustomEvent('qb-pc-sdk-ready', {
88
+ detail: { AdSDK: window.AdSDK, GDTAdSDK: window.GDTAdSDK }
89
+ });
90
+ window.dispatchEvent(event);
91
+ });
92
+ });
93
+
94
+ })(typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : this);
95
+
@@ -560,7 +560,7 @@
560
560
  // 构建 HTML 结构
561
561
  this.container.innerHTML = `
562
562
  <div class="${wrapperClass}">
563
- <button class="q-ad-close" title="关闭广告">×</button>
563
+ <button class="q-ad-close" title="关闭广告" style="position: absolute; top: 5px; right: 5px; width: 20px; height: 20px; background: rgba(0,0,0,0.5); color: #fff; border: none; border-radius: 50%; cursor: pointer; display: flex; align-items: center; justify-content: center; font-size: 14px; line-height: 1; z-index: 10; transition: background 0.2s; flex-shrink: 0; padding: 0; margin: 0; box-sizing: border-box; font-family: Arial, sans-serif; font-weight: bold;">×</button>
564
564
  <div class="q-media-container">
565
565
  <div class="q-ad-video" style="display:none"></div>
566
566
  <img class="q-ad-img" style="display:none">