Web SDK API

SDK จะรับ URL การเชื่อมต่อและการรายงานสถิติตามศูนย์ข้อมูลของ AppKey โดยอัตโนมัติ รวมถึงแฟรงก์เฟิร์ตและเวอร์จิเนีย ไม่จำเป็นต้องกำหนด baseUrl, report_url หรือ webSocketUrl เอง

การตรวจสอบสิทธิ์

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

เริ่มต้นโครงสร้างข้อมูล

              
              interface MTInitInfo {
  website_push_id: string;
  code: number;
  master_secret: string;
  passwd: string;
  pull: number;
  regid: string;
  sess: string;
  tagalias: number;
  uid: number;
  vapid_pubkey: string;
}

type dataType = {
  code: number,
  content?: string | { code: number; [key: string]: unknown },
  message: string,
};

interface InitType {
  report_url?: string; // Report URL, used for private cloud or custom deployments
  baseUrl?: string; // Server domain; when used together with report_url, the private cloud or custom deployment logic is used
  userLang?: string; // Defaults to navigator.language and must be a language value supported by the browser
  safari_url?: string; // Safari push test field
  appkey: string; // AppKey of the application registered on the EngageLab platform, required
  user_str: string; // Unique user identifier, required
  swUrl?: string; // Default: "/sw" + sdkEnv.prefix
  is_temporary?: "n" | "t"; // Default: "n"
  debugMode?: boolean; // Default: false
  webSocketUrl?: string; // If not provided, baseUrl will be used
  fail?: (data: dataType | undefined) => void; // Initialization failure callback
  success?: (data: dataType | undefined) => void; // Initialization success callback
  webPushcallback?: def;
  canGetInfo?: (d: MTInitInfo) => void;
  custom?: (Callback: () => void) => void; // Callback for custom prompts; call Callback to request notification permission
  maOpen?: boolean; // Whether to enable the ma-sdk module
  maChannel?: string; // Channel name used by ma-sdk; default: default-channel
  appName?: string; // Website name used by ma-sdk for reporting
  userIdentity?: { userId?: string; anonymousId?: string }; // User identity used by ma-sdk
  maCompletion?: (code: number, msg: string) => void; // ma-sdk initialization completion callback
  openUrl?: string; // Redirect link when clicking a notification
  encodeSwUrl?: boolean; // Whether to encode swUrl
  regidSearchPath?: string; // Page path for querying Registration ID
}

            

• คำอธิบายพารามิเตอร์:
  • openUrl: URL ที่เปิดเมื่อคลิกการแจ้งเตือน
    • หากไม่ได้กำหนด URL เมื่อส่งการแจ้งเตือน จะใช้ค่านี้เป็นลิงก์เปลี่ยนเส้นทาง
    • หากไม่ได้ตั้งค่า จะเปลี่ยนเส้นทางไปยังโดเมนการรวมโดยค่าเริ่มต้น
    • ในกรณีหลายโดเมน ใช้พารามิเตอร์นี้เพื่อเปลี่ยนเส้นทางไปยัง URL ที่ตรงกัน
  • encodeSwUrl: จะเข้ารหัส swUrl หรือไม่
    • ใช้เมื่อ swUrl มีอักขระพิเศษ (เช่น @) และเซิร์ฟเวอร์จำกัดการเข้าถึง URL นั้น อาจทำให้การลงทะเบียน Service Worker ล้มเหลว เพิ่มกลไกลงทะเบียนใหม่ และเข้ารหัส swUrl เมื่อลองใหม่
  • regidSearchPath: Path หน้าสำหรับค้นหา Registration ID ค่าเริ่มต้น /engagelab/regid ดู คู่มือการค้นหา Registration ID

