การผสานรวมการสตรีม Event

ต้องการความช่วยเหลือจากนักพัฒนา

คุณจะต้องได้รับความช่วยเหลือจากทีมนักพัฒนาของคุณเพื่อตั้งค่าการผสานรวมนี้ โปรดแชร์คู่มือนี้กับพวกเขา

ภาพรวมการผสานรวม

ประเภทการผสานรวม

Source: ข้อมูลจะถูกส่งจาก Pushwoosh ไปยังระบบของคุณผ่าน HTTP หรือ gRPC ตามทริกเกอร์ event ที่กำหนดค่าไว้

การผสานรวมทำงานอย่างไร

Pushwoosh จะส่งข้อมูล event การสื่อสาร (เช่น กิจกรรมพุช/อีเมล) ไปยัง endpoint ที่ไคลเอนต์กำหนด ข้อมูลจะถูกส่งในรูปแบบสตรีมแบบแบตช์ตามช่วงเวลาที่กำหนดหรือเมื่อถึงขนาดแบตช์ขั้นต่ำ

ข้อมูลจะถูกส่งก็ต่อเมื่อตรงกับ events แพลตฟอร์ม และตัวกรองเสริมที่เลือก (รหัสแคมเปญ/ข้อความ, กิจกรรมสด) endpoint ของไคลเอนต์ต้องพร้อมที่จะรับและตอบกลับสถานะ (เป็นทางเลือก)

คำศัพท์

Endpoint URL: endpoint ฝั่งเซิร์ฟเวอร์ที่อนุญาตให้รับคำขอ ไคลเอนต์อาจระบุพอร์ตหากจำเป็น

ตัวอย่าง:

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

รายการเอนทิตีที่ซิงโครไนซ์

• Event สถิติการสื่อสาร (เช่น Push Sent, Email Delivered)
• Post events: events ที่แอปของคุณส่งไปยัง Pushwoosh ผ่าน postEvent ซึ่งจะถูกสตรีมแยกจาก event สถิติการสื่อสาร

กรณีการใช้งาน

• การติดตามการมีส่วนร่วมแบบเรียลไทม์

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

• การผสานรวมกับการวิเคราะห์ภายนอก

สตรีม events ไปยังแพลตฟอร์มการวิเคราะห์ของบุคคลที่สามเพื่อการรายงานและการวิเคราะห์แบบรวมศูนย์

• เวิร์กโฟลว์ผู้ใช้อัตโนมัติ

ทริกเกอร์การดำเนินการในระบบภายนอก (เช่น CRM หรือเครื่องมือการตลาดอัตโนมัติ) ตามพฤติกรรมของผู้ใช้ เช่น ส่งข้อความติดตามผลเมื่อผู้ใช้เปิดอีเมล

• การซิงค์รายการอุปกรณ์

ลบอุปกรณ์ออกจากฐานข้อมูลของคุณเองเมื่ออุปกรณ์นั้นไม่สามารถรับข้อความได้อีกต่อไป ดูซิงค์อุปกรณ์ที่ยกเลิกการลงทะเบียนไปยังระบบของคุณ

การตั้งค่าการผสานรวม

ในการตั้งค่าการผสานรวม:

1. ในบัญชี Pushwoosh ของคุณ ไปที่ Settings > 3rd party Integrations ค้นหา Event streaming integration และคลิก Configure

2. ในหน้าต่างที่เปิดขึ้น ให้กรอกข้อมูลในฟิลด์ที่จำเป็น

ป้อน Endpoint URL

ในฟิลด์ Endpoint URL ให้ป้อน URL แบบเต็มที่จะใช้ส่ง events รวมถึงโปรโตคอลและพอร์ต (ถ้ามี)

ตัวอย่าง

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

เลือก events

จากดรอปดาวน์ Events ให้เลือกอย่างน้อยหนึ่ง event หากไม่เลือก การตรวจสอบความถูกต้องจะล้มเหลว รายการ events จะถูกจัดการโดยแบ็กเอนด์และอาจเปลี่ยนแปลงได้ตลอดเวลา

