คู่มือการผสานรวม Web SDK สำหรับ Chrome Extension (เวอร์ชัน V3)

หมายเหตุ: เอกสารนี้เป็นคู่มือมาตรฐานสำหรับการผสานรวม MTpush Web SDK ในสภาพแวดล้อม Chrome extension (Manifest V3) และใช้ได้เฉพาะกับเวอร์ชันเบราว์เซอร์ที่รองรับสถาปัตยกรรมส่วนขยาย V3 เท่านั้น

1. ข้อมูลเบื้องต้นเกี่ยวกับผลิตภัณฑ์

MTpush Web SDK - เวอร์ชัน Chrome Extension เป็นเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ส่วนขยาย Chrome (Manifest V3) ที่ใช้ความสามารถการแจ้งเตือนของเบราว์เซอร์ Chrome และกลไกการเชื่อมต่อแบบถาวรของ Service Worker เพื่อให้บริการ Push ที่มีเสถียรภาพและมีประสิทธิภาพสำหรับส่วนขยาย

SDK นี้รองรับเฉพาะ เบราว์เซอร์ Chrome และเบราว์เซอร์ที่ใช้ Chromium (เช่น Edge Chromium) และต้องทำงานในสภาพแวดล้อมส่วนขยายของเบราว์เซอร์ ไม่จำเป็นต้องขออนุญาตจากผู้ใช้เพิ่มเติม ส่วนขยายสามารถรับการแจ้งเตือน Push ได้ทันทีหลังจากการเริ่มต้น

📦 คุณสมบัติหลัก

• การแจ้งเตือนระดับระบบ: แสดงข้อความ Push โดยตรงผ่านศูนย์การแจ้งเตือนของเบราว์เซอร์
• การผสานรวมระดับส่วนขยาย: ออกแบบมาเพื่อทำงานกับสถาปัตยกรรมส่วนขยาย Chrome โดยมีการสมัครรับข้อมูลอัตโนมัติและไม่ต้องรับรู้จากผู้ใช้
• การเข้าถึงแบบเบา: API ที่เป็นเอกภาพสำหรับการเริ่มต้นและการรับข้อความที่รวดเร็ว
• รองรับข้อความที่กำหนดเอง: การกำหนดเป้าหมายผู้ใช้อย่างยืดหยุ่นผ่านแท็ก, นามแฝง เป็นต้น

📌 สถานการณ์การใช้งาน

• การส่งการแจ้งเตือน การตลาด การอัปเดต และการแจ้งเตือนอื่นๆ ให้กับผู้ใช้ส่วนขยาย
• การส่งข้อมูลที่ผู้ใช้สนใจในเวลาจริง เช่น สถานะการจัดส่งสินค้า ข้อความกิจกรรม
• การสร้างส่วนขยายเครื่องมือเบราว์เซอร์ที่มีความสามารถในการส่งข้อความ

2. เนื้อหาของไฟล์บีบอัด SDK

              
              webPushSdk.min.x.x.x-release.zip
├── chrome-extension
│   ├── webSdkExtension.min.x.x.x.js     // ไฟล์ SDK หลัก
│   ├── swExtension.min.x.x.x.js         // ไฟล์ Service Worker
│   └── push-demo                        // โครงการตัวอย่างส่วนขยาย Chrome

            

3. กระบวนการผสานรวม

1. รับข้อมูลแอปพลิเคชัน

สร้างแอปพลิเคชันใหม่ในคอนโซล EngageLab เมื่อสร้างสำเร็จ ระบบจะสร้าง AppKey โดยอัตโนมัติเพื่อระบุแอปพลิเคชัน ดูรายละเอียด: /zh_CN/docs/web-push/console/app-settings

2. ผสานรวม ID ส่วนขยาย

• รับ ID ส่วนขยายของ Chrome extension ของคุณ
• เข้าสู่ระบบคอนโซล WebPush ของ EngageLab ไปที่ [การตั้งค่าผสานรวม] - [การผสานรวม Chrome Extension] และกรอกชื่อส่วนขยายและ ID ส่วนขยาย

แผนภาพ: !https://res.engagelab.net/docs/20250617/101331771/image.png

3. การเข้าถึง SDK

ขั้นตอนที่ 1: ดาวน์โหลด SDK และกำหนดค่าส่วนขยาย

กำหนดค่าต่อไปนี้ใน manifest.json:

              
              {
  "manifest_version": 3,
  "permissions": [
    "storage",
    "notifications",
    "tabs",
    "activeTab"
  ],
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["webSdkExtension.min.x.x.x.js"],
      "run_at": "document_end"
    },
    {
      "matches": ["<all_urls>"],
      "js": ["init-sdk.js"],
      "run_at": "document_end"
    }
  ],
  "background": {
    "service_worker": "swExtension.min.x.x.x.js"
  }
}

            

