สร้าง API การส่งข้อความ

ส่งการแจ้งเตือนหรือข้อความไปยังอุปกรณ์เดียวหรือรายการอุปกรณ์ เนื้อหาที่ส่งจะต้องเป็นวัตถุ JSON เท่านั้น

ข้อจำกัดอัตราการร้องขอ

API ของเรามีการจำกัดความถี่ในการเรียกใช้งานเพื่อให้มั่นใจถึงความเสถียรและความยุติธรรมของบริการ QPS (จำนวนคำขอต่อวินาที) สำหรับแต่ละ AppKey มีข้อจำกัดดังนี้:

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

วิธีการร้องขอ

POST

ที่อยู่การเรียกใช้งาน

ที่อยู่บริการอินเทอร์เฟซสอดคล้องกับจุดเชื่อมต่อของศูนย์ข้อมูลที่เลือก โปรดเลือกที่อยู่การเรียกใช้งานที่ตรงกับจุดเชื่อมต่อบริการแอปพลิเคชันของคุณ

ปัจจุบัน EngageLab ได้ปรับใช้และสนับสนุนจุดเชื่อมต่อศูนย์ข้อมูลสองแห่ง โดยข้อมูลระหว่างจุดเชื่อมต่อบริการที่แตกต่างกันจะถูกแยกออกจากกันโดยสมบูรณ์ คุณสามารถเลือกที่อยู่การเรียกใช้งานตามจุดเชื่อมต่อศูนย์ข้อมูลที่เลือกเมื่อสร้างผลิตภัณฑ์

              
              
POST v4/push

            

การตรวจสอบการเรียกใช้งาน

สำหรับข้อมูลเพิ่มเติม โปรดดู วิธีการรับรองความถูกต้อง ในภาพรวม REST API

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

ส่วนหัวของคำขอ

              
              > POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

            

เนื้อหาคำขอ

              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "alert" :"Hello, Push!",
            "android": {
                "alert": "Hi, Push!",
                "title": "Send to Android",
                "builder_id": 1,
                "extras": {
                    "newsid": 321
                }
            },
            "ios": {
                "alert": "Hi, MTPush!",
                "sound": "default",
                "badge": "+1",
                "extras": {
                    "newsid": 321
                }
            }
        },
        "options": {
            "time_to_live": 60,
            "apns_production": false
        }
    },
    "request_id": "12345678",
    "custom_args":{
             "Engagelab": "push to you"
    }
}'
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

            

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

โครงสร้างพารามิเตอร์การส่งมีดังตารางด้านล่าง:

from

ผู้ส่งบริการปัจจุบัน ประเภท String ฟิลด์ตัวเลือก

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

              
              {
    "from":"push"
}

            

to

วัตถุอุปกรณ์ที่ส่ง หมายถึงรายการอุปกรณ์ที่สามารถส่งได้ เพื่อยืนยันวัตถุอุปกรณ์ที่ส่ง App Push มีวิธีการหลายแบบ เช่น: ชื่อเล่น, ป้ายกำกับ, รหัสลงทะเบียน, กลุ่มย่อย, การกระจาย ฯลฯ

เป้าหมายการส่ง

นอกจากการกระจายแล้ว ยังมีวิธีการเลือกอุปกรณ์หลายแบบ ดังนี้:

ตัวอย่าง

• ส่งไปยังทั้งหมด (broadcast):

              
              {
  "to": "all",
}

            

• ส่งไปยังหลายแท็ก (เพียงแค่ตรงกับแท็กใดแท็กหนึ่ง): ในเซินเจิ้น, กว่างโจว หรือปักกิ่ง

              
              {
    "to":{
        "tag":[
            "Shenzhen",
            "Guangzhou",
            "Beijing"
        ]
    }
}

            

• ส่งไปยังหลายแท็ก (ต้องอยู่ในช่วงของแท็กหลายแท็กพร้อมกัน): ในเซินเจิ้นและ "ผู้หญิง"

              
              {
    "to":{
        "tag_and":[
            "Shenzhen",
            "female"
        ]
    }
}

            

• ส่งไปยังหลายชื่อเล่น:

              
              {
    "to":{
        "alias":[
            "4314",
            "892",
            "4531"
        ]
    }
}

            

• ส่งไปยังหลายหมายเลขการลงทะเบียน:

              
              {
  "to": {
    "registration_id": [
      "4312kjklfds2",
      "8914afd2",
      "45fdsa31"
    ]
  }
}

            

• สามารถส่งพร้อมกันไปยังเป้าหมายการส่งหลายประเภท: ในเซินเจิ้นหรือกว่างโจวและเป็น "ผู้หญิง" "สมาชิก"

              
              {
    "to":{
        "tag":[
            "Shenzhen",
            "Guangzhou"
        ],
        "tag_and":[
            "female",
            "members"
        ]
    }
}

            