สามารถลงทะเบียน service worker ได้เพียงหนึ่งตัวภายในขอบเขตเดียวกัน หากการเริ่มต้นสำเร็จแต่รายงานข้อผิดพลาดเช่น "Failed to execute 'subscribe' on 'PushManager': Subscription failed - no active Service Worker" โปรดตรวจสอบความขัดแย้งกับ service worker อื่นๆ อาจจำเป็นต้องรวม service worker หรือแก้ไขขอบเขตของ service worker

การเริ่มต้น SDK

คำอธิบายอินเทอร์เฟซ

อินเทอร์เฟซสำหรับเริ่มต้น

              
              window.MTpushInterface.init(Object:InitType)

            

คำอธิบายพารามิเตอร์

• รายละเอียดดูที่ /th_TH/docs/web-push/sdk/web-sdk-api#Initialize data structure
• คำอธิบายข้อมูล callback Object:

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

              
              const appkey = "your_appkey";
const userStr = "adminDemo";

MTpushInterface.init({
  appkey: appkey,
  user_str: userStr,
  fail(data) {
    console.log("Online push setup failed", data);
  },
  success(data) {
    console.log("Online push setup successful", data);
  },
  webPushcallback(code, tip) {
    console.log("Status code and message", code, tip);
  },
  canGetInfo(data) {
    // RegId is available here, and initialization config data can also be read from data.
    console.log("Obtained RegId", MTpushInterface.getRegistrationID(), data);
    // MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
  },
  custom: (requestPermission) => {
    // For custom prompt settings, call requestPermission during an appropriate user action to request notification permission.
    document.getElementById("subscribe")?.addEventListener("click", () => {
      if (Notification.permission === "default") {
        requestPermission();
      } else if (Notification.permission === "denied") {
        console.log("Notification permission is denied and cannot be requested");
      } else {
        console.log("Notification permission has already been granted");
      }
    });
  },
});

            

รับ RegistrationID

คำอธิบายอินเทอร์เฟซ

เรียก API นี้เพื่อรับ RegistrationID ที่ตรงกับบัญชีปัจจุบัน ค่าที่ตรงกันจะถูกส่งกลับเมื่อการลงทะเบียนลายเซ็นเริ่มต้นสำเร็จเท่านั้น มิฉะนั้นจะส่งกลับสตริงว่าง ต้องเรียกใช้เมธอดนี้หลังจากเรียกใช้ callback canGetInfo แล้ว

              
              window.MTpushInterface.getRegistrationID()

            

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

              
              var rid = window.MTpushInterface.getRegistrationID();

            

หยุด push

เรียก API นี้เพื่อตัดการเชื่อมต่อแบบถาวรกับแบ็กเอนด์และหยุดรับข้อความ push

              
              window.MTpushInterface.mtPush.stopPush()

            

การตรวจสอบข้อความ push

คำอธิบายอินเทอร์เฟซ

แนะนำให้เรียกตัวตรวจสอบข้อความก่อนเริ่มต้น

              
              window.MTpushInterface.onMsgReceive(fn)

            

คำอธิบายพารามิเตอร์

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

              
              window.MTpushInterface.onMsgReceive(function (res) {
   if(res.type===0){
    // res.data.messages[]
    // res.data.messages[].msg_id
    // res.data.messages[].title
    // res.data.messages[].content
    // res.data.messages[].extras
   }else{
    // res.data.title
   }

});

            

ข้อมูลที่ส่งกลับ

อาร์เรย์ข้อความช่องทาง Engagelab (messages)

ข้อมูลข้อความช่องทางระบบ

รองรับอินเทอร์เฟซ NotificationOptions ของ w3c ดูรายละเอียดที่ https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/notifications/NotificationOptions

ตรวจสอบสถานะบริการ push

              
              window.MTpushInterface.getPushAuthority()

            

