แชร์ผ่าน

การลงทะเบียนอุปกรณ์การแจ้งเตือนแบบพุชสำหรับนักพัฒนาแอปพลิเคชัน

  • บทความ

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับวิธีการโดยรวมในการตั้งค่าการแจ้งเตือนแบบพุชใน Customer Insights - Journeys โปรดไปที่ ภาพรวมการตั้งค่าการแจ้งเตือนแบบพุช

หากต้องการเปิดใช้งานการแจ้งเตือนแบบพุชใน Customer Insights - Journeys คุณต้องทำตามขั้นตอนต่อไปนี้:

  1. การกำหนดค่าแอปพลิเคชันการแจ้งเตือนแบบพุช
  2. การแมปผู้ใช้สำหรับการแจ้งเตือนแบบพุช
  3. การลงทะเบียนอุปกรณ์สำหรับการแจ้งเตือนแบบพุช
  4. การรับการแจ้งเตือนแบบพุชบนอุปกรณ์เคลื่อนที่
  5. การรายงานการโต้ตอบสำหรับการแจ้งเตือนแบบพุช

แผนผังนี้อธิบายสองขั้นตอนที่จำเป็นในการลงทะเบียนอุปกรณ์และผู้ใช้ภายใน 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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "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

สำคัญ

มีสาเหตุที่เป็นไปได้สามประการที่ทำให้สถานะสามารถติดอยู่ในสถานะ "รอดำเนินการ":

  1. คำขอการลงทะเบียนอุปกรณ์ดั้งเดิมมีโทเค็น API ที่ไม่ถูกต้อง เพื่อป้องกันไม่ให้ผู้ไม่ประสงค์ดีทำการโจมตี DoS ต่อสภาพแวดล้อมโดยการเรียก "ลงทะเบียนอุปกรณ์" และสร้างการควบคุมที่ไม่จำกัด การดำเนินการดังกล่าวจะไม่สร้างการจัดเก็บประวัติการลงทะเบียน ดังนั้นจึงไม่มีข้อมูลในการตรวจสอบความสำเร็จ
  2. CRM อยู่ในสถานะควบคุมปริมาณเป็นเวลาหลายชั่วโมง ทำให้การดำเนินการอัปเดตสถานะล้มเหลวในการดำเนินการหลังจากลองใหม่หลายครั้ง
  3. คำขอลงทะเบียนอุปกรณ์ถูกสร้างโดยไม่มีส่วนหัว 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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

ส่งคืน: 202 หากคำขอที่ระบุถูกต้อง 400 หากคำขอไม่ถูกต้อง

คำนิยาม
ชื่อ คำอธิบาย
MobileAppId ตัวระบุของแอปพลิเคชันสำหรับอุปกรณ์เคลื่อนที่ที่กำหนดค่าไว้ Customer Insights - Journeys
ApiToken โทเค็น API ของคุณเพื่ออนุญาตคำขอ
UserId ตัวระบุผู้ใช้ของผู้ติดต่อ ลูกค้าเป้าหมาย หรือโปรไฟล์ Customer Insights - Data จาก Customer Insights - Journeys
DeviceToken ตัวระบุโทเค็นอุปกรณ์เฉพาะที่สร้างโดยแอปพลิเคชัน