# Subscription widget

**Subscription widget** คือกระดิ่งตัวเปิดพร้อมพรอมต์ที่เชิญชวนผู้เยี่ยมชมเว็บไซต์ให้สมัครรับการแจ้งเตือนแบบพุช โดยแทนที่ [ปุ่มสมัครสมาชิก Push](/th/developer/pushwoosh-sdk/web-push-notifications/push-subscription-button/), [Custom Subscription Popup](/th/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/) และวิดเจ็ต [Subscription prompt](/th/developer/guides/messaging-channels/subscription-prompt/) ด้วยคอมโพเนนต์เดียว ตราบใดที่เปิดใช้งานอยู่ ทั้งสามอย่างนี้จะไม่ถูกโหลดบนหน้าเพจ ดังนั้นผู้เยี่ยมชมจะไม่เห็นคำขอที่แข่งขันกันสองรายการ

ผู้เยี่ยมชมที่ยังไม่ได้ตัดสินใจจะเห็นคำขอ ผู้เยี่ยมชมที่บล็อกการแจ้งเตือนไปแล้วจะเห็นคำอธิบายวิธีปลดบล็อกแทน

## ข้อกำหนดเบื้องต้น

ตรวจสอบให้แน่ใจว่าคุณได้ติดตั้ง Pushwoosh Web SDK 3.0 บนเว็บไซต์ของคุณแล้ว โดยทำตาม[คู่มือการผสานการทำงาน](/th/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration)ของเรา

## 1. เปิดใช้งานวิดเจ็ต

เพิ่มพารามิเตอร์ `subscriptionWidget` ลงในการเริ่มต้น WebSDK และตั้งค่า `enable` เป็น `true`:

```javascript
Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    enable: true,
  }
}]);
```

ทุกฟิลด์ด้านล่างเป็นทางเลือก ฟิลด์ที่ละไว้จะใช้ค่าเริ่มต้น ใน init snippet ตัวเลขที่อยู่นอกช่วงจะถูกจำกัดไปที่ขอบเขตที่ใกล้ที่สุดโดยไม่มีการแจ้งเตือน และค่า enum ที่ไม่ถูกต้องจะกลับไปใช้ค่าเริ่มต้นโดยไม่มีการแจ้งเตือนในคอนโซล ฟอร์มใน Control Panel ที่อธิบายไว้ด้านล่างจะปฏิเสธค่าที่ไม่ถูกต้องทันทีและปฏิเสธการบันทึก

## 2. กำหนดค่าพรอมต์

```javascript
Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    enable: true,
    prompt: {
      layout: 'card',       // 'card' | 'bar' | 'modal'
      position: 'bottom-right',
      iconUrl: 'https://url-image.png',
      borderRadius: 12,     // 0–32
      overlay: false,
    },
    launcher: {
      enabled: true,
      position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
      offset: 20,           // 0–100
      size: 48,             // 32–80
    },
    display: {
      trigger: 'auto',      // 'auto' | 'launcher' | 'manual'
      delay: 5,             // seconds, 0–3600
      cappingCount: 3,      // auto-shows per visitor, 0–100, 0 = unlimited
      cappingInterval: 24,  // hours between auto-shows, 0–8760
    },
    texts: {
      title: 'Stay in the loop',
      message: 'Get notified about news and updates.',
      acceptText: 'Allow',
      declineText: 'Not now',
      closeText: 'Close',
      blockedTitle: 'Notifications are blocked',
      blockedMessage: 'Enable notifications in your browser settings to stay updated.',
      launcherLabel: 'Subscribe to notifications',
      launcherBlockedLabel: 'Notifications are blocked',
    },
    colors: {
      background: '#ffffff',
      accent: '#4285f4',
      text: '#000000',
      textSecondary: '#666666',
    },
  }
}]);
```

### รูปแบบและตำแหน่ง

`prompt.layout` กำหนดรูปทรงของพรอมต์:

- **`card`** — การ์ดขนาดกะทัดรัดที่ยึดกับขอบหรือมุม `prompt.position` รองรับ `top`, `bottom`, `top-left`, `top-right`, `bottom-left` หรือ `bottom-right`
- **`bar`** — แถบที่ครอบคลุมความกว้างเต็มหน้าเพจ `prompt.position` รองรับเฉพาะ `top` หรือ `bottom`
- **`modal`** — หน้าต่างที่อยู่ตรงกลางหน้าเพจ `prompt.position` เป็น `center` เสมอ