โครงสร้างข้อมูลที่ส่งกลับมีดังนี้:

              
              {
   mtPush: {
     code:1, //1 สำเร็จ, -1 กำลังเริ่มต้น, 0 ล้มเหลว
     msg:'success'
   },
   webPush: {
     code:1, // 0 webpush ไม่พร้อมใช้งาน (เบราว์เซอร์ไม่รองรับ) 1 พร้อมใช้งาน 2 สิทธิ์ถูกปิดใช้งาน 3 สิทธิ์ยังไม่ได้รับการยืนยัน
     msg:'success'
   }
}

            

• รหัสข้อผิดพลาดสำหรับวัตถุ webPush:

รหัสสถานะต่อไปนี้ใช้กับ getPushAuthority().webPush.code และ webPushcallback(code, tip) โดยแยกจากรหัสใน callback fail ของการเริ่มต้น

รับสิทธิ์การแจ้งเตือนของเบราว์เซอร์

              
              window.MTpushInterface.getWebPermission()

            

คำอธิบายพารามิเตอร์ที่ส่งกลับ

• granted : พร้อมใช้งาน
• denied : ปิดใช้งาน
• default: สิทธิ์ยังไม่ได้รับการยืนยัน

รายงานข้อความที่กำหนดเอง

หากต้องการรายงานข้อความที่กำหนดเองเพื่อทำสถิติ โปรดใช้ API การรายงานแบบกำหนดเอง

รายงานการแสดงผล:

              
              window.MTpushInterface.customDisplayReport('msg_id');//msg_id คือ msg_id ของข้อความที่กำหนดเอง

            

รายงานการคลิก:

              
              window.MTpushInterface.customClickReport('msg_id');//msg_id คือ msg_id ของข้อความที่กำหนดเอง

            

การตรวจสอบการตัดการเชื่อมต่อ

คำอธิบายอินเทอร์เฟซ

หากเกิดการตัดการเชื่อมต่อหลังจากการเริ่มต้นสำเร็จ SDK จะพยายามเชื่อมต่อและลงชื่อใหม่โดยอัตโนมัติ แนะนำให้เรียกตัวตรวจสอบเหตุการณ์นี้ก่อนเริ่มต้น และเรียกการเริ่มต้นอีกครั้งหลังจากได้รับเหตุการณ์นี้

              
              window.MTpushInterface.mtPush.onDisconnect(fn)

            

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

              
              window.MTpushInterface.mtPush.onDisconnect(function () {
});

            

ยกเลิกการสมัครรับการแจ้งเตือนของเบราว์เซอร์

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

              
              MTpushInterface. unSubscribe();

            

ตั้งค่า TagsAlias

window.MTpushInterface.setTagsAlias({})

              
              
MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });

            

คำอธิบายพารามิเตอร์

คำอธิบายอินเทอร์เฟซ

นักพัฒนาสามารถตั้งค่า tag และ alias ผ่านอินเทอร์เฟซนี้ โปรดทราบว่าอินเทอร์เฟซนี้ใช้ตรรกะการเขียนทับ การตั้งค่าเป็นสตริงว่างจะลบ tag และ alias ที่มีอยู่

ตั้งค่าภาษาการแจ้งเตือน

MTpushInterface.setLan(lan)

              
              MTpushInterface.setLan(lan, (err) => {
  alert(err ? "ตั้งค่าภาษาการแจ้งเตือนล้มเหลว: " + err : "ตั้งค่าภาษาการแจ้งเตือนสำเร็จ");
});

            

คำอธิบายพารามิเตอร์

คำอธิบายอินเทอร์เฟซ

นักพัฒนาสามารถใช้ API นี้เพื่อตั้งค่าภาษาการแจ้งเตือนด้วยตนเอง หลังจากตั้งค่าสำเร็จ SDK จะบันทึกภาษานั้นไว้ หากการเริ่มต้นครั้งถัดไปไม่ได้ส่ง userLang จะใช้ภาษาที่บันทึกไว้ในเครื่องก่อน

การแสดงคำแนะนำหมวดหมู่หลายครั้ง

              
              window.MTpushInterface.promptPushCategories();

            

คำอธิบายอินเทอร์เฟซ

