API แท็กและนามแฝง

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

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

สำหรับรายละเอียดเกี่ยวกับแท็กและนามแฝง โปรดดูเอกสาร API ของแพลตฟอร์มไคลเอนต์ที่เกี่ยวข้อง

• web - tag, alias

ข้อจำกัดและกฎสำหรับการใช้งาน TAG

• ขีดจำกัดจำนวน TAG: ภายใต้ AppKey เดียว สามารถสร้าง Tags ได้สูงสุด 100,000 รายการ
• ขีดจำกัดความยาวของ TAG: ความยาวสูงสุดของแต่ละ Tag คือ 40 ไบต์ อักขระที่ใช้ได้ประกอบด้วยตัวอักษร (แยกตัวพิมพ์เล็กและใหญ่) ตัวเลข ขีดล่าง และอักขระภาษาจีน
• ขีดจำกัดการผูก TAG ของอุปกรณ์: แต่ละอุปกรณ์สามารถผูกกับ Tags ได้สูงสุด 100 รายการ
• ขีดจำกัดจำนวนอุปกรณ์: ภายใต้ Tag เดียว สามารถเพิ่มอุปกรณ์ได้สูงสุด 100,000 เครื่อง

หากคุณเป็นผู้ใช้แพ็กเกจแบบชำระเงิน และต้องการปรับขีดจำกัดการใช้งานสำหรับ AppKey แบบชำระเงิน โปรดติดต่อทีมขายของเราที่ Sales@engagelab.com

ข้อจำกัดและกฎสำหรับการใช้งาน alias

• ความสัมพันธ์การแมประหว่างอุปกรณ์และ alias: alias หนึ่งรายการสามารถสอดคล้องกับอุปกรณ์ได้เพียงหนึ่งเครื่องเท่านั้น และไม่สามารถสอดคล้องกับหลายอุปกรณ์ได้ ในทำนองเดียวกัน แต่ละอุปกรณ์สามารถแมปกับ alias ได้เพียงหนึ่งรายการภายในขอบเขตของ AppKey และไม่สามารถแมปกับหลาย alias ได้
• ขีดจำกัดจำนวน alias: ภายใต้ AppKey เดียว สามารถสร้าง aliases ได้สูงสุด 100,000 รายการ
• ขีดจำกัดความยาวของ alias: ความยาวสูงสุดของแต่ละ alias คือ 40 ไบต์ อักขระที่ใช้ได้ประกอบด้วยตัวอักษร (แยกตัวพิมพ์เล็กและใหญ่) ตัวเลข ขีดล่าง และอักขระภาษาจีน

หากคุณเป็นผู้ใช้แพ็กเกจแบบชำระเงิน และต้องการปรับขีดจำกัดการใช้งานสำหรับ AppKey แบบชำระเงิน โปรดติดต่อทีมขายของเราที่ Sales@engagelab.com

ภาพรวม API

Device API ใช้สำหรับค้นหา ตั้งค่า อัปเดต และลบข้อมูลแท็กและนามแฝงของอุปกรณ์บนฝั่งเซิร์ฟเวอร์

ประกอบด้วย API 3 กลุ่ม ได้แก่ device, tag และ alias โดยมีรายละเอียดดังนี้:

• device ใช้สำหรับค้นหา/ตั้งค่าคุณสมบัติต่าง ๆ ของอุปกรณ์ รวมถึง tags และ alias
• tag ใช้สำหรับค้นหา/ตั้งค่า/ลบ tags ของอุปกรณ์
• alias ใช้สำหรับค้นหา/ตั้งค่า/ลบ aliases ของอุปกรณ์

ข้อมูลสำคัญอีกส่วนหนึ่งที่คุณต้องทราบคือ registration ID:

ค่า registration_id ของอุปกรณ์จะได้รับหลังจากรวมการทำงานฝั่งไคลเอนต์แล้ว สำหรับรายละเอียด โปรดดูเอกสาร Web API

ฝั่งเซิร์ฟเวอร์ไม่มี API สำหรับรับค่า registration_id ของอุปกรณ์ นักพัฒนาจำเป็นต้องรับ registration ID จากฝั่งไคลเอนต์และอัปโหลดไปยังเซิร์ฟเวอร์ของนักพัฒนาเพื่อจัดเก็บ

ค้นหาจำนวนแท็กภายใต้ AppKey

Endpoint

              
              GET /v4/tags_count

            

ตัวอย่างคำขอ

Request Headers

              
              GET /v4/tags_count