หลังจากนำเข้า webSdkExtension.min.x.x.x.js แล้ว คุณสามารถเรียกใช้เมธอด SDK ผ่าน window.MTpushInterfaceExtension

ขั้นตอนที่ 2: สร้าง user_str

แนะนำให้ใช้ลายนิ้วมือเบราว์เซอร์เพื่อสร้าง user_str ที่ไม่ซ้ำกันเพื่อป้องกันการลงทะเบียนผู้ใช้ที่ไม่ถูกต้อง:

              
              // ละเว้น: รหัสการเก็บรวบรวมลายนิ้วมือ Canvas, WebGL, ส่วนขยาย (ไม่เปลี่ยนแปลง)
const visitorId = getFingerprint();
console.log('user_str', visitorId);

            

ขั้นตอนที่ 3: เริ่มต้น SDK

              
              if (window.MTpushInterfaceExtension) {
  window.MTpushInterfaceExtension.initSdk({
    appkey: '',      // AppKey ที่สร้างโดยคอนโซล
    user_str: '',    // ลายนิ้วมือเบราว์เซอร์หรือตัวระบุที่ไม่ซ้ำกันของผู้ใช้ที่เข้าสู่ระบบ
  });
}

chrome.runtime.onMessage.addListener((message) => {
  switch (message.type) {
    case 'MTPUSH_INIT_SDK_SUCCESS':
      console.log('การเริ่มต้น SDK สำเร็จ:', message.data);
      break;
    case 'MTPUSH_INIT_SDK_FAIL':
      console.log('การเริ่มต้น SDK ล้มเหลว:', message.data);
      break;
    case 'MTPUSH_ON_MSG_RECEIVE':
      console.log('ได้รับข้อความ Push:', message.data);
      break;
  }
});

            

MTPUSH_ON_MSG_RECEIVE จะถูกเรียกเมื่อได้รับข้อความ Push และใช้ได้เฉพาะกับหน้าต่อไปนี้:

1. หน้าที่เปิดใหม่หลังจากติดตั้งส่วนขยาย (หรือรีสตาร์ทส่วนขยาย)
2. หน้าที่อยู่ในสถานะที่มองเห็นได้ในปัจจุบัน

4. ข้อควรทราบ

1. การเริ่มต้น SDK ต้องดำเนินการบนหน้า "ที่เปิดใหม่หลังจากติดตั้งส่วนขยาย" หน้าเก่าไม่สามารถสร้างการเชื่อมต่อได้
2. หากส่วนขยายถูกปิดใช้งานหรือลบออก จะไม่สามารถรับ Push ใดๆ ได้
3. หลังจากเปิดใช้งานหรือโหลดส่วนขยายใหม่ ต้องเปิดหน้าใดหน้าหนึ่งใหม่เพื่อเริ่มต้นและสมัครรับข้อมูล
4. ในเบราว์เซอร์เดียวกัน แม้จะมี AppKey เดียวกัน แต่ส่วนขยายหรือ user_str ที่ต่างกันจะถูกถือว่าเป็นผู้ใช้ที่ต่างกัน
5. ส่วนขยายไม่จำเป็นต้องขออนุญาตการแจ้งเตือนจากผู้ใช้ จะสมัครรับการแจ้งเตือนระบบโดยอัตโนมัติหลังเริ่มต้นสำเร็จ

5. API เพิ่มเติม

สำหรับการใช้ API ของ SDK เพิ่มเติม โปรดดูเอกสารทางการ: /zh_CN/docs/web-push/sdk/web-sdk-api

6. การเรียกใช้ตัวอย่าง Demo

ไฟล์บีบอัดรวมโครงการตัวอย่างส่วนขยาย Chrome push-demo ซึ่งสามารถใช้สำหรับการทดสอบฟังก์ชัน Push อย่างรวดเร็ว:

1. แทนที่ไดเรกทอรี lib ด้วย SDK ล่าสุด
2. กำหนดค่า appkey และ user_str ที่ถูกต้องใน init-sdk.js
3. เปิด chrome://extensions เปิดใช้งานโหมดนักพัฒนา และนำเข้า demo ที่แตกไฟล์แล้ว
4. เปิดหน้าเว็บใดๆ โดยสุ่มเพื่อดำเนินกระบวนการเริ่มต้นการสมัครรับข้อมูลให้เสร็จสิ้น
5. เข้าสู่ระบบคอนโซล EngageLab และส่งข้อความทดสอบ Push
6. คลิกไอคอน Push ที่มุมขวาล่างของหน้าเว็บเพื่อดู regid, บันทึกการ Push และตั้งค่าแท็ก/นามแฝง
7. หาก Chrome ส่งกลับข้อผิดพลาดเช่น "session timeout" ส่วนขยายจะสมัครรับข้อมูลใหม่โดยอัตโนมัติ