qb-pc-sdk 1.3.2 → 1.3.3

package/README.md

@@ -390,6 +390,33 @@ onBeforeUnmount(() => {
 - **data-ad-id** 或 **data-placement-id**：广告位 ID（必填）
 - 同一页面可放多个 `.lazy-ad`，动态插入的也会被监听并懒加载
 
+**懒加载下使用「关闭按钮」与「插屏」：可直接写在 div 上**
+
+在懒加载的 div 上增加以下**可选** data 属性即可，无需额外 JS：
+
+| 属性 | 取值 | 说明 |
+|------|------|------|
+| `data-close-button-first-click-as-ad` | `true` / `1` / `yes` | 关闭图标：第一次点击 = 广告跳转，第二次点击 = 关闭；悬停显示「关闭按钮」，点击该文字直接关闭 |
+| `data-show-as-interstitial` | `true` / `1` / `yes` | 广告加载成功后自动以插屏形式展示（遮罩 + 居中） |
+
+示例：
+
+```html
+<!-- 仅懒加载，默认关闭逻辑 -->
+<div class="lazy-ad" data-app-id="your-app-id" data-ad-id="your-placement-id"></div>
+
+<!-- 懒加载 + 关闭按钮「首次点击=跳转」 -->
+<div class="lazy-ad" data-app-id="your-app-id" data-ad-id="your-placement-id" data-close-button-first-click-as-ad="true"></div>
+
+<!-- 懒加载 + 以插屏形式展示 -->
+<div class="lazy-ad" data-app-id="your-app-id" data-ad-id="your-placement-id" data-show-as-interstitial="true"></div>
+
+<!-- 两个都开 -->
+<div class="lazy-ad" data-app-id="your-app-id" data-ad-id="your-placement-id" data-close-button-first-click-as-ad="true" data-show-as-interstitial="true"></div>
+```
+
+若需要更细的控制（例如仅部分广告插屏、或自定义关闭逻辑），可在引入 SDK 后使用 `qbAds.push({ onAdLoaded: function(ad, instance, element) { ... } })`，在回调里根据 `element` 判断是哪个广告位，再调用 `instance.showAsInterstitial()` 或 `AdSDK.createCloseButtonClickToAdBehavior(...)`。
+
 ### 方式三：即插即用模式（推荐用于所有建站平台）
 
 专为**所有建站平台**设计的**零代码接入方式**，客户只需复制粘贴即可使用，无需任何技术背景。
@@ -554,6 +581,7 @@ new AdSDK(config);
 - `onAdError` (function, 可选): 广告加载失败回调，参数为错误对象和错误消息
 - `onAdExpose` (function, 可选): 广告曝光回调
 - `onAdClick` (function, 可选): 广告点击回调
+- `closeButtonFirstClickAsAdClick` (boolean, 可选，默认 `false`): 为 `true` 时，关闭按钮采用「第一次点击 = 广告跳转，第二次点击 = 关闭广告」逻辑，用于提高广告点击率；仅需时开启。
 
 ### 实例方法
 
@@ -605,6 +633,70 @@ adSDK.destroy();
 - 广告会自动显示关闭按钮（右上角 ×），点击即可关闭
 - 也可以手动调用 `destroy()` 方法销毁广告
 
+#### 关闭按钮功能（可选）
+
+关闭按钮支持两种用法，可按需选择其一或使用默认行为。
+
+**1. 配置方式：首次点击跳转、二次点击关闭**
+
+在创建实例时传入 `closeButtonFirstClickAsAdClick: true`，则关闭**图标（×）**行为为：第一次点击触发广告跳转（提高点击率），第二次点击才关闭广告。
+
+- 同时，鼠标悬停在关闭图标上会在下方显示「关闭按钮」四个字；**点击「关闭按钮」文字**会直接关闭广告（一次即关）。
+- 仅**点击关闭图标**保持「第一次跳转、第二次关闭」逻辑。
+
+```javascript
+const adSDK = new AdSDK({
+  appId: "your-app-id",
+  placementId: "your-placement-id",
+  container: "#ad-container",
+  closeButtonFirstClickAsAdClick: true, // 开启：关闭图标首次点击=跳转，二次点击=关闭
+  onAdLoaded: (ad, instance) => console.log("广告已加载"),
+});
+```
+
+**2. 静态方法：自定义关闭按钮逻辑**
+
+若需对**任意关闭按钮**自行绑定「首次点击 = 广告跳转，第二次点击 = 关闭」逻辑（例如自定义 UI），可调用静态方法：
+
+```javascript
+// 在 onAdLoaded 中获取关闭按钮与实例后调用
+var closeBtn = instance.container.querySelector(".q-ad-close");
+AdSDK.createCloseButtonClickToAdBehavior(closeBtn, {
+  triggerAdClick: function () {
+    instance.container.querySelector(".q-cta-btn").click(); // 触发广告跳转
+  },
+  close: function () {
+    instance.destroy();
+  },
+});
+```
+
+- `triggerAdClick`: 第一次点击时调用（如对 CTA 按钮执行 `click()`）。
+- `close`: 第二次点击时调用（如 `instance.destroy()`）。
+
+#### showAsInterstitial() 插屏展示
+
+将当前已加载的广告以**全屏插屏**形式展示：半透明遮罩 + 居中广告框，适合活动页、弹窗场景。需在广告加载成功后再调用。
+
+```javascript
+const adSDK = new AdSDK({
+  appId: "your-app-id",
+  placementId: "your-placement-id",
+  container: "#ad-container",
+  onAdLoaded: (ad, instance) => {
+    console.log("广告已加载");
+    instance.showAsInterstitial(); // 以插屏形式展示（遮罩 + 居中）
+  },
+});
+```
+
+**说明**：
+
+- 插屏内广告为**竖版布局**（上图下文），尺寸随容器自适应（约 9:14 比例，最大 90vw×85vh）。
+- **仅能通过广告上的关闭按钮关闭**，点击遮罩不会关闭，避免误触。
+- 插屏无白色边框，广告素材区域贴边展示。
+- 若当前无广告或已在插屏中展示，再次调用不会重复弹层。
+
 ### 广告尺寸自适应
 
 广告会自动适应容器大小。建议在 CSS 中为容器设置明确的宽高：