ระบุข้อมูลรับรองการให้สิทธิ์

หากเซิร์ฟเวอร์ของคุณต้องการ ให้ป้อนค่าที่สมบูรณ์สำหรับ Authorization header ในฟิลด์ Authorization

ตัวอย่าง:

• Bearer your_token_here

• Basic base64encoded_credentials

หมายเหตุ

ค่านี้จะถูกแทรก ตามที่เป็น ลงใน Authorization header (HTTP) หรือ gRPC metadata ตรวจสอบให้แน่ใจว่ามีช่องว่างระหว่างรูปแบบการยืนยันตัวตนและโทเค็น

เลือกประเภทการส่ง

จากดรอปดาวน์ Transport type ให้เลือกโปรโตคอลการจัดส่งสำหรับการส่ง event: HTTP หรือ gRPC แต่ละประเภทมีพฤติกรรมและการกำหนดค่าเฉพาะ

HTTP

ด้วยประเภทการส่ง HTTP Pushwoosh จะส่งข้อมูลเป็นแบตช์ตามเงื่อนไขข้อใดข้อหนึ่งต่อไปนี้:

• มี events อย่างน้อย 100 รายการพร้อมที่จะส่ง หรือ

• ผ่านไปหนึ่งชั่วโมงนับจากการส่งครั้งล่าสุด

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

หากเซิร์ฟเวอร์ตอบกลับด้วย 5xx error Pushwoosh จะพยายามส่งคำขออีกครั้งตามนโยบายการลองใหม่ที่กำหนดไว้

กลไกการลองใหม่

ครั้งที่	การหน่วงเวลา
1	1 วินาที
2	3 วินาทีหลังจากการลองครั้งที่ 1
3	8 วินาทีหลังจากการลองครั้งที่ 2

หากการลองใหม่ทั้งหมดล้มเหลว คำขอจะถูกยกเลิก หากปลายทางของคุณล้มเหลวต่อเนื่องเป็นเวลา 24 ชั่วโมงโดยไม่รับ event ใดเลย Pushwoosh จะหยุดการผสานรวมชั่วคราว ดูการผสานรวมที่ถูกหยุดชั่วคราว

การหมดเวลา

การหมดเวลาเริ่มต้นสำหรับคำขอคือ 30 วินาที สามารถปรับแต่งได้ตามคำขอผ่านฝ่ายสนับสนุน

ดูตัวอย่าง

gRPC

ประเภทการส่ง gRPC ใช้ bidirectional streaming สำหรับการส่งข้อมูล เรียนรู้เพิ่มเติมใน เอกสาร gRPC

สตรีมจะเปิดขึ้นเมื่อตรงตามเงื่อนไขข้อใดข้อหนึ่งต่อไปนี้:

• มี events อย่างน้อย 1,000 รายการพร้อมสำหรับการจัดส่ง
• ผ่านไปหนึ่งชั่วโมงนับจากสตรีมล่าสุดที่เปิด

สตรีมจะถูกปิดหลังจากส่ง events แล้ว สิ่งนี้ช่วยให้แน่ใจว่าจะไม่มีการเปิดสตรีมใหม่สำหรับแต่ละ event ในช่วงเวลาสั้นๆ

ดูข้อกำหนด protobuf

กลไกการลองใหม่
แต่ละ event จะมี uuid ที่ไม่ซ้ำกัน หาก event ล้มเหลว:

1. การตอบกลับต้องมี status ไม่เท่ากับ "Success"
2. ต้องมี uuid เดิมจากคำขอรวมอยู่ด้วย

Pushwoosh จะพยายามจัดส่งอีกครั้งตามการตอบกลับนี้

การตั้งค่าการเชื่อมต่อ

ตัวเลือกขั้นสูง เช่น TLS, keep-alive หรือ retry policies จะถูกกำหนดค่าด้วยตนเองผ่านฝ่ายสนับสนุนและอาจต้องอาศัยความช่วยเหลือจากฝ่ายพัฒนา

