คู่มือการผสานรวม Web SDK

เอกสารนี้เป็นคู่มือการผสานรวมมาตรฐานสำหรับ MA Web SDK

คำอธิบายผลิตภัณฑ์

MA Web SDK ให้บริการฟังก์ชันการรวบรวมและรายงานข้อมูล ซึ่งใช้ในสถานการณ์ต่าง ๆ เช่น การสร้าง EUID การตั้งค่าคุณสมบัติผู้ใช้ และการรายงานเหตุการณ์

ตัวเลือกการผสานรวม

MA Web SDK รองรับวิธีการเข้าถึง 2 แบบ ได้แก่ ใช้งานร่วมกับ WebPush หรือใช้งาน MA Web SDK แบบแยกเดี่ยว

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

ใช้งานร่วมกับ WebPush

การเตรียมตัวก่อนการผสานรวม

• จำเป็นต้องผสานรวมโมดูล WebPushไปพร้อมกัน
• เตรียมชื่อโดเมนบริการเว็บ HTTPS ที่สามารถเข้าถึงได้ หลังจากการผสานรวมแล้ว จำเป็นต้องทดสอบและดีบักหน้าเว็บภายใต้ชื่อโดเมนนี้ การแจ้งเตือนแบบพุชออฟไลน์บนเว็บไม่รองรับการดีบักในเครื่องและไม่รองรับ HTTP
• เข้าถึง EngageLab WebPush และในหน้า [การตั้งค่าการผสานรวม] - [ชื่อโดเมนเว็บไซต์] ให้กรอกชื่อโดเมนบริการเว็บ HTTPS

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

คุณจำเป็นต้องสร้างแอปพลิเคชันในคอนโซล WebPush หลังจากสร้างสำเร็จแล้ว ระบบจะสร้าง AppKey โดยอัตโนมัติเพื่อระบุแอปพลิเคชันนี้ สำหรับรายละเอียดเพิ่มเติม โปรดดูที่ เอกสารการตั้งค่าแอปพลิเคชัน

การกำหนดค่าแหล่งข้อมูล MA

ในโปรเจกต์ MA ไปที่ แหล่งข้อมูล - เพิ่มแหล่งข้อมูล - Web เลือก「ใช้งานร่วมกับ WebPush」 จากนั้นเลือกแอปพลิเคชันที่สร้างไว้ใน WebPush จากรายการดรอปดาวน์ แล้วบันทึก

การเข้าถึง SDK

ไปที่ คอนโซล ดาวน์โหลด SDK และนำเข้า js ในแต่ละหน้า:

              
              <script type="text/javascript" src="./WebSDK.3.3.4.js"></script>

            

เคล็ดลับ

หลังจากนำเข้า js นี้ ให้ส่งคุณสมบัติ maOpen พร้อมค่า true เพื่อเปิดใช้งานการตั้งค่า MA จากนั้นจึงสามารถใช้ API และฟีเจอร์ที่เกี่ยวข้องของ MA ได้

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

              
                  //  เริ่มต้นใช้งาน (เปิด MA)
  MTpushInterface.init({
    appkey: "", // จำเป็นต้องกรอก ดูรายละเอียดในหัวข้อรับข้อมูลแอปพลิเคชันด้านบน
    user_str: "adminDemo", // จำเป็นต้องกรอก ตัวระบุผู้ใช้ ใช้สำหรับระบุผู้ใช้
    swUrl: "url", //ค่าเริ่มต้น "/sw.min." + sdkEnv.version + ".js" การตั้งค่านี้คือที่อยู่ไฟล์ server worker โดเมนต้องเป็นโดเมนปัจจุบัน และเส้นทางจะกำหนดขอบเขตการทำงานของ server worker
    debugMode: true,// ตั้งค่าว่าจะเปิดโหมด debug หรือไม่ true จะพิมพ์ข้อมูลล็อกมากขึ้น หากตั้งเป็น false จะแสดงเฉพาะล็อกระดับ w และ e
    channel: "default-channel",// ชื่อช่องทาง ค่าเริ่มต้น: default-channel
    appName: "string",// ใช้ตั้งชื่อเว็บไซต์ สำหรับการรายงาน
    maOpen: true, //เปิดสวิตช์เพื่อเปิดใช้ฟีเจอร์ MA
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },//ตั้งค่ารหัสผู้ใช้พร้อมกับการเริ่มต้น MA รองรับตั้งแต่เวอร์ชัน 3.3.4 เหมาะสำหรับองค์กรที่ให้บริการ MA เฉพาะสมาชิกที่ล็อกอินแล้ว
    maDataCollectionEnabled: false, //สถานะเริ่มต้นของการรวบรวมข้อมูล MA หากไม่ส่งค่า ค่าเริ่มต้นคือเปิด รองรับตั้งแต่ WebPush SDK 3.3.9
    maCompletion: (code, msg) => {//การเรียกกลับหลังเริ่มต้น MA
                if (code === 0) {
                    console.log("✅MA SDK เริ่มต้นใช้งานสำเร็จ!");
                } else {
                    console.error("❌MA SDK เริ่มต้นใช้งานล้มเหลว:", msg);
                }
    }
  });

            

