API ลงทะเบียนอุปกรณ์

API ลงทะเบียนอุปกรณ์มีอินเทอร์เฟซฝั่งเซิร์ฟเวอร์สำหรับลงทะเบียน Token อุปกรณ์และรับ registration_id ใน AppPush

รับ registration_id ผ่าน Token

API นี้ช่วยให้เซิร์ฟเวอร์ลงทะเบียนผู้ใช้ AppPush ด้วย FCM Tokens หรือ APNs Device Tokens และรับ registration_id ที่ EngageLab สร้างขึ้น หลังจากได้รับ registration_id แล้ว สามารถนำไปใช้ส่ง Push ไปยังผู้ใช้ที่ระบุ รวมถึงใช้กับ APIs ที่เกี่ยวข้องกับอุปกรณ์ เช่น แท็กและนามแฝง

ข้อจำกัดการใช้งาน

• แต่ละคำขอรองรับการลงทะเบียน Tokens ตั้งแต่ 1–500 รายการ
• หนึ่งคำขอต้องมี Tokens จากแพลตฟอร์มเดียวเท่านั้น ได้แก่ ชุด FCM Tokens หรือชุด APNs Device Tokens ไม่รองรับการผสม Tokens ของ FCM และ APNs ในคำขอเดียวกัน
• คำขอซ้ำที่ใช้แอปพลิเคชัน แพลตฟอร์ม และ Token เดียวกันเป็นแบบ idempotent ระบบจะไม่สร้างผู้ใช้ซ้ำและจะส่งคืน registration_id เดิม
• ผลลัพธ์จะเรียงตามลำดับเดียวกับ Tokens ในคำขอ

Endpoint

              
              POST /v4/devices/token/registration_id

            

URL คำขอแบบเต็มประกอบด้วย Base URL ของศูนย์ข้อมูลที่แอปพลิเคชันสังกัดและพาธด้านบน สำหรับที่อยู่ศูนย์ข้อมูลและวิธีการยืนยันตัวตน โปรดดู ภาพรวม REST API

ส่วนหัวคำขอ

              
              Content-Type: application/json
Accept: application/json
Authorization: Basic base64_auth_string

            

พารามิเตอร์คำขอ

กฎรูปแบบ Token

• FCM Token: ต้องเป็นสตริงที่ไม่ว่างและยาวไม่เกิน 400 อักขระ อนุญาตเฉพาะอักขระ ASCII ที่พิมพ์ได้ (0x21–0x7E) ห้ามมีช่องว่าง ขึ้นบรรทัดใหม่ หรือช่องว่างที่ต้นและท้าย
• APNs Device Token: ต้องเป็นสตริงเลขฐานสิบหกที่ไม่ว่าง มีจำนวนอักขระเป็นเลขคู่ และยาวไม่เกิน 400 อักขระ อนุญาตเฉพาะ 0-9, a-f และ A-F ห้ามมีช่องว่าง วงเล็บมุม หรือตัวคั่นอื่น

API นี้ตรวจสอบเฉพาะรูปแบบ Token และไม่สามารถยืนยันได้ว่า Token ยังใช้งานได้จริงหรือไม่ ความถูกต้องของ Token ให้พิจารณาจากผลการส่ง Push ของ FCM หรือ APNs

ตัวอย่างคำขอ Android (FCM)

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "android",
    "tokens": [
      "fcm_token_1",
      "fcm_token_2"
    ]
  }'

            

ตัวอย่างคำขอ iOS (APNs)

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "ios",
    "tokens": [
      "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ],
    "apns_production": true
  }'

            

พารามิเตอร์การตอบกลับ

รหัสผลลัพธ์รายรายการ:

ตัวอย่างการตอบกลับสำเร็จ

เมื่อลงทะเบียนครั้งแรก is_new จะเป็น true:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": true,
      "code": 0
    },
    {
      "token": "fcm_token_2",
      "registration_id": "13065ffa4e1a6cc91c4",
      "is_new": true,
      "code": 0
    }
  ]
}

            

เมื่อส่ง Token ที่ลงทะเบียนแล้วอีกครั้ง ระบบจะส่งคืน registration_id เดิม และ is_new จะเป็น false:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    }
  ]
}

            

ตัวอย่าง Token รายการเดียวล้มเหลว

หาก Token รายการใดในชุดมีรูปแบบไม่ถูกต้องหรือลงทะเบียนล้มเหลว รายการนั้นจะส่งคืนข้อผิดพลาดผ่าน code และ message ขณะที่ Tokens อื่นยังประมวลผลได้ตามปกติ ตัวอย่างต่อไปนี้แสดง Token ว่างที่ไม่ผ่านการตรวจสอบรูปแบบ:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    },
    {
      "token": "",
      "is_new": false,
      "code": 21003,
      "message": "invalid fcm token format"
    }
  ]
}

            

ตัวอย่างคำขอล้มเหลว

หากพารามิเตอร์โดยรวมของคำขอไม่ถูกต้อง API จะส่งคืน HTTP 400 ตัวอย่างเช่น คำขอ iOS ที่ไม่ได้ส่ง apns_production จะได้รับ:

              
              {
  "error": {
    "code": 21003,
    "message": "apns_production is required for ios"
  }
}

            

ข้อผิดพลาดของคำขอที่พบบ่อย:

• platform ไม่ใช่ android หรือ ios;
• tokens ว่างหรือมีมากกว่า 500 รายการ;
• คำขอ Android ส่ง apns_production;
• คำขอ iOS ไม่ได้ส่ง apns_production

การตอบกลับของ API

รหัสสถานะ HTTP

ดู รหัสสถานะ HTTP

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

ตารางต่อไปนี้แสดงรหัสข้อผิดพลาดระดับคำขอ ในคำขอแบบ Batch ข้อผิดพลาดของ Token แต่ละรายการจะส่งคืนผ่าน results[].code และ results[].message โดยไม่กระทบการประมวลผล Tokens อื่น