# 自定义订阅弹窗

**自定义订阅弹窗**是一个显示在网页上的弹出窗口，建议用户订阅 Web 推送通知。它通过 [Pushwoosh WebSDK](/zh/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration) 实现，并允许克服浏览器对显示原生订阅提示的限制。原生订阅弹窗只能向特定用户显示两次。如果用户不允许推送通知并连续两次关闭原生订阅弹窗，它将不会再次显示，并且推送通知被视为已阻止。而**自定义订阅弹窗**则可以根据需要多次显示，除非用户明确订阅或阻止推送通知。

**自定义订阅弹窗**可以包含任何解释订阅推送通知优势的文本，以及两个可自定义的按钮——一个用于“稍后询问”选项，另一个用于“订阅”。

一旦用户按下“订阅”按钮，就会出现一个原生订阅弹窗。

当用户按下“稍后询问”按钮或直接关闭窗口时，自定义订阅弹窗将在指定时间后再次出现（默认为一周后；重试延迟可通过 `retryOffset` 参数自定义）。

## 实现

要启用和自定义**自定义订阅弹窗**，请在初始化 [Pushwoosh WebSDK](/zh/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration) 时使用以下脚本：

```javascript title="示例"
Pushwoosh.push('init', {
    // . . .,
    subscribePopup: {
        enable: true,                      // (布尔值) 弹窗激活
        text: '弹窗上的文本',             // (字符串) 弹窗上显示的文本
        confirmSubscriptionButtonText: '订阅', // (字符串) “订阅”按钮的自定义文本

        manualToggle: false,               // (布尔值) 手动控制弹窗显示
        delay: 60,                         // (整数) 页面加载与弹窗出现之间的延迟
        retryOffset: 604800,               // (整数) 再次显示弹窗的偏移量（秒）

        iconUrl: 'https://...',            // (字符串) 自定义图标 URL
        iconAlt: '您的图标的描述性文本', // (字符串) 图标的 ALT 文本
        overlay: false,                    // (布尔值) 弹窗显示时启用页面覆盖
        position: 'top',                   // (字符串) 页面上的位置。可能的值：’top' | 'center' | 'bottom’
        mobileViewMargin: '10px',          // (字符串) 移动视图的外边距

        bgColor: '#fff',                   // (字符串) 弹窗的背景颜色
        borderColor: 'transparent',        // (字符串) 弹窗的边框颜色
        boxShadow: '0 3px 6px rgba(0,0,0,0.16)', // (字符串) 弹窗的阴影

        textColor: '#000',                 // (字符串) 弹窗的文本颜色
        textSize: 'inherit',               // (字符串) 弹窗的文本大小
        textWeight: 'normal',              // (字符串) 弹窗的文本粗细
        fontFamily: 'inherit',             // (字符串) 弹窗的文本字体

        subscribeBtnBgColor: '#4285f4',         // (字符串) “订阅”按钮的背景颜色
        subscribeBtnTextColor: '#fff',          // (字符串) “订阅”按钮文本的颜色
        subscribeBtnTextWeight: 'bold',         // (字符串) “订阅”按钮文本的粗细
        subscribeBtnBorderColor: 'transparent', // (字符串) “订阅”按钮的边框颜色
        subscribeBtnBorderRadius: '4px',        // (字符串) “订阅”按钮的边框圆角

        askLaterButtonText: '不是现在',          // (字符串) “稍后询问”按钮的自定义文本
        askLaterBtnBgColor: 'transparent',      // (字符串) “稍后询问”按钮的背景颜色
        askLaterBtnTextColor: '#000',           // (字符串) “稍后询问”按钮文本的颜色
        askLaterBtnBorderColor: 'transparent',  // (字符串) “稍后询问”按钮的边框颜色
        askLaterBtnBorderRadius: '4px',         // (字符串) “稍后询问”按钮的边框圆角
        askLaterBtnTextWeight: 'normal',        // (字符串) “稍后询问”按钮文本的粗细

        theme: 'material',               // (字符串) 弹窗主题，可能的值：'material' | 'topbar'
        viewport: 'desktop'              // (字符串) 目标视口，可能的值：'desktop' | 'mobile'
    }
});
```


### 访问自定义订阅弹窗实例

**自定义订阅弹窗**实例可通过 `Pushwoosh.moduleRegistry.subscribePopup` 访问。

**注意：**此实例仅在 `subscribe-popup-ready` 事件触发后才可访问。但是，**如果用户已经订阅了推送通知，则该实例将不可用。**

该实例提供了一个 `toggle()` 方法，允许您手动显示或隐藏弹窗：

```javascript
// 手动显示或隐藏自定义订阅弹窗
Pushwoosh.moduleRegistry.subscribePopup.toggle(); // 切换可见性
Pushwoosh.moduleRegistry.subscribePopup.toggle(true); // 显示弹窗
Pushwoosh.moduleRegistry.subscribePopup.toggle(false); // 隐藏弹窗
```

这使您可以直接从代码中更好地控制弹窗的行为。

## 主题

默认情况下，订阅弹窗使用 **'material' 主题**，显示时会覆盖屏幕的一部分，从而对网站访问者隐藏部分内容。

<img src="/web-push-notifications-custom-subscription-popup-1.webp" alt="'Material' 主题"/>

为避免订阅弹窗隐藏有价值的内容，请使用 **'topbar' 主题**，这样弹窗会以窄条形式显示在屏幕顶部。

<img src="/web-push-notifications-custom-subscription-popup-2.webp" alt="'Topbar' 主题"/>

## 自定义订阅弹窗事件

以下事件可用于跟踪与**自定义订阅弹窗**的交互：

```javascript
// 当自定义订阅弹窗加载完成并准备好显示时执行
// 注意：如果用户已经订阅了推送通知，此事件将不会触发。
Pushwoosh.addEventHandler('subscribe-popup-ready', function() {
  console.log("触发的事件：subscribe-popup-ready");
});

// 当自定义订阅弹窗显示时执行
Pushwoosh.addEventHandler('subscribe-popup-show', function() {
  console.log("触发的事件：subscribe-popup-show");
});

// 当用户点击弹窗中的“订阅”按钮时执行
Pushwoosh.addEventHandler('subscribe-popup-accept', function() {
  console.log("触发的事件：subscribe-popup-accept");
});

// 当用户点击弹窗中的“稍后询问”按钮时执行
Pushwoosh.addEventHandler('subscribe-popup-decline', function() {
  console.log("触发的事件：subscribe-popup-decline");
});

// 当弹窗隐藏时执行
Pushwoosh.addEventHandler('subscribe-popup-hide', function() {
  console.log("触发的事件：subscribe-popup-hide");
});
```