สวิตช์การรวบรวมข้อมูล (ใช้งานร่วมกับ WebPush)

เวอร์ชันที่เริ่มรองรับ: MA Web SDK 2.2.0, WebPush SDK 3.3.9

• ขณะเริ่มต้นด้วย MTpushInterface.init โปรดส่งค่า maDataCollectionEnabled แบบไดนามิกตามสถานะการให้ความยินยอมของผู้ใช้ WebPush SDK จะส่งผ่านค่านี้ไปยัง MA SDK โปรดระวังอย่าเขียนค่าตายตัวในการตั้งค่า เพื่อหลีกเลี่ยงไม่ให้สถานะถูกรีเซ็ตเป็นค่าตายตัวทุกครั้งที่เริ่มต้น
• เมื่อสถานะการรวบรวมข้อมูลของผู้ใช้เปลี่ยนแปลง ให้เรียก window.MAInterface.setDataCollectionEnabled(true/false) หลังจากการเรียกกลับ maCompletion ถูกทริกเกอร์แล้ว maCompletion เป็นสัญญาณว่า MA SDK พร้อมใช้งาน ก่อนหน้านั้น window.MAInterface อาจยังไม่ถูกโหลด
• ในช่วงที่ปิดการรวบรวมข้อมูล การแจ้งเตือน WebPush ยังคงส่งถึงและคลิกได้ แต่จะไม่นับการระบุแหล่งที่มาของการแปลง (conversion attribution) จากการคลิกการแจ้งเตือนอีกต่อไป

ดูรายละเอียดได้ที่ สวิตช์การรวบรวมข้อมูล

ใช้งาน MA Web SDK แบบแยกเดี่ยว

การกำหนดค่าแหล่งข้อมูล MA

ในโปรเจกต์ MA ไปที่ แหล่งข้อมูล - เพิ่มแหล่งข้อมูล - Web ในตัวเลือก「ใช้งานร่วมกับ WebPush หรือไม่」ให้เลือก「ไม่ใช้」 กรอกชื่อแหล่งข้อมูลและชื่อโดเมนของเว็บไซต์ หลังจากบันทึกแล้วจะได้รับข้อมูล Appkey ของแหล่งข้อมูล Web

• โปรดเตรียมชื่อโดเมนบริการเว็บ HTTPS ที่สามารถเข้าถึงได้ หลังจากการผสานรวมแล้ว จำเป็นต้องทดสอบและดีบักหน้าเว็บภายใต้ชื่อโดเมนนี้

การเข้าถึง SDK

นำเข้า js ต่อไปนี้ในแต่ละหน้า:

              
              <script type="text/javascript" src="https://websdk-res.engagelab.com/lib/ma-web.min.js"></script>
        

            

หลังจากนำเข้า JS นี้แล้ว จะสามารถใช้ออบเจ็กต์ส่วนกลาง MAInterface บน Window ได้

ข้อควรทราบพิเศษ: โปรดใช้ลิงก์นี้โดยตรง อย่าดาวน์โหลดไฟล์นี้ไปไว้ในโปรเจกต์ของคุณ มิฉะนั้น เมื่อเราอัปเดตโครงสร้างข้อมูลหรืออินเทอร์เฟซ API อาจทำให้การเก็บสถิติใช้งานไม่ได้

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

              
                window.MAInterface.init({
    appKey: "7ccf93e0950b5e22f4ca2124",  // จำเป็นต้องกรอก ดูรายละเอียดในหัวข้อรับข้อมูลแอปพลิเคชันด้านบน
    debugMode: true,
    channel: "default-channel22",// ชื่อช่องทาง ค่าเริ่มต้น: default-channel
    appName: "EngageLab-MA test-appName", //ชื่อเว็บไซต์ ใช้ตั้งค่า app_name ในคุณสมบัติอุปกรณ์และการรายงานเหตุการณ์
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, //ตั้งค่ารหัสผู้ใช้พร้อมกับการเริ่มต้น MA รองรับ user_id, anonymous_id, email และ phone
      completion: (code, msg) => {
        if (code === 0) {
            console.log("✅ SDK เริ่มต้นใช้งานสำเร็จ!");
        } else {
            console.error("❌ SDK เริ่มต้นใช้งานล้มเหลว:", msg);
        }
    }
  })
        

            

คำอธิบายรหัสผู้ใช้

• userIdentity รองรับรหัสผู้ใช้ 4 ประเภท ได้แก่ user_id, anonymous_id, email และ phone (email และ phone รองรับตั้งแต่เวอร์ชัน 2.1.0) ต้องระบุอย่างน้อยหนึ่งรายการ กฎของแต่ละฟิลด์ดูรายละเอียดที่ ตั้งค่ารหัสผู้ใช้
• ฟิลด์ที่ไม่เป็นไปตามกฎขณะเริ่มต้นจะถูกละเว้นและพิมพ์คำเตือนในคอนโซล ส่วนฟิลด์อื่นที่ถูกต้องจะยังคงมีผล
• email และ phone ใช้สำหรับจับคู่ตัวตนของผู้ใช้ ไม่ใช่ข้อมูลติดต่อ อีเมลและหมายเลขโทรศัพท์ที่ใช้สำหรับการส่งข้อความถึงผู้ใช้ โปรดตั้งค่าผ่านอินเทอร์เฟซ「ตั้งค่าข้อมูลติดต่อผู้ใช้」(setUserContact)