Authorization: Basic (base64 auth string)
Accept: application/json

            

ตัวอย่างคำขอ

              
              curl -X GET http://127.0.0.1/v4/tags_count?tags=tag1&tags=tag2&platform=ios -u "appKey:appSecret"

            

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

• tags: ค้นหาสตริง tag ที่ระบุ จำเป็น สามารถค้นหาได้สูงสุด 1000 tags ต่อหนึ่งคำขอ (tags=tag1&tags=tag2&tags=tag3)
• platform: ค้นหาแพลตฟอร์มที่ระบุ จำเป็น ค่าที่ใช้ได้คือ android, ios, hmos และ web ไม่อนุญาตให้ใช้ค่าอื่น

ตัวอย่างการตอบกลับ

• เมื่อคำขอสำเร็จ จะส่งคืนออบเจ็กต์ JSON ที่มีฟิลด์ tagsCount ซึ่งเป็นชุดของคู่คีย์-ค่า โดยคีย์คือชื่อแท็ก และค่าคือจำนวนภายใต้แท็กนั้น
• หากคำขอล้มเหลว จะส่งคืนออบเจ็กต์ JSON ที่มีข้อมูลข้อผิดพลาด ฟิลด์ code ระบุรหัสข้อผิดพลาด และฟิลด์ message ระบุข้อความข้อผิดพลาด

การตอบกลับเมื่อสำเร็จ

              
              {
  "tagsCount": {
    "tag1": 0,
    "tag2": 1,
    "tag3": 2
  }
}

            

การตอบกลับเมื่อไม่สำเร็จ

              
              {
  "error": {
    "code": 21008,
    "message": "app_key is not a 24 size string or does not exist"
  }
}

            

ค้นหา Alias และ Tags ของอุปกรณ์

• ดึงคุณสมบัติทั้งหมดของอุปกรณ์ปัจจุบัน รวมถึง tags และ alias

Endpoint

              
              GET /v4/devices/{registration_id}

            

ตัวอย่างคำขอ

Request Headers

              
              GET /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json

            

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

• registration_id: จำเป็น registration_id ของอุปกรณ์

ตัวอย่างการตอบกลับ

การตอบกลับเมื่อสำเร็จ

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

ข้อมูลการตอบกลับ

              
              {
  "tags": ["tag1", "tag2"],
  "alias": "alias1"
}

            

• หากไม่พบรายการสถิติ จะเป็น null มิฉะนั้นจะเป็นค่าของรายการสถิตินั้น

ตั้งค่า Alias และ Tags ของอุปกรณ์

• อัปเดตคุณสมบัติที่ระบุของอุปกรณ์ปัจจุบัน ขณะนี้รองรับ tags และ alias

Endpoint

              
              POST /v4/devices/{registration_id}

            

ตัวอย่างคำขอ

Request Headers

              
              POST /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json

            

ข้อมูลคำขอ

              
              {
  "tags": {
    "add": ["tag1", "tag2"],
    "remove": ["tag3", "tag4"]
  },
  "alias": "alias1"
}

            

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

• registration_id: จำเป็น registration_id ของอุปกรณ์
• tags: รองรับ add, remove หรือสตริงว่าง เมื่อพารามิเตอร์ tags เป็นสตริงว่าง หมายความว่าจะล้าง tags ทั้งหมด โดย add/remove ใช้เพื่อเพิ่มหรือลบ tags ที่ระบุ
• alias: อัปเดตคุณสมบัติ alias ของอุปกรณ์ เมื่อ alias เป็นสตริงว่าง alias ของอุปกรณ์ที่ระบุจะถูกลบ

ตัวอย่างการตอบกลับ

การตอบกลับเมื่อสำเร็จ

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

ข้อมูลการตอบกลับ

              
              success

            

การตอบกลับเมื่อไม่สำเร็จ

              
              {
  "error": {
    "code": 27002,
    "message": "unknown error"
  }
}

            

ค้นหารายการแท็ก

• ดึงรายการ tags ทั้งหมดในแอปพลิเคชันปัจจุบัน

Endpoint

              
              GET /v4/tags/

            

ตัวอย่างคำขอ

Request Headers

              
              GET /v4/tags/
Authorization: Basic (base64 auth string)
Accept: application/json

            

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

• ไม่มี

ตัวอย่างการตอบกลับ

การตอบกลับเมื่อสำเร็จ

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

ข้อมูลการตอบกลับ

              
              {
  "tags": ["tag1", "tag2"]
}

            