เปิดใช้งาน post events

โดยค่าเริ่มต้น ตัวสลับนี้จะปิดอยู่ ดังนั้นจะมีเพียง event สถิติการสื่อสารเท่านั้นที่สตรีม หากต้องการสตรีม events ที่แอปของคุณส่งไปยัง Pushwoosh ผ่าน postEvent ด้วย ให้เปิดตัวสลับ Allow post events

จากฟิลด์ Post events ที่ปรากฏขึ้น ให้เลือก events ของบัญชีของคุณที่จะสตรีม ต้องมีอย่างน้อยหนึ่ง event ในขณะที่ตัวสลับเปิดอยู่ หากบัญชีของคุณยังไม่เคยส่ง events ใดๆ รายการนี้จะว่างเปล่าจนกว่าคุณจะเรียก postEvent อย่างน้อยหนึ่งครั้ง

หมายเหตุ

Post events จะถูกส่งไปยัง Endpoint URL เดียวกันกับที่ป้อนไว้ข้างต้น และจะไปถึงโดยไม่คำนึงถึงแพลตฟอร์ม: ส่วน Platforms และ Advanced filters ด้านล่างนี้จะใช้กับ event สถิติการสื่อสารเท่านั้น ไม่ใช่กับ post events

การแสดงผลและการคลิก in-app ก็ส่งผ่านสตรีม post event นี้เช่นกัน ในชื่อ PW_InAppShow และ PW_InAppClicked แต่ละรายการจะปรากฏในรายการ Post events หลังจากที่เกิดขึ้นอย่างน้อยหนึ่งครั้งสำหรับบัญชีแล้วเท่านั้น เช่นเดียวกับ post event อื่นๆ

เลือกแพลตฟอร์ม

ในส่วน Platforms ให้เลือกอย่างน้อยหนึ่งแพลตฟอร์มเพื่อเปิดใช้งานการสตรีม event

แพลตฟอร์มที่รองรับ ได้แก่:

• iOS, Android, macOS, Windows, Amazon, Safari
• Chrome, Firefox, Internet Explorer, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

กำหนดค่าตัวกรองขั้นสูง

ในส่วน Advanced filters ให้ปรับเกณฑ์การจัดส่ง event โดยใช้ตัวกรอง:

• Live activity events: เปิดใช้งานเพื่อรับ live activity events events เหล่านี้มีเพียงข้อมูลเมตาซึ่งรวมถึง live_activity_id

• Campaign filters: กรองตามรหัสแคมเปญ เฉพาะ events ที่ผูกกับแคมเปญเหล่านี้เท่านั้นที่จะถูกจัดส่ง

• Message filters: กรองตามรหัสข้อความ เฉพาะ events ที่ผูกกับข้อความเหล่านี้เท่านั้นที่จะถูกจัดส่ง

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

หมายเหตุ

การเปลี่ยนแปลงการกำหนดค่าจะมีผล ภายใน 15 นาที หลังจากส่ง

เคล็ดลับ

สำหรับการตั้งค่าขั้นสูง เช่น การหมดเวลาที่กำหนดเอง หรือการกำหนดค่า gRPC โปรด ติดต่อฝ่ายสนับสนุน

รายละเอียดคำขอและตัวอย่าง

Endpoint	https://exampleclientendpoint.com/webhook_endpoint
HTTP Request	POST
Authentication	ไม่มี
Request type	Source
Request meaning	ส่งคำขอไปยัง webhook endpoint
Headers	Content-Type: application/json

ตัวอย่าง Request body

{
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new",
  "attributes": null
}

Attributes

