Subscription widget

Subscription widget คือพรอมต์และกระดิ่งตัวเปิดที่เชิญชวนผู้เยี่ยมชมเว็บไซต์ให้สมัครรับการแจ้งเตือนแบบพุช กำหนดค่าร่วมกันเป็น subscriptionWidget แต่เปิดใช้งานแยกกันได้: เฉพาะพรอมต์ เฉพาะกระดิ่ง หรือทั้งสองอย่างพร้อมกัน การเปิดใช้งานอย่างใดอย่างหนึ่งจะแทนที่ ปุ่มสมัครสมาชิก Push, Custom Subscription Popup และ Subscription prompt — ตราบใดที่เปิดใช้งานอย่างน้อยหนึ่งส่วน วิดเจ็ตรุ่นเก่าทั้งสามนี้จะไม่ถูกโหลดบนหน้าเพจ

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

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

ตรวจสอบให้แน่ใจว่าคุณได้ติดตั้ง Pushwoosh Web SDK 3.0 บนเว็บไซต์ของคุณแล้ว โดยทำตามคู่มือการผสานการทำงานของเรา

1. เปิดใช้งานพรอมต์และกระดิ่ง

เพิ่มพารามิเตอร์ subscriptionWidget ลงในการเริ่มต้น WebSDK และตั้งค่า prompt.enabled และ/หรือ launcher.enabled เป็น true:

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);

ไม่มีสวิตช์เดียวระดับบนสุด

subscriptionWidget.enable ระดับบนสุดจะไม่ถูกอ่านค่า การตั้งค่าเพียงฟิลด์นี้จะไม่เปิดใช้งานอะไรเลย ดู การย้ายจากวิดเจ็ตรุ่นเก่า ด้านล่าง

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

2. กำหนดค่าพรอมต์และกระดิ่ง

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      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
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    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 — ไม่เปิดตามตัวจับเวลาเลย ให้ตั้งค่านี้ควบคู่กับ launcher.enabled: true เพื่อให้การคลิกกระดิ่งเปิดพรอมต์ได้ API แบบแมนนวลยังคงเปิดพรอมต์ได้เสมอไม่ว่าจะตั้งค่านี้หรือเปิดกระดิ่งไว้หรือไม่
• manual — เปิดเฉพาะผ่าน Pushwoosh.moduleRegistry.subscriptionWidget ซึ่งอธิบายไว้ด้านล่าง

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

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

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

ผลของการคลิกกระดิ่งขึ้นอยู่กับพรอมต์ หาก prompt.enabled เป็น true การคลิกจะสลับพรอมต์: เปิดพรอมต์ หรือปิดหากเปิดอยู่แล้ว หากปิดพรอมต์ไว้ การคลิกจะขอสิทธิ์จากเบราว์เซอร์โดยตรง เช่นเดียวกับ Pushwoosh.subscribe() — ยกเว้นกรณีที่ผู้เยี่ยมชมบล็อกการแจ้งเตือนไว้แล้ว ซึ่งการคลิกจะไม่มีผลใดๆ

launcher.width และ launcher.height กำหนดขนาดของกระดิ่งเป็นพิกเซล (16–200 ค่าเริ่มต้นอย่างละ 48) launcher.imageUrl วาดรูปภาพแทนปุ่มกระดิ่งทรงกลม launcher.background และ launcher.iconColor กำหนดสีพื้นและสีสัญลักษณ์ของปุ่มทรงกลม หากไม่ได้ตั้งค่า launcher.background จะใช้สีเน้นของชุดสีเป็นค่าเริ่มต้น และ launcher.iconColor จะใช้สีสัญลักษณ์ที่คำนวณให้เทียบกับสีพื้นได้ชัดเจน

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

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 ตรวจสอบแต่ละฟิลด์เหล่านี้ รวมถึง launcher.background/launcher.iconColor ในลักษณะนี้ สูงสุด 64 ตัวอักษร init snippet ยอมรับสตริงที่ไม่ว่างเปล่าสำหรับ colors.* โดยไม่ตรวจสอบรูปแบบหรือความยาว ส่วน launcher.background/launcher.iconColor จะไม่ตรวจสอบรูปแบบเช่นกัน แต่ตัดค่าให้เหลือ 64 ตัวอักษรโดยไม่มีการแจ้งเตือน

หมายเหตุ

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

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

สำหรับแอปพลิเคชันที่จัดการผ่านแผงควบคุมเท่านั้น

การ์ด Control Panel มีให้ใช้งานเฉพาะสำหรับแอปพลิเคชันที่มีแพลตฟอร์ม Web อยู่ในโหมด จัดการผ่านแผงควบคุม เท่านั้น (ดู Web Push SDK 3.0) สำหรับแอปพลิเคชันที่กำหนดค่าผ่าน snippet ให้ตั้งค่า subscriptionWidget ใน init snippet ตามที่แสดงด้านบน

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

• Subscription invitation แก้ไขพรอมต์: Invitation (รูปแบบ ตำแหน่ง ไอคอน), When to show (ทริกเกอร์ ความหน่วง การจำกัดความถี่), Texts และ Colors
• Subscription bell แก้ไขตัวเปิด: ตำแหน่ง URL รูปภาพ ความกว้าง/ความสูง สีพื้นและสีไอคอน และข้อความทูลทิปของตัวเอง

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

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

3. ควบคุมพรอมต์จากโค้ดของคุณ

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

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() และ toggle() ไม่มีผลขณะที่ prompt.enabled เป็น false และไม่มีผลสำหรับผู้เยี่ยมชมที่สมัครสมาชิกไปแล้ว การเปิดพรอมต์จะส่งอีเวนต์ show-subscription-widget การปิดจะส่งอีเวนต์ hide-subscription-widget:

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.prompt.enabled และ subscriptionWidget.launcher.enabled ของไซต์ยังไม่ได้ตั้งค่าหรือเป็น false ทั้งคู่ การเปิดใช้งานอย่างใดอย่างหนึ่งจะหยุดการโหลดทั้งสามรายการ ทั้งในแอปพลิเคชันที่กำหนดค่าผ่าน snippet และที่จัดการผ่านแผงควบคุม

ข้อควรระวัง

วิดเจ็ตเวอร์ชันก่อนหน้าใช้สวิตช์ระดับบนสุด subscriptionWidget.enable เพียงตัวเดียวแทน prompt.enabled/launcher.enabled แยกกัน รูปแบบนั้นจะไม่ถูกอ่านค่าอีกต่อไป snippet ที่ยังตั้งเพียง enable: true จะทำให้วิดเจ็ตปิดทั้งหมด: ทั้งพรอมต์และกระดิ่งจะไม่วาดอะไรเลย WebSDK จะบันทึกคำแนะนำในคอนโซลที่ระบุสองฟิลด์ที่ต้องตั้งค่าแทน และวิดเจ็ตรุ่นเก่าทั้งสามจะโหลดราวกับว่าไม่เคยตั้งค่า subscriptionWidget การเปลี่ยนแอปพลิเคชันที่จัดการผ่านแผงควบคุมไปใช้วิดเจ็ตใหม่ก็ไม่นำการตั้งค่าของวิดเจ็ตรุ่นเก่าที่ถูกแทนที่มาด้วยเช่นกัน — แต่ละการ์ดจะเริ่มต้นด้วยค่าเริ่มต้นของตัวเอง