• ส่งข้อความกิจกรรมสด

              
                {
      "to": {
          "live_activity_id": "LiveActivity-1"
      }
  }

            

ส่งไปยัง ID การแบ่งกลุ่มผู้ใช้:

              
              {
  "to": {
    "seg": {
      "id":"segid"
    }
  }
}

            

เนื้อหา

ส่งเนื้อหาคำขอ ฟิลด์ที่รองรับมีดังนี้:

แพลตฟอร์ม

MTPush รองรับการส่งสำหรับแพลตฟอร์ม Android และ iOS คำสำคัญคือ: "android", "ios" ตามลำดับ

ส่งไปยังทุกแพลตฟอร์ม:

              
              { "platform" : "all" }

            

กำหนดแพลตฟอร์มการส่งเฉพาะ:

              
              {
  "platform": [
    "android",
    "ios"
  ]
}

            

การแจ้งเตือน

วัตถุ "Notification" ซึ่งเป็นหนึ่งในวัตถุเนื้อหาของการส่ง (อีกอันคือ "Message") จะถูกส่งไปยังไคลเอนต์ในรูปแบบ "Notification"

การแจ้งเตือน

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

              
              {
  "notification" : {
    "alert" : "Hello, Push!"
  }
}

            

วัตถุการแจ้งเตือนที่กำหนดข้างต้นจะถูกส่งไปยังหลายแพลตฟอร์มที่ระบุโดย "platform" และทั้งหมดจะมีข้อความการแจ้งเตือนเหมือนกัน

Android