การเริ่มต้นซ้ำและการสลับ AppKey

เวอร์ชันที่เริ่มรองรับ: 2.1.0

หลังจาก SDK เริ่มต้นแล้ว สามารถเรียก init อีกครั้งได้โดยไม่ต้องรีเฟรชหน้า:

• ส่ง AppKey เดิม: SDK จะขอรับ EUID ใหม่ หากส่ง userIdentity ใหม่มาพร้อมกัน SDK จะใช้รหัสผู้ใช้ใหม่ในการขอรับ EUID ใหม่ เหมาะกับสถานการณ์ที่ออกจากระบบแล้วสลับบัญชีภายในหน้าเดียวกัน
• ส่ง AppKey อื่น: SDK จะสลับไปยังแหล่งข้อมูล MA ที่ตรงกับ AppKey ใหม่ ข้อมูลหลังจากนั้นจะรายงานไปยังแหล่งข้อมูลใหม่ ส่วนข้อมูลที่เกิดขึ้นก่อนการสลับจะยังคงรายงานไปยังแหล่งข้อมูลเดิม
• การเรียก init หลายครั้งจะทำงานตามลำดับการเรียก แต่ละครั้งจะส่งผลลัพธ์กลับผ่าน completion โปรดยึดผลลัพธ์จากการเรียกกลับของครั้งนั้นเป็นหลัก
• รองรับการสลับ AppKey เฉพาะเมื่อใช้งาน MA Web SDK แบบแยกเดี่ยวเท่านั้น วิธีการเข้าถึงแบบ「ใช้งานร่วมกับ WebPush」ไม่รองรับ

              
                // สลับไปยังแหล่งข้อมูล MA อื่น
  window.MAInterface.init({
    appKey: "AppKey ของแหล่งข้อมูลอื่น",
    completion: (code, msg) => {
      console.log(code, msg)
    }
  })

            

ตั้งค่า ID ติดต่อของช่องทาง

เวอร์ชันที่เริ่มรองรับ: 2.1.0

หากต้องการตั้งค่า RID หรือ Token ให้กับช่องทาง WebPush หรือ Push ของบุคคลที่สาม โปรดเรียกใช้หลังจาก SDK เริ่มต้นสำเร็จแล้ว:

              
                window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message) => { })

            

• channelId: ID ของช่องทาง Push ที่กำหนดค่าไว้ในคอนโซล MA ต้องมากกว่า 0
• values: อาร์เรย์ของ RID หรือ Token ทั้งอาร์เรย์และองค์ประกอบต้องไม่ว่างเปล่า เมื่อ RID หรือ Token เปลี่ยนแปลง ต้องเรียกอินเทอร์เฟซอีกครั้งเพื่ออัปเดต

ดูรายละเอียดได้ที่ ตั้งค่า ID ติดต่อของช่องทาง

สวิตช์การรวบรวมข้อมูล

เวอร์ชันที่เริ่มรองรับ: 2.2.0

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

              
                // ขณะเริ่มต้น โปรดส่งค่า dataCollectionEnabled แบบไดนามิกตามสถานะการให้ความยินยอมของผู้ใช้ อย่าเขียนค่าตายตัว เพื่อหลีกเลี่ยงไม่ให้สถานะถูกรีเซ็ตเป็นค่าตายตัวทุกครั้งที่เริ่มต้น
  window.MAInterface.init({
    appKey: "your appKey",
    dataCollectionEnabled: false, // หากไม่ส่งค่า ค่าเริ่มต้นคือเปิด
    completion: (code, msg) => {}
  })

  // หลังจากผู้ใช้ให้ความยินยอม / ถอนความยินยอม
  window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {})
  window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {})

            

• เมื่อค่าที่ตั้งเหมือนกับสถานะปัจจุบัน จะไม่ทริกเกอร์การประมวลผลการสลับ การซิงก์ตัวเลือกของผู้ใช้ทุกครั้งที่โหลดหน้าจึงไม่ส่งผลกระทบเพิ่มเติม
• ในช่วงที่ปิด หากเรียกอินเทอร์เฟซคุณสมบัติผู้ใช้ completion จะส่งคืน -8 ส่วนอินเทอร์เฟซที่ไม่มีการเรียกกลับ เช่น เหตุการณ์และ UTM จะถูกทิ้งแบบเงียบ
• เมื่อการจัดเก็บถูกลดระดับ (localStorage ใช้งานไม่ได้) สถานะสวิตช์จะมีผลเฉพาะในแท็บปัจจุบันเท่านั้น

ดูรายละเอียดได้ที่ สวิตช์การรวบรวมข้อมูล

อินเทอร์เฟซ API เพิ่มเติม

สำหรับวิธีใช้งาน API อื่น ๆ โปรดดูเอกสารอินเทอร์เฟซ: Web SDK API