• หากไม่พบรายการสถิติ จะเป็น null มิฉะนั้นจะเป็นค่าของรายการสถิตินั้น

ค้นหาความสัมพันธ์การผูกระหว่างอุปกรณ์กับแท็ก

• ค้นหาว่าอุปกรณ์เป็นสมาชิกของแท็กหรือไม่

Endpoint

              
              GET /v4/tags/{tag_value}/registration_ids/{registration_id}

            

ตัวอย่างคำขอ

Request Headers

              
              GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
Authorization: Basic (base64 auth string)
Accept: application/json

            

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

• tag_value: จำเป็น แท็กที่ต้องการค้นหา
• registration_id: จำเป็น registration_id ของอุปกรณ์

ตัวอย่างการตอบกลับ

การตอบกลับเมื่อสำเร็จ

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

ข้อมูลการตอบกลับ

              
              {"result": true}

            

อัปเดตแท็ก

• เพิ่มหรือลบอุปกรณ์สำหรับแท็ก

Endpoint

              
              POST /v4/tags/{tag_value}

            

ตัวอย่างคำขอ

Request Headers

              
              POST /v4/tags/{tag_value}
Authorization: Basic (base64 auth string)
Accept: application/json

            

ข้อมูลคำขอ

              
              {
  "registration_ids": {
    "add": ["registration_id1", "registration_id2"],
    "remove": ["registration_id1", "registration_id2"]
  }
}

            

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

• tag_value: จำเป็น แท็กที่ต้องการค้นหา
• action: ประเภทการดำเนินการ มี 2 ตัวเลือก: "add" และ "remove" ซึ่งระบุว่าคำขอนี้เป็นการเพิ่มหรือลบ
• registration_ids: ค่า registration_id ของอุปกรณ์ที่จะเพิ่มหรือลบ
• add/remove: รองรับได้สูงสุดรายการละ 1000 รายการ

ตัวอย่างการตอบกลับ

การตอบกลับเมื่อสำเร็จ

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

ข้อมูลการตอบกลับ

              
              success

            

การตอบกลับเมื่อไม่สำเร็จ

              
              {
  "error": {
    "code": 27005,
    "message": "registration id is illegal",
    "data": "{\"invalid_regids\":[\"18071adc021ff8df80\",\"100d85592955c1f1058\"]}"
  }
}

            

ลบแท็ก

ลบแท็กและความเชื่อมโยงระหว่างแท็กกับอุปกรณ์

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

ตัวอย่างคำขอ