การแจ้งเตือนบนแพลตฟอร์ม Android จะแสดงโดย MTPush SDK ตามรูปแบบแถบการแจ้งเตือนที่กำหนดไว้ ฟิลด์ที่รองรับมีดังนี้:

              
              {
    "notification": {
        "android": {
            "alert": "hello, MTPush!",
            "title": "Push test",
            "builder_id": 3,
            "style": 1,
            "big_text": "big text content",
            "inbox":JSONObject,
            "big_pic_path": "picture url",
            "priority": 0,
            "category": "category str",
            "large_icon": "http://pushapi-sgp.engagelab.comlargeIcon.jpg",
            "small_icon": "http://www.small.com/small_icon.jpg",
            "intent": {
                "url": "intent:#Intent;component=push.pushapi-sgp.engagelab.com/com.example.mtpushdemo.SettingActivity;end"
            },
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

            

iOS

การแจ้งเตือน APNs บนแพลตฟอร์ม iOS

เนื้อหาการแจ้งเตือนถูกส่งโดยตัวแทน MTPush ไปยังเซิร์ฟเวอร์ Apple APNs และแสดงบนอุปกรณ์ iOS เป็นการแจ้งเตือนระบบ

เนื้อหาการแจ้งเตือนตรงตามข้อกำหนด APNs และรองรับฟิลด์ต่อไปนี้:

ตัวอย่างการส่งฝั่งเซิร์ฟเวอร์:

              
              {
    "notification": {
        "ios": {
            "alert": "hello, Push!",
            "sound": "sound.caf",
            "badge": 1,
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

            

ข้อความที่ได้รับโดยไคลเอนต์:

              
              {
  "_j_msgid" = 813843507;
  aps =     {
  alert = "hello,Push!";
  badge = 1;
  sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}

            

ข้อความ

ข้อความในแอปพลิเคชัน หรือเรียกอีกชื่อว่า: ข้อความที่กำหนดเอง, ข้อความผ่าน

• ส่วนนี้จะไม่แสดงในแถบการแจ้งเตือน, MTPush SDK จะรับเนื้อหาข้อความและส่งต่อไปยังแอปพลิเคชัน
• iOS เมื่อแอปพลิเคชันอยู่ในโหมดเบื้องหน้า จะได้รับส่วนนี้ผ่านช่องทางข้อความในแอปพลิเคชัน (ไม่ใช่ APNS)

ฟิลด์ที่รองรับมีดังนี้:

ตัวอย่าง:

              
              {
  "message": {
    "msg_content": "Hi,Push",
    "content_type": "text",
    "title": "msg",
    "extras": {
      "key": "value"
    }
  }
}

            

กิจกรรมแบบเรียลไทม์

หมายเหตุ: ข้อความกิจกรรมแบบเรียลไทม์จำเป็นต้องใช้ใบรับรอง iOS P8 และเลือกการตั้งค่าการรับรอง iOS WebPortal ในหัวข้อ "การตั้งค่าการรับรองโทเค็น"

เนื้อหาข้อความกิจกรรมแบบเรียลไทม์ประกอบด้วยฟิลด์ดังต่อไปนี้:

iOS JSON Object

iOS alert JSON Object

• ข้อความกิจกรรมแบบเรียลไทม์ของ iOS จะถูกส่งต่อไปยังเซิร์ฟเวอร์ของ Apple ผ่าน Engagelab Push Apple กำหนดให้ข้อมูลอัปเดตแบบไดนามิกของข้อความกิจกรรมแบบเรียลไทม์ (ActivityKit) ต้องไม่เกิน 4096 ไบต์
• เนื่องจากความต้องการการบรรจุใหม่และการพิจารณาความปลอดภัย Engagelab Push กำหนดความยาวรวมของพารามิเตอร์ "live_activity" ใน "iOS": { } และเนื้อหาในวงเล็บต้องไม่เกิน 3584 ไบต์ JPush ใช้การเข้ารหัส UTF-8 ซึ่งตัวอักษรจีนหนึ่งตัวใช้ 3 ไบต์

ตัวอย่างการส่งข้อความกิจกรรมแบบเรียลไทม์

ประเภท attributes-type และ live_activity_id ที่ใช้ในกิจกรรมแบบเรียลไทม์จะถูกรายงานโดย SDK ของนักพัฒนา ก่อนใช้งานกิจกรรมแบบเรียลไทม์ จำเป็นต้องรายงานโทเค็นเริ่มต้นการแจ้งเตือนของอุปกรณ์และโทเค็นอัปเดต ดูกระบวนการโดยละเอียดที่ คู่มือกิจกรรมแบบเรียลไทม์ของ Apple

• การสร้าง

  { "from": "push", "to": { "registration_id": [ "161a3797c816b134042" ] }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "start", "content-state": { "eventStr": "hello", "eventTime":1685952000 }, "attributes": { "name": "1", "number": 2, "tag": "mytag" }, "alert": { "title": "hello", "body": "welcome" }, "attributes-type": "my_la_type", "relevance-score": 100, "apns-priority": 100 } } }, "request_id": "12345678", "custom_args": "12345678" }

                
                {
      "from": "push",
     "to": {
          "registration_id": [
              "161a3797c816b134042"
          ]
      },
      "body": {
          "platform": "ios",
          "live_activity": {
              "ios": {
                  "event": "start",
                  "content-state": {
                      "eventStr": "hello",
                      "eventTime":1685952000
                  },
                  "attributes": {
                      "name": "1",
                      "number": 2,
                      "tag": "mytag"
                  },
                  "alert": {
                      "title": "hello",
                      "body": "welcome"
                  },
                  "attributes-type": "my_la_type",
                  "relevance-score": 100,
                  "apns-priority": 100
              }
          }
      },
      "request_id": "12345678",
      "custom_args": "12345678"
  }
  
              

  โค้ดนี้โชว์เป็นหน้าต่างลอย

• การอัปเดต

  { "from": "push", "to": { "live_activity_id": "my_la_id" }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "update", "content-state": { "eventStr": "test_live", "eventTime": 198 }, "alert": { "title": "123411", "body": "123411" } } } }, "request_id": "12345678", "custom_args": "12345678" }

                
                {
     "from": "push",
     "to": {
           "live_activity_id": "my_la_id"
      },
      "body": {
          "platform": "ios",
          "live_activity": {
              "ios": {
                  "event": "update",
                  "content-state": {
                      "eventStr": "test_live",
                      "eventTime": 198
                  },
  
                  "alert": {
                      "title": "123411",
                      "body": "123411"
                  }
              }
          }
      },
      "request_id": "12345678",
      "custom_args": "12345678"
  }
  
              

  โค้ดนี้โชว์เป็นหน้าต่างลอย

Voip

ฟังก์ชัน VOIP ของ iOS ประเภทนี้ไม่รองรับการอยู่ร่วมกับประเภทข้อความ iOS อื่น ๆ โครงสร้างพารามิเตอร์คำขออ้างอิง:

              
              { 
    "from": "push", 
    "to": { 
        "registration_id": [ "1a0018970a91da03de5" ] 
    }, 
    "request_id": "12345", 
    "custom_args": "12345", 
    "body": { 
        "platform": "ios", 
        "voip": { 
            "key": "value // คีย์-ค่าแบบกำหนดเองใด ๆ ที่จะส่งต่อไปยังแอปพลิเคชัน" 
        } 
    } 
}

            

ตัวเลือก

ตัวเลือกการแจ้งเตือนแบบพุชปัจจุบันประกอบด้วยเนื้อหาดังต่อไปนี้:

Multi_language

ฟิลด์นี้ใช้สำหรับฟังก์ชันการพุชหลายภาษาของบริการ EngageLab Push อนุญาตให้คุณส่งเนื้อหาการแจ้งเตือนที่กำหนดเองไปยังผู้ใช้ที่พูดภาษาต่างกัน โดยการระบุหลายภาษาและเนื้อหาข้อความ หัวข้อ และคำบรรยาย iOS ที่สอดคล้องกันในคำขอพุช คุณสามารถส่งการแจ้งเตือนที่เหมาะสมตามการตั้งค่าภาษาของผู้ใช้

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

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

              
                 HTTP วิธีการขอ: POST
   URL คำขอ: /v4/grouppush หรือ /v4/push
   รูปแบบข้อมูลคำขอ: JSON
   ตัวอย่างคำขอ:
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
          "ios_subtitle": ""
        }
      }
    }
   }

            

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

              
              การตอบสนองสำเร็จ:
{
   
}

            

              
              