หลังจากผู้ใช้สมัครรับการแจ้งเตือน push แล้ว นักพัฒนาสามารถแสดงคำแนะนำหมวดหมู่หลายครั้งตามต้องการ ต้องเรียกใช้หลังจากเริ่มต้น SDK แล้ว

ความเข้ากันได้ของ Callback บน Safari

ตั้งแต่ SDK v3.3.8 ระบบจะเลือกช่องทาง push ตามประเภทการสมัครของ Safari ที่ใช้อยู่ ความพร้อมใช้งานของ callback ขึ้นอยู่กับประเภทการสมัคร สถานะของหน้าเว็บเมื่อเกิดเหตุการณ์ และเวลาที่ลงทะเบียน listener:

Callback ฝั่งหน้าเว็บ การแสดงการแจ้งเตือนของระบบ และการรายงานสถิติฝั่งเซิร์ฟเวอร์เป็นกลไกที่แยกจากกัน การไม่ได้รับ callback ฝั่งหน้าเว็บไม่ได้หมายความว่าการแจ้งเตือนไม่ได้แสดง หรือเซิร์ฟเวอร์ไม่ได้บันทึกข้อมูลการส่ง การแสดงผล หรือการคลิก

การเรียกกลับการแสดงข้อความพุช

คำอธิบายอินเทอร์เฟซ

แนะนำให้เรียกใช้ตัวฟังข้อความก่อนการเริ่มต้นใช้งาน

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

              
              window.MTpushInterface.onMsgDisplay((msgData) => {});

            

คำอธิบายพารามิเตอร์

คำอธิบายพารามิเตอร์การเรียกกลับข้อความแจ้งเตือน msgData:

              
              {
  engagelab_ntf_or_msg: number;
  engagelab_appkey: string;
  engagelab_passwd: string;
  engagelab_uid: number;
  engagelab_m_str: string;
  engagelab_a_str: string;
  type: number;
  title: string;
  content: string;
  msg_id: string;
}

            

คำอธิบายพารามิเตอร์การเรียกกลับข้อความในแอป msgData:

              
              {
  title: string;
  content: string;
  msg_id: string;
  ntf_or_msg: number;
  type: number;
}

            

ชนิดข้อมูลนี้ใช้กับเทมเพลตข้อความในแอปมาตรฐานของคอนโซล ซึ่ง type เป็นตัวเลข 0 ส่วนเทมเพลต HTML ที่กำหนดเองจะกำหนดข้อมูล callback เอง

หมายเหตุ:

1. ในโหมดแก้ไข HTML สำหรับข้อความในแอป พารามิเตอร์การเรียกกลับ title และ content จะเป็นสตริงว่าง

2. Callback ของ Safari อยู่ภายใต้เงื่อนไขความเข้ากันได้ข้างต้น โปรดลงทะเบียน listener ก่อนเริ่มต้น SDK และตรวจสอบว่ามีหน้าเว็บที่อยู่ภายใต้การควบคุมของ Service Worker เมื่อเกิดเหตุการณ์

การเรียกกลับการคลิกข้อความพุช

คำอธิบายอินเทอร์เฟซ

แนะนำให้เรียกใช้ตัวฟังข้อความก่อนการเริ่มต้นใช้งาน

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

              
              window.MTpushInterface.onMsgClick((msgData) => {});

            

คำอธิบายพารามิเตอร์

คำอธิบายพารามิเตอร์การเรียกกลับข้อความแจ้งเตือน msgData:

              
              {
  engagelab_ntf_or_msg: number;
  engagelab_appkey: string;
  engagelab_passwd: string;
  engagelab_uid: number;
  engagelab_m_str: string;
  engagelab_a_str: string;
  type: number;
  title: string;
  content: string;
  msg_id: string;
  target_event: string | null;
  position: string; // ตำแหน่งการคลิก, 'msgBody' | Button ID
}

            