ตรวจสอบรายการด้านบนสำหรับรูปแบบที่คุณตั้งค่าไว้ก่อนเลือกตำแหน่ง ใน init snippet ตำแหน่งที่รูปแบบปัจจุบันไม่รองรับจะถูกแทนที่ด้วยค่าเริ่มต้นของรูปแบบนั้นโดยไม่มีการแจ้งเตือน ฟอร์มใน Control Panel จะปฏิเสธชุดค่าผสมนั้นแทน

### เมื่อใดควรแสดง

`display.trigger` ควบคุมว่าอะไรเปิดพรอมต์:

- **`auto`** — เปิดโดยอัตโนมัติหลังจากหน้าเพจโหลด `display.delay` วินาที จากนั้นเปิดอีกครั้งทุก `display.cappingInterval` ชั่วโมง หากผู้เยี่ยมชมยังไม่ตัดสินใจ สูงสุด `display.cappingCount` ครั้งโดยรวม (`0` หมายถึงไม่จำกัด)
- **`launcher`** — เปิดเฉพาะเมื่อผู้เยี่ยมชมคลิกที่กระดิ่ง
- **`manual`** — เปิดเฉพาะผ่าน `Pushwoosh.moduleRegistry.subscriptionWidget` ซึ่งอธิบายไว้ด้านล่าง

`display.delay`, `display.cappingCount` และ `display.cappingInterval` ใช้ได้กับทริกเกอร์ `auto` เท่านั้น

### กระดิ่งตัวเปิด

`launcher.enabled` แสดงกระดิ่งลอยตัวตราบใดที่ผู้เยี่ยมชมยังไม่ได้สมัครสมาชิก ไม่ว่า `display.trigger` จะเป็นอะไร — แม้จะใช้ `trigger: 'auto'` กระดิ่งก็ยังคงมองเห็นได้เพื่อให้ผู้เยี่ยมชมเปิดพรอมต์อีกครั้งได้หลังจากปิดไป `launcher.position` วางไว้ที่มุมใดมุมหนึ่งในสี่มุม `launcher.offset` (ระยะห่างจากขอบเป็นพิกเซล) และ `launcher.size` (เส้นผ่านศูนย์กลางของกระดิ่งเป็นพิกเซล) ปรับตำแหน่งอย่างละเอียด

### ข้อความและสี

`texts.blockedTitle`, `texts.blockedMessage` และ `texts.closeText` จะแสดงแทนคำขอทันทีที่เบราว์เซอร์รายงานว่าผู้เยี่ยมชมบล็อกการแจ้งเตือน — `texts.acceptText` และ `texts.declineText` จะไม่ปรากฏในสถานะนั้นเลย `texts.launcherLabel` และ `texts.launcherBlockedLabel` คือทูลทิปของกระดิ่งในแต่ละสถานะ ฟิลด์ข้อความแต่ละรายการรองรับสูงสุด 300 ตัวอักษร

`colors.accent`, `colors.background`, `colors.text` และ `colors.textSecondary` รับค่า hex หรือชื่อสี CSS ฟอร์มใน Control Panel ตรวจสอบแต่ละฟิลด์ในลักษณะนี้ สูงสุด 64 ตัวอักษร init snippet ยอมรับสตริงที่ไม่ว่างเปล่าสำหรับฟิลด์เหล่านี้โดยไม่ตรวจสอบรูปแบบหรือความยาว

<Aside type="note">
ชุดสี dark mode, `zIndex` ของตัวเปิด และ `fontFamily` แบบกำหนดเองมีให้ใช้งานเป็นฟิลด์เพิ่มเติมสำหรับ init parameter เท่านั้น ฟิลด์เหล่านี้ไม่ปรากฏในฟอร์มของ Control Panel ที่อธิบายไว้ด้านล่าง
</Aside>

## การจัดการใน Control Panel