ในบรรดา event สถิติการสื่อสาร attributes จะถูกเติมข้อมูลสำหรับ push events เท่านั้น โดยมีเนื้อหาเฉพาะช่องทาง (Android, iOS และอื่นๆ) สำหรับแพลตฟอร์มที่พุชถูกส่งไป Email และ SMS events จะมีเฉพาะฟิลด์ระดับบนสุดเท่านั้น (เช่น event_name, platform, payload) attributes จะเป็น null สำหรับ events เหล่านั้น ภายในอ็อบเจกต์ attributes ที่มีข้อมูล ฟิลด์ที่อยู่นอกแพลตฟอร์มของ event เองจะถูกละไว้แทนที่จะส่งเป็นค่าว่าง ดู webhook.proto สำหรับรายการฟิลด์ทั้งหมด

post event จะมีคู่คีย์/ค่าของ attribute อยู่ใน attributes.event_attributes แทน message_code และ payload จะยังคงว่างเปล่า เนื่องจาก post event ไม่ได้ผูกกับข้อความหรือแคมเปญ

ข้อควรระวัง

attributes.geozone เลิกใช้งานแล้ว: คุณสมบัติต้นทางเป็นอ็อบเจกต์ ไม่ใช่ตัวเลข ดังนั้นฟิลด์นี้จึงไม่เคยมีค่าที่แท้จริง อ่านค่า geozone ที่แท้จริงจาก attributes.geozone_data แทน ฟิลด์เก่ายังคงอยู่ในสัญญาสำหรับไคลเอนต์ที่มี gRPC stubs อยู่แล้ว

การตอบกลับ
เนื้อหาการตอบกลับจะถูกละเว้น สำหรับการส่งแบบ HTTP รหัสการตอบกลับจะเป็นตัวตัดสินว่า event ถือว่าส่งถึงแล้วหรือไม่ รหัส 2xx หมายความว่าปลายทางของคุณได้รับ event เหล่านั้นแล้ว

ซิงค์อุปกรณ์ที่ยกเลิกการลงทะเบียนไปยังระบบของคุณ

หากคุณเก็บสำเนารายการอุปกรณ์ไว้เอง เช่น ใน CRM หรือแพลตฟอร์มข้อมูลลูกค้า ให้สตรีม post event PW_DeviceUnregistered เพื่อค้นหาอุปกรณ์ที่ Pushwoosh ไม่สามารถเข้าถึงได้อีกต่อไป Pushwoosh จะส่ง event นี้เมื่ออุปกรณ์สูญเสียการสมัครรับ push ดูสาเหตุได้ที่ PW_DeviceUnregistered

เริ่มจากการผสานรวมที่ตั้งค่าไว้แล้ว โดยป้อน Endpoint URL และเลือกแพลตฟอร์มอย่างน้อยหนึ่งแพลตฟอร์ม จากนั้น:

1. ในการตั้งค่าการผสานรวม ให้เปิด Allow post events ดูเปิดใช้งาน post events
2. ในฟิลด์ Post events ให้เลือก PW_DeviceUnregistered
3. หากต้องการทราบเกี่ยวกับอุปกรณ์ที่ได้รับ push token ด้วย ให้เลือก PW_DeviceRegistered
4. คลิก Apply การเปลี่ยนแปลงจะมีผลภายใน 15 นาที

เช่นเดียวกับ post event อื่นๆ PW_DeviceUnregistered จะปรากฏในรายการ Post events หลังจากที่ถูกทริกเกอร์อย่างน้อยหนึ่งครั้งสำหรับบัญชีแล้วเท่านั้น ดูเปิดใช้งาน post events

โปรดคำนึงถึงข้อจำกัดเหล่านี้เมื่อประมวลผล event:

