การลงทะเบียนอุปกรณ์การแจ้งเตือนแบบพุชสำหรับนักพัฒนาแอปพลิเคชัน
หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับวิธีการโดยรวมในการตั้งค่าการแจ้งเตือนแบบพุชใน Customer Insights - Journeys โปรดไปที่ ภาพรวมการตั้งค่าการแจ้งเตือนแบบพุช
หากต้องการเปิดใช้งานการแจ้งเตือนแบบพุชใน Customer Insights - Journeys คุณต้องทำตามขั้นตอนต่อไปนี้:
- การกำหนดค่าแอปพลิเคชันการแจ้งเตือนแบบพุช
- การแมปผู้ใช้สำหรับการแจ้งเตือนแบบพุช
- การลงทะเบียนอุปกรณ์สำหรับการแจ้งเตือนแบบพุช
- การรับการแจ้งเตือนแบบพุชบนอุปกรณ์เคลื่อนที่
- การรายงานการโต้ตอบสำหรับการแจ้งเตือนแบบพุช
แผนผังนี้อธิบายสองขั้นตอนที่จำเป็นในการลงทะเบียนอุปกรณ์และผู้ใช้ภายใน Customer Insights - Journeys
การลงทะเบียนอุปกรณ์
ในการกำหนดค่าแอปสำหรับอุปกรณ์เคลื่อนที่ให้เสร็จสมบูรณ์ นักพัฒนาต้องลงทะเบียนอุปกรณ์ในเซิร์ฟเวอร์ คุณควรมีโทเค็นอุปกรณ์, ID ผู้ใช้จาก Customer Insights - Journeys (ID ผู้ติดต่อ, ID ลูกค้าเป้าหมาย, ID โปรไฟล์ Customer Insights - Data) และ ID แอปพลิเคชันสำหรับอุปกรณ์เคลื่อนที่จาก Customer Insights - Journeys
เมื่อเรียกคำขอการลงทะเบียนอุปกรณ์สำเร็จ จะมีการตอบสนอง 202 การตอบสนอง 202 บ่งชี้ว่าคำขอได้รับการยอมรับเท่านั้น เพื่อยืนยันคำขอที่สำเร็จ คุณต้องตรวจสอบสถานะโดยใช้ webhook หรือการเรียกตำแหน่งข้อมูลสถานะโดยตรง
API
การลงทะเบียนอุปกรณ์ (รายการเดียว)
การร้องขอทาง HTTP ตัวอย่าง (iOS):
POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices
{
"MobileAppId": "00000000-0000-0000-0000-000000000000",
"UserId": "00000000-0000-0000-0000-000000000000",
"ApiToken": "%API_TOKEN%",
"ApnsDeviceToken": "%APNS_TOKEN%"
}
การร้องขอทาง HTTP ตัวอย่าง (Android):
POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices
{
"MobileAppId": "00000000-0000-0000-0000-000000000000",
"UserId": "00000000-0000-0000-0000-000000000000",
"ApiToken": "%API_TOKEN%",
"FcmDeviceToken": "%FCM_TOKEN%"
}
ส่วนหัว:
- การลงทะเบียน x-ms-track: เมื่อเป็นจริง ข้อมูลเกี่ยวกับความสำเร็จ/ความล้มเหลวในการลงทะเบียนจะถูกจัดเก็บและสามารถใช้งานผ่าน API สถานะการลงทะเบียน
- x-ms-callback-url: เมื่อไม่ว่างเปล่า การลงทะเบียนอุปกรณ์ล้มเหลวหรือสำเร็จจะทริกเกอร์ webhook คำขอ POST
- x-ms-callback-url-headers: มี JSON ที่ต่อเนื่องกันของพจนานุกรมแบบสตริงต่อสตริง ซึ่งแสดงถึงส่วนหัวที่ส่งผ่านสำหรับคำขอ webhook ใช้เมื่อมีการกำหนด x-ms-callback-url เท่านั้น
ส่งคืน: 202 หากคำขอที่ระบุถูกต้อง 400 หากคำขอไม่ถูกต้อง
เนื้อความการตอบสนอง:
เมื่อ x-ms-track-registration เป็นจริง:
{
"RegistrationRequestId": "%GUID%"
}
ไม่เช่นนั้น เนื้อความจะว่างเปล่า
คำนิยาม
| ชื่อ | คำอธิบาย |
|---|---|
| MobileAppId | ตัวระบุของแอปพลิเคชันสำหรับอุปกรณ์เคลื่อนที่ที่กำหนดค่าไว้ Customer Insights - Journeys |
| UserId | ตัวระบุผู้ใช้ของผู้ติดต่อ ลูกค้าเป้าหมาย หรือโปรไฟล์ Customer Insights - Data จาก Customer Insights - Journeys |
| ApiToken | โทเค็น API ของคุณเพื่ออนุญาตคำขอ |
| ApnsDeviceToken | ตัวระบุโทเค็นอุปกรณ์เฉพาะที่สร้างโดยแอปพลิเคชัน iOS โดยจะส่งไปยังอุปกรณ์ iOS เท่านั้น |
| FcmDeviceToken | ตัวระบุโทเค็นอุปกรณ์เฉพาะที่สร้างโดยแอปพลิเคชัน Android โดยจะส่งไปยังอุปกรณ์ Android เท่านั้น |
การลงทะเบียนอุปกรณ์ (หลายรายการ)
เนื้อความของการลงทะเบียนชุดงานประกอบด้วยอาร์เรย์สูงสุด 100 ออบเจ็กต์ที่แสดงถึงคำขอการลงทะเบียนอุปกรณ์
การร้องขอทาง HTTP ตัวอย่าง (iOS):
POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch
[
{
"MobileAppId": "00000000-0000-0000-0000-000000000000",
"UserId": "00000000-0000-0000-0000-000000000000",
"ApiToken": "%API_TOKEN%",
"ApnsDeviceToken": "%APNS_TOKEN%"
},
{
"MobileAppId": "00000000-0000-0000-0000-000000000000",
"UserId": "00000000-0000-0000-0000-000000000000",
"ApiToken": "%API_TOKEN%",
"ApnsDeviceToken": "%APNS_TOKEN%"
}
]
การร้องขอทาง HTTP ตัวอย่าง (Android):
POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch
[
{
"MobileAppId": "00000000-0000-0000-0000-000000000000",
"UserId": "00000000-0000-0000-0000-000000000000",
"ApiToken": "%API_TOKEN%",
"FcmDeviceToken": "%FCM_TOKEN%"
},
{
"MobileAppId": "00000000-0000-0000-0000-000000000000",
"UserId": "00000000-0000-0000-0000-000000000000",
"ApiToken": "%API_TOKEN%",
"FcmDeviceToken": "%FCM_TOKEN%"
}
]
ส่วนหัว:
- การลงทะเบียน x-ms-track: เมื่อเป็นจริง ข้อมูลเกี่ยวกับความสำเร็จหรือความล้มเหลวในการลงทะเบียนจะถูกจัดเก็บและสามารถใช้งานผ่าน API สถานะการลงทะเบียน
- x-ms-callback-url: เมื่อไม่ว่างเปล่า การลงทะเบียนอุปกรณ์ล้มเหลวหรือสำเร็จจะทริกเกอร์ webhook คำขอ
POST - x-ms-callback-url-headers: มี JSON ที่ต่อเนื่องกันของพจนานุกรมแบบสตริงต่อสตริง ซึ่งแสดงถึงส่วนหัวที่ส่งผ่านสำหรับคำขอ webhook ใช้เฉพาะเมื่อ
x-ms-callback-urlถูกกำหนดไว้
ส่งคืน: 202 หากคำขอที่ระบุถูกต้อง 400 หากคำขอไม่ถูกต้อง
เนื้อความการตอบสนอง:
เมื่อ x-ms-track-registration เป็นจริง: อาร์เรย์ของรายการ แต่ละรายการเรียงลำดับสอดคล้องกับลำดับจากอาร์เรย์เนื้อความคำขอ
[
{
"RegistrationRequestId": "%REG_REQUEST_ID%"
},
{
"RegistrationRequestId": "%REG_REQUEST_ID%"
}
]
ไม่เช่นนั้น เนื้อความจะว่างเปล่า
สถานะของการลงทะเบียนอุปกรณ์
POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/status/
เนื้อหาของคำขอ:
{
"RegistrationRequestIds": [
"%REG_REQUEST_ID%"
],
"MobileAppId": "%MOBILE_APP_ID%",
"ApiToken": "%API_TOKEN%"
}
ส่งคืน: 200 หากคำขอที่ระบุถูกต้อง 400 หากคำขอไม่ถูกต้อง
เนื้อความการตอบสนอง - อาร์เรย์ของรายการ:
[
{
"Status": "Pending|Success|Failed",
"FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
},
{
"Status": "Pending|Success|Failed",
"FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
}
]
แต่ละรายการลำดับสอดคล้องกับลำดับจากอาร์เรย์ RegistrationRequestIds
คำนิยาม
| ชื่อ | คำอธิบาย |
|---|---|
| RegistrationRequestIds | อาร์เรย์ของการร้องขอการลงทะเบียนเฉพาะรายการ ค่าที่ได้มาจากการตอบสนองของการเรียกการลงทะเบียน จะมีให้เฉพาะเมื่อมีการใช้ส่วนหัว x-ms-track-registration ในการลงทะเบียนเท่านั้น |
| MobileAppId | ตัวระบุของแอปพลิเคชันสำหรับอุปกรณ์เคลื่อนที่ที่กำหนดค่าไว้ Customer Insights - Journeys |
| UserId | ตัวระบุผู้ใช้ของผู้ติดต่อ ลูกค้าเป้าหมาย หรือโปรไฟล์ Customer Insights - Data จาก Customer Insights - Journeys |
สำคัญ
มีสาเหตุที่เป็นไปได้สามประการที่ทำให้สถานะสามารถติดอยู่ในสถานะ "รอดำเนินการ":
- คำขอการลงทะเบียนอุปกรณ์ดั้งเดิมมีโทเค็น API ที่ไม่ถูกต้อง เพื่อป้องกันไม่ให้ผู้ไม่ประสงค์ดีทำการโจมตี DoS ต่อสภาพแวดล้อมโดยการเรียก "ลงทะเบียนอุปกรณ์" และสร้างการควบคุมที่ไม่จำกัด การดำเนินการดังกล่าวจะไม่สร้างการจัดเก็บประวัติการลงทะเบียน ดังนั้นจึงไม่มีข้อมูลในการตรวจสอบความสำเร็จ
- CRM อยู่ในสถานะควบคุมปริมาณเป็นเวลาหลายชั่วโมง ทำให้การดำเนินการอัปเดตสถานะล้มเหลวในการดำเนินการหลังจากลองใหม่หลายครั้ง
- คำขอลงทะเบียนอุปกรณ์ถูกสร้างโดยไม่มีส่วนหัว x-ms-track-registration ที่ให้มา
webhook สถานะการลงทะเบียนอุปกรณ์
ถ้า x-ms-สถานะ-โทรกลับ-url ระบุ URL เมื่อการลงทะเบียนอุปกรณ์สำเร็จหรือล้มเหลว Customer Insights - Journeys จะเข้าถึงค่าของส่วนหัว
POST ไปยัง URL ที่ให้ไว้ภายในส่วนหัว x-ms-status-callback-url ของคำขอลงทะเบียนอุปกรณ์
เนื้อความ:
{
"Status": "Success|Failed",
"Signature": "%SIGNATURE%",
"FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid"
}
เคล็ดลับ
ลายเซ็นคือแฮช HMACSHA256 ของ URL ติดต่อกลับที่คำนวณโดยใช้โทเค็น API เป็นคีย์ ใช้ค่าเพื่อยืนยันว่า Customer Insights - Journeys ทำการเรียก แฮช URL ติดต่อกลับด้วยโทเค็น API ที่ฝั่งของ webhook โดยใช้อัลกอริทึมเดียวกัน และเปรียบเทียบค่าต่างๆ
หมายเหตุ
ความพยายามที่จะส่งคำขอเกิดขึ้นเพียงครั้งเดียว ความล้มเหลวในการดำเนินการตามคำขอจะทำให้การแจ้งเตือนสูญหาย ชนิดความล้มเหลว ได้แก่ URL ติดต่อกลับที่ไม่ถูกต้อง REST API หมดเวลาการเรียก หรือรหัสสถานะการตอบสนองที่ไม่คาดคิด
ส่งคืน: 202 หากคำขอที่ระบุถูกต้อง 400 หากคำขอไม่ถูกต้อง
เนื้อความที่คาดไว้: เนื้อความว่างเปล่า
การล้างข้อมูลอุปกรณ์ (รายการเดียว)
สิ่งสำคัญคือต้องลบอุปกรณ์ที่ไม่ถูกต้องออกจากฐานข้อมูลเพื่อให้แน่ใจว่าสามารถส่งข้อความได้อย่างมีประสิทธิภาพ ใช้วิธีการต่อไปนี้เพื่อลบชุดรวมอุปกรณ์ ผู้ใช้ และแอปพลิเคชันเก่าออกจากตารางอุปกรณ์
POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup
{
"MobileAppId": "00000000-0000-0000-0000-000000000000",
"ApiToken": "%API_TOKEN%",
"UserId": "00000000-0000-0000-0000-000000000000",
"DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}
ส่งคืน: 202 หากคำขอที่ระบุถูกต้อง 400 หากคำขอไม่ถูกต้อง
คำนิยาม
| ชื่อ | คำอธิบาย |
|---|---|
| MobileAppId | ตัวระบุของแอปพลิเคชันสำหรับอุปกรณ์เคลื่อนที่ที่กำหนดค่าไว้ Customer Insights - Journeys |
| ApiToken | โทเค็น API ของคุณเพื่ออนุญาตคำขอ |
| UserId | ตัวระบุผู้ใช้ของผู้ติดต่อ ลูกค้าเป้าหมาย หรือโปรไฟล์ Customer Insights - Data จาก Customer Insights - Journeys |
| DeviceToken | ตัวระบุโทเค็นอุปกรณ์เฉพาะที่สร้างโดยแอปพลิเคชัน |
การล้างข้อมูลอุปกรณ์ (หลายรายการ)
สิ่งสำคัญคือต้องลบอุปกรณ์ที่ไม่ถูกต้องออกจากฐานข้อมูลเพื่อให้แน่ใจว่าสามารถส่งข้อความได้อย่างมีประสิทธิภาพ ใช้วิธีการต่อไปนี้เพื่อลบชุดรวมอุปกรณ์ ผู้ใช้ และแอปพลิเคชันเก่าออกจากตารางอุปกรณ์
POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup/batch
{
"MobileAppId": "00000000-0000-0000-0000-000000000000",
"ApiToken": "%API_TOKEN%",
"UserId": "00000000-0000-0000-0000-000000000000",
"DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}
ส่งคืน: 202 หากคำขอที่ระบุถูกต้อง 400 หากคำขอไม่ถูกต้อง
คำนิยาม
| ชื่อ | คำอธิบาย |
|---|---|
| MobileAppId | ตัวระบุของแอปพลิเคชันสำหรับอุปกรณ์เคลื่อนที่ที่กำหนดค่าไว้ Customer Insights - Journeys |
| ApiToken | โทเค็น API ของคุณเพื่ออนุญาตคำขอ |
| UserId | ตัวระบุผู้ใช้ของผู้ติดต่อ ลูกค้าเป้าหมาย หรือโปรไฟล์ Customer Insights - Data จาก Customer Insights - Journeys |
| DeviceToken | ตัวระบุโทเค็นอุปกรณ์เฉพาะที่สร้างโดยแอปพลิเคชัน |