<Aside type="caution" title="สำหรับแอปพลิเคชันที่จัดการผ่านแผงควบคุมเท่านั้น">
การ์ด Control Panel มีให้ใช้งานเฉพาะสำหรับแอปพลิเคชันที่มีแพลตฟอร์ม Web อยู่ในโหมด **จัดการผ่านแผงควบคุม** เท่านั้น (ดู [Web Push SDK 3.0](/th/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/)) สำหรับแอปพลิเคชันที่กำหนดค่าผ่าน snippet ให้ตั้งค่า `subscriptionWidget` ใน init snippet ตามที่แสดงด้านบน
</Aside>

ในแอปพลิเคชันที่จัดการผ่านแผงควบคุม ไปที่ **Settings → Configure platforms → Web** แล้วเปิดการ์ด **Subscription widget** ป้ายกำกับบนการ์ดจะแสดงว่าวิดเจ็ตอยู่ในสถานะ **On** หรือ **Off**

คลิก **Configure** เพื่อแก้ไขฟิลด์เดียวกันกับที่อธิบายไว้ด้านบน ซึ่งจัดกลุ่มเป็น **Prompt**, **When to show**, **Bell**, **Texts** และ **Colors** พร้อมตัวอย่างสดที่แสดงทั้งสถานะผู้เยี่ยมชมที่ยังไม่ตัดสินใจและผู้เยี่ยมชมที่ถูกบล็อก การบันทึกจะแทนที่สำเนาการกำหนดค่าวิดเจ็ตในแผงควบคุม โดยไม่กระทบ init snippet ของ WebSDK บนเว็บไซต์ของคุณ

ตราบใดที่แอปพลิเคชันได้รับการจัดการผ่านแผงควบคุม ค่าที่บันทึกไว้ในการ์ดนี้จะแทนที่คีย์เดียวกันใน init snippet ของเว็บไซต์ การย้ายเว็บไซต์ไปใช้การกำหนดค่าผ่านแผงควบคุมเป็นเพียงสวิตช์ในแผงควบคุม โดยไม่ต้องเปลี่ยนโค้ดบนเว็บไซต์

## 3. ควบคุมวิดเจ็ตจากโค้ดของคุณ

เมื่อโหลดบันเดิลของวิดเจ็ตแล้ว จะเผยแพร่ API ที่ `Pushwoosh.moduleRegistry.subscriptionWidget`:

```javascript
Pushwoosh.moduleRegistry.subscriptionWidget.show();          // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.hide();          // Closes the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.toggle();        // Toggles the current state
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true);    // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.isVisible();     // Returns whether the prompt is open
```

`show()` ไม่มีผลสำหรับผู้เยี่ยมชมที่สมัครสมาชิกไปแล้ว การเปิดพรอมต์จะส่งอีเวนต์ `show-subscription-widget` การปิดจะส่งอีเวนต์ `hide-subscription-widget`:

```javascript
Pushwoosh.addEventHandler('show-subscription-widget', function() {
  console.log('Triggered event: show-subscription-widget');
});

Pushwoosh.addEventHandler('hide-subscription-widget', function() {
  console.log('Triggered event: hide-subscription-widget');
});
```

## การย้ายจากวิดเจ็ตรุ่นเก่า

ปุ่มสมัครสมาชิก Push, Custom Subscription Popup และ Subscription prompt จะยังคงทำงานตามที่อธิบายไว้ในหน้าของตนเอง ตราบใดที่ `subscriptionWidget.enable` ยังไม่ได้ตั้งค่าหรือเป็น `false` การตั้งค่าเป็น `true` จะหยุดการโหลดทั้งสามรายการ ทั้งในแอปพลิเคชันที่กำหนดค่าผ่าน snippet และที่จัดการผ่านแผงควบคุม

<Aside type="caution">
การเปลี่ยนแอปพลิเคชันที่จัดการผ่านแผงควบคุมไปใช้ Subscription widget จะไม่นำการตั้งค่าของวิดเจ็ตรุ่นเก่าที่ถูกแทนที่มาด้วย — วิดเจ็ตจะเริ่มต้นด้วยค่าเริ่มต้นของตัวเอง และคุณต้องกำหนดค่าใหม่ทั้งหมดในการ์ดของมัน
</Aside>