การตอบสนองล้มเหลว:
{   
    "code": 400,  
    "data": "",
  "message": "ข้อความผิดพลาด"
}   

            

Third_party_channel

ฟิลด์นี้ใช้สำหรับกรอกข้อมูลเฉพาะของช่องทางผู้ผลิต Android key รองรับเฉพาะช่องทางผู้ผลิต Android 7 ช่องทาง ได้แก่ xiaomi, huawei, meizu, oppo, vivo, fcm, honor สามารถมีอยู่ได้หนึ่งหรือหลายช่องทางพร้อมกัน แต่ละประเภท key ของผู้ผลิตสามารถมีตัวเลือกดังนี้:

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

เพื่อให้สอดคล้องกับกลยุทธ์ช่องทางผู้ผลิตหลายรายและลดความซับซ้อนของการกำหนดค่า ฟิลด์ distribution_new ได้รับการปรับเปลี่ยนวิธีการกำหนดค่าดังนี้ การกำหนดค่าระดับผู้ผลิตในอดีตของคุณยังคงใช้ได้ แต่แนะนำให้ย้ายไปยังการกำหนดค่าระดับโลกเพื่อหลีกเลี่ยงความเสี่ยงด้านความเข้ากันได้ในอนาคต (กฎใหม่จะมีผลบังคับใช้ตั้งแต่วันที่ 3 เมษายน 2025):

• ลำดับความสำคัญของการกำหนดค่า (กฎใหม่)
  • ลำดับความสำคัญที่หนึ่ง: การกำหนดค่าระดับโลก third_party_channel.distribution_new (วิธีใหม่ที่แนะนำ)
    ตัวอย่าง: "distribution_new": "pns_mtpush"
  • ลำดับความสำคัญที่สอง: การกำหนดค่าระดับผู้ผลิต third_party_channel.{vendor_key}.distribution_new (วิธีการที่เข้ากันได้ในอดีต)
    มีผลเฉพาะเมื่อไม่ได้ตั้งค่าระดับโลก
  • ไม่ได้กำหนดค่า: กลยุทธ์เริ่มต้น: pns_mtpush

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

              
              {
    "third_party_channel": {
        "distribution_new": "pns_mtpush",
        "xiaomi": {
            "channel_id": "*******",
            "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
            "small_icon_color": "#ABCDEF"
        },
        "huawei": {
            "importance": "NORMAL",
            "small_icon_uri": "https://xx.com/xx.jpg",
            "only_use_vendor_style": true
        },
        "oppo": {
            "channel_id": "*******",
            "large_icon": "3653918_5f92b5739ae676f5745bcbf4"
        },
        "vivo": {
            "pushMode": 0
        }
    }
}

            

Request_id

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

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

              
              {
      "request_id":"12345678"
}

#### Return Example

```json
{
    "msg_id": "1225764",
    "request_id": "12345678"
}

            

ตัวอย่างการส่งคืน

              
              {
    "msg_id": "1225764",
    "request_id": "12345678"
}

            

Custom_args

ฟิลด์ที่กำหนดเองโดยลูกค้า เป็นฟิลด์ที่ไม่จำเป็น ไม่ได้ส่งคืนในการตอบกลับ และจะถูกส่งคืนใน callback

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

              
              {
  "custom_args":{
    "args1": "args1"
  }
}

            

พารามิเตอร์การส่งคืน

การส่งคืนที่สำเร็จ

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}

            

การส่งคืนที่ล้มเหลว

รหัสสถานะ HTTP เป็น 4xx หรือ 5xx และเนื้อหาการตอบกลับประกอบด้วยฟิลด์ดังต่อไปนี้:

              
              {
    "error":{
    "code": 3002,
    "message": "Push.template field must be set correctly when type is template"
    }
}

            

การส่งคืนการเรียก

รหัสสถานะ HTTP

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

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

ขีดจำกัดการส่งพุช

รหัสภาษาหลายภาษา