Request Headers

              
              DELETE /v4/tags/{tag_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json

            

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

• tag_value: จำเป็น แท็กที่ต้องการค้นหา
• platform: ไม่บังคับ หากละไว้ ค่าดีฟอลต์คือทุกแพลตฟอร์ม

ตัวอย่างการตอบกลับ

การตอบกลับเมื่อสำเร็จ

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

ข้อมูลการตอบกลับ

              
              success

            

การตอบกลับเมื่อไม่สำเร็จ

              
              {
  "error": {
    "code": 27002,
    "message": "unknown error"
  }
}

            

ค้นหา Alias (ความสัมพันธ์การผูกกับอุปกรณ์)

              
              GET /v4/aliases/{alias_value}
Get the device under the specified alias.

            

ค้นหา Alias

• ดึงอุปกรณ์ภายใต้ alias ที่ระบุ

Endpoint

              
              GET /v4/aliases/{alias_value}

            

ตัวอย่างคำขอ

Request Headers

              
              GET /v4/aliases/{alias_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json

            

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

• alias_value: จำเป็น alias ที่ต้องการค้นหา
• platform: ไม่บังคับ หากละไว้ ค่าดีฟอลต์คือทุกแพลตฟอร์ม

ตัวอย่างการตอบกลับ

การตอบกลับเมื่อสำเร็จ

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

ข้อมูลการตอบกลับ

              
              {
  "registration_ids": ["registration_id1", "registration_id2"]
}

            

• หากไม่พบรายการสถิติ จะเป็น null มิฉะนั้นจะเป็นค่าของรายการสถิตินั้น

ลบ Alias

ลบ alias และความสัมพันธ์การผูกระหว่าง alias กับอุปกรณ์

              
              DELETE /v4/aliases/{alias_value}

            

ตัวอย่างคำขอ

Request Headers

              
              DELETE /v4/aliases/{alias_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json

            

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

• alias_value: จำเป็น alias ที่ต้องการลบ
• platform: ไม่บังคับ หากละไว้ ค่าดีฟอลต์คือทุกแพลตฟอร์ม

ตัวอย่างการตอบกลับ

• สำเร็จ

              
              success

            

• ไม่สำเร็จ

              
              {
  "error": {
    "code": 27002,
    "message": "unknown error"
  }
}

            

รับสถานะออนไลน์ของผู้ใช้

Endpoint

              
              POST /v4/devices/status/

            

ตัวอย่างคำขอ

Request Headers

              
              POST /v4/devices/status/
Authorization: Basic (base64 auth string)
Accept: application/json

            

ข้อมูลคำขอ

              
              {
  "registration_ids": [
    "010b81b3582",
    "0207870f1b8",
    "0207870f9b8"
  ]
}

            

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

• registration_ids: ค่า registration_id ของผู้ใช้ที่ต้องการสถานะออนไลน์ รองรับ registration_id ได้สูงสุด 1000 ค่าในการค้นหาหนึ่งครั้ง
• API นี้สามารถเรียกใช้ได้เฉพาะกับ AppKey ที่ได้สมัครและเปิดใช้งานบริการนี้แล้วเท่านั้น

ตัวอย่างการตอบกลับ

การตอบกลับเมื่อสำเร็จ

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

ข้อมูลการตอบกลับ

              
              [
  {
    "regid": "010b81b3582",
    "online": true
  },
  {
    "regid": "0207870f1b8",
    "online": false,
    "last_online_time": "2014-12-16 10:57:07"
  },
  {
    "regid": "0207870f9b8",
    "online": false
  }
]

            

ข้อมูลการตอบกลับ

• online
  • true: ออนไลน์ภายใน 10 นาทีที่ผ่านมา
  • false: ไม่ได้ออนไลน์ภายใน 10 นาทีที่ผ่านมา
• last_online_time
  • เมื่อ online เป็น true จะไม่ส่งคืนฟิลด์นี้
  • เมื่อ online เป็น false และไม่มีการส่งคืนฟิลด์นี้ หมายความว่าเวลาออนไลน์ล่าสุดมากกว่าสองวันก่อน
• สำหรับค่า regid ที่ไม่ถูกต้อง หรือค่า regid ที่ไม่ได้อยู่ภายใต้ AppKey การตรวจสอบจะล้มเหลว

API สำหรับค้นหาข้อมูลโควตา TAG/alias

ค้นหาข้อมูลโควตาที่เกี่ยวข้องสำหรับ AppKey แพลตฟอร์ม และ tag ที่ระบุ สามารถค้นหา tags ได้ไม่เกิน 1000 รายการต่อครั้ง

Endpoint

              
              GET /v4/tags/quota-info?tags=tag1&platform=android
Authorization: Basic (base64 auth string)
Accept: application/json

            

ตัวอย่างคำขอ

              
              curl --location 'https://webpushapi-sgp.engagelab.com/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='

            

การตอบกลับเมื่อสำเร็จ

              
              {
  "data": {
    "totalTagQuota": 100000,
    "useTagQuota": 1,
    "totalAliasQuota": 100000,
    "useAliasQuota": 3,
    "tagUidQuotaDetail": [
      {
        "tagName": "tag1",
        "totalUidQuota": 100000,
        "useUidQuota": 0
      },
      {
        "tagName": "tag2",
        "totalUidQuota": 100000,
        "useUidQuota": 0
      }
    ]
  }
}

            

คำอธิบายฟิลด์การตอบกลับ:

• totalTagQuota: ระบุโควตารวมสำหรับจำนวน tags ภายใต้แอปพลิเคชัน
• useTagQuota: ระบุโควตา tag ที่ถูกใช้ไป
• totalAliasQuota: ระบุโควตารวมสำหรับจำนวน aliases ภายใต้แอปพลิเคชัน
• useAliasQuota: ระบุโควตา alias ที่ถูกใช้ไป
• tagUidQuota: ระบุโควตาสำหรับจำนวนอุปกรณ์ภายใต้ tag เดียว
• useUidQuota: ระบุรายละเอียดจำนวนอุปกรณ์ที่ผูกกับแต่ละ tag

การตอบกลับเมื่อไม่สำเร็จ

              
              {
  "error": {
    "code": 27002,
    "message": "Invalid parameters"
  }
}

            

รหัสสถานะ HTTP

เอกสารอ้างอิง: Http-Status-Code

รหัสตอบกลับทางธุรกิจ