คำอธิบายพารามิเตอร์การเรียกกลับข้อความในแอป msgData:

              
              {
  position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
  msg_id: number;
  title: string;
  content: string;
  extras: object | null;
  ntf_or_msg: number;
  strategy: object | null;
  target_event: unknown[];
  type: number;
  icon: string;
}

            

หมายเหตุ:

1. ในโหมดแก้ไข HTML สำหรับข้อความในแอป ค่าของ position จะถูกกำหนดโดยนักพัฒนา และพารามิเตอร์การเรียกกลับ title และ content จะเป็นสตริงว่าง
2. Callback ของ Safari อยู่ภายใต้เงื่อนไขความเข้ากันได้ข้างต้น หากไม่มีหน้าเว็บที่รับข้อความได้เมื่อคลิกการแจ้งเตือน การเปิดหน้าเป้าหมายจะไม่ส่ง callback การคลิกย้อนหลัง

รหัสข้อผิดพลาด

ตารางต่อไปนี้แสดงค่า data.code ชั้นนอกของ callback การเริ่มต้น ส่วนสาเหตุเฉพาะของข้อผิดพลาดฝั่งเซิร์ฟเวอร์อยู่ใน data.content.code ตัวเลขเดียวกันในสองฟิลด์นี้อาจมีความหมายต่างกัน

รหัสข้อผิดพลาดจากการเริ่มต้นฝั่งเซิร์ฟเวอร์

เมื่อการเริ่มต้นล้มเหลว SDK จะส่งรหัสข้อผิดพลาดชั้นนอกผ่าน fail เช่น data.code === 1003 หาก data.content เป็นออบเจ็กต์ ให้ดูรหัสข้อผิดพลาดเฉพาะของเซิร์ฟเวอร์ที่ data.content.code และคำอธิบายจากเซิร์ฟเวอร์ที่ data.content.desc หากมี

การตรวจสอบการเริ่มต้นและข้อผิดพลาดของบริการ

ตัวอย่างเช่น data.code === 1003 พร้อมกับ data.content.code === 4008 หมายถึงการเริ่มต้นล้มเหลวเพราะบริการ VIP หมดอายุ ควรตรวจสอบทั้ง code ชั้นนอกและสาเหตุเฉพาะใน content

รหัสข้อผิดพลาดที่ส่งต่อจากบริการลงทะเบียน

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

ตัวอย่างเช่น data.code === 1008 ชั้นนอกหมายถึงข้อจำกัดตามภูมิภาค แต่หากรหัสชั้นนอกเป็น 1003 และชั้นในเป็น data.content.code === 1008 จะหมายถึงไม่มีแอปพลิเคชันนี้

รายละเอียดการตรวจสอบสิทธิ์ที่ล้มเหลว

เมื่อ API ตรวจสอบสิทธิ์ล้มเหลว SDK จะนำ message จากการตอบกลับใส่ในสตริง data.content โดยไม่ส่ง code เดิมของ API เป็น content.code หากต้องการดูรหัสเดิมต่อไปนี้ ให้ตรวจสอบการตอบกลับของคำขอตรวจสอบสิทธิ์ (/v1/auth) ในเครื่องมือสำหรับนักพัฒนาของเบราว์เซอร์

การแจ้งเตือนการสมัครรับข้อมูลหมดอายุ

เซิร์ฟเวอร์ส่ง 4107 (subscribe expired) ผ่านคำสั่ง WebSocket expired เมื่อการสมัครรับข้อความ push ของเบราว์เซอร์หมดอายุ นี่คือการแจ้งเตือนระบบหลังการเริ่มต้น ไม่ใช่รหัสข้อผิดพลาดใน callback fail ของการเริ่มต้น ตัวรับฟัง mtPush.onExpired ของ SDK จะได้รับการแจ้งเตือน แต่ callback จะไม่ส่งรหัสข้อผิดพลาดนี้มาด้วย