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

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

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

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

• Android - tag, alias
• iOS - tag, alias
• HarmonyOS - tag, alias

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

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

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

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

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

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

ภาพรวม API

API นี้ใช้ฝั่งเซิร์ฟเวอร์เพื่อค้นหา ตั้งค่า อัปเดต และลบข้อมูล tag และ alias ของอุปกรณ์

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

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

ข้อมูลสำคัญอีกส่วนหนึ่งที่จำเป็นคือ registration ID:

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

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

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

Endpoint

              
              GET /v4/tags_count

            

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

Request Header

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

            

Request Example

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

            

Request Parameters

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

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

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

Successful Response

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

            

Failed Response

              
              {
  "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 Header

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

            

Request Parameters

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

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

Successful Response

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

            

Response Data

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

            

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

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

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

Endpoint

              
              POST /v4/devices/{registration_id}

            

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

Request Header

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

            

Request Data

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

            

Request Parameters

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

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

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

ค้นหารายการ Tag

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

Endpoint

              
              GET /v4/tags/

            

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

Request Header

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

            

Request Parameters

• ไม่มี

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

Successful Response

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

            

Response Data

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

            

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

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

• ค้นหาว่าอุปกรณ์อยู่ภายใต้ tag หรือไม่

Endpoint

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

            

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

Request Header

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

            

Request Parameters

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

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

Successful Response

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

            

Response Data

              
              {
  "result": true
}

            

อัปเดต Tag

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

Endpoint

              
              POST /v4/tags/{tag_value}

            

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

Request Header

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

            

Request Data

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

            

Request Parameters

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

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

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

ลบ Tag

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

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

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

Request Header

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

            

Request Parameters

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

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

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

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

              
              GET /v4/aliases/{alias_value}
รับอุปกรณ์ภายใต้ alias ที่ระบุ

            

ค้นหา Alias

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

Endpoint

              
              GET /v4/aliases/{alias_value}

            

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

Request Header

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

            

Request Parameters

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

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

Successful Response

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

            

Response Data

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

            

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

ลบ Alias

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

              
              DELETE /v4/aliases/{alias_value}

            

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

Request Header

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

            

Request Parameters

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

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

• สำเร็จ

              
              success

            

• ล้มเหลว

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

            

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

Endpoint

              
              POST /v4/devices/status/

            

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

Request Header

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

            

Request Data

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

            

Request Parameters

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

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

Successful Response

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

            

Response Data

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

            

Response Data

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

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

ค้นหาข้อมูลโควตาที่เกี่ยวข้องกับ AppKey, platform และ tag ที่ระบุ สามารถค้นหา tag ได้ไม่เกิน 1,000 รายการต่อครั้ง

Endpoint

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

            

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

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

            

Successful Response

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

            

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

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

Failed Response

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

            

รหัสสถานะ HTTP

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

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