• จับคู่อุปกรณ์ด้วย hwid หรือ user_id ไม่ใช่ด้วย push token event มี hwid, user_id และแพลตฟอร์มของอุปกรณ์ แต่ไม่มี push token และไม่มีเหตุผลของการยกเลิกการลงทะเบียน โทเค็นที่หมดอายุและการยกเลิกการลงทะเบียนผ่าน SDK จึงดูเหมือนกัน
• การที่อุปกรณ์เดิมได้รับโทเค็นใหม่จะไม่ส่ง event PW_DeviceRegistered จะถูกทริกเกอร์เฉพาะเมื่ออุปกรณ์ที่ไม่มี push token ได้รับโทเค็นเท่านั้น รายการที่จัดเก็บอุปกรณ์ตาม push token จะเก็บโทเค็นที่ใช้งานไม่ได้แล้วไว้ เนื่องจากเมื่ออุปกรณ์ได้รับโทเค็นใหม่ จะไม่มี event ใดถูกทริกเกอร์
• การยกเลิกการสมัครรับอีเมลจะไม่ลบอุปกรณ์ สำหรับอีเมล ที่อยู่อีเมลจะยังคงอยู่บนอุปกรณ์ และ Pushwoosh จะทำเครื่องหมายว่ายกเลิกการสมัครรับเท่านั้น เมื่อผู้ใช้ยกเลิกการสมัครรับผ่านลิงก์ในอีเมล attributes.event_attributes จะมี message_code และ campaign_id ของอีเมลนั้นด้วย

บาง event อาจไม่ไปถึงปลายทางของคุณเลย เนื่องจากชุดข้อมูลที่ล้มเหลวในการลองใหม่ผ่าน HTTPทุกครั้งจะถูกละทิ้ง หากต้องการค้นหาอุปกรณ์เหล่านี้ ให้ส่งออกเซกเมนต์ของอุปกรณ์ที่คุณกำหนดเป้าหมายเป็น CSV เป็นระยะ แล้วเปรียบเทียบกับรายการอุปกรณ์ของคุณ การส่งออกเซกเมนต์ต้องมีสิทธิ์ Personal data ในบทบาทของคุณ หากปลายทางของคุณล้มเหลวต่อเนื่องเป็นเวลา 24 ชั่วโมง การผสานรวมจะถูกหยุดชั่วคราวและ event จะหยุดส่งมาถึง ดูการผสานรวมที่ถูกหยุดชั่วคราว

การผสานรวมที่ถูกหยุดชั่วคราว

หากการส่งไปยังปลายทาง HTTP ของคุณล้มเหลวต่อเนื่องเป็นเวลา 24 ชั่วโมง และปลายทางไม่รับ event ใดเลยในช่วงเวลานั้น Pushwoosh จะหยุดการผสานรวมชั่วคราว:

• Pushwoosh หยุดส่ง event ไปยังปลายทาง
• event ที่รอการส่งจะถูกละทิ้ง event จากช่วงที่หยุดชั่วคราวจะไม่ถูกส่งในภายหลัง
• เจ้าของบัญชีจะได้รับอีเมลแจ้งเรื่องการหยุดชั่วคราว การตั้งค่าการผสานรวมจะไม่แสดงสถานะหยุดชั่วคราว อีเมลนี้จึงเป็นการแจ้งเตือนเพียงช่องทางเดียว

event จะถือว่าได้รับแล้วเมื่อปลายทางของคุณส่งรหัสการตอบกลับ 2xx ความล้มเหลวบางส่วนจะไม่ทำให้การผสานรวมหยุดชั่วคราว: event ใดก็ตามที่ได้รับจะเริ่มนับ 24 ชั่วโมงใหม่ การผสานรวมที่ใช้การส่งแบบ gRPC จะไม่ถูกหยุดชั่วคราว

หากต้องการกลับมาสตรีมต่อ:

1. ตรวจสอบให้แน่ใจว่าปลายทางของคุณเข้าถึงได้และส่งรหัสการตอบกลับ 2xx
2. ไปที่ Settings > 3rd party Integrations ค้นหา Event streaming integration และคลิก Configure
3. คลิก Apply คุณไม่จำเป็นต้องเปลี่ยนการตั้งค่าใดๆ การสตรีมจะกลับมาทำงานภายใน 15 นาที

คุณจะทราบได้อย่างไรว่าการผสานรวมทำงานอยู่

คุณจะเริ่มได้รับคำขอจาก Pushwoosh ที่ endpoint ที่คุณกำหนดค่าไว้