ข้ามไปที่เนื้อหา

การส่งแบบเดี่ยว

ข้อกำหนดเบื้องต้น

เพื่อซิงค์กับ Single Push API ให้แน่ใจว่าคุณได้ออกโทเค็นการอนุญาต (API KEY) หากคุณมีคีย์แล้วให้ขอสิทธิ์เพิ่มเติม ดูที่ Hive Server API > Notification > Push v4 > Authentication เพื่อตรวจสอบวิธีการขอและออกโทเค็นการอนุญาต

Note

Single Puch API เป็นแบบอะซิงโครนัสและประมวลผลตามลำดับ, API Request > Token Lookup > Send.

  • API Request: ตรวจสอบข้อมูลคำขอและส่งคืนรหัสการตอบสนองต่อคำขอ
  • Token Lookup: ค้นหาท็อกเกนการส่งไปยังข้อมูลคำขอ อาจมีสถานการณ์ที่ไม่มีท็อกเกน
  • Send: ส่งข้อมูลไปยังเซิร์ฟเวอร์การส่งของแต่ละตลาด (เช่น ADM, APNS, FCM และ Facebook) การตอบสนองที่ได้รับจากตลาดจะแสดงผลลัพธ์การประมวลผล
  • เมื่อการประมวลผลล้มเหลวในขั้นตอนการค้นหาท็อกเกนและการส่ง จะไม่มีการส่งคืนการตอบสนองไปยังไคลเอนต์ที่เรียกเซิร์ฟเวอร์การส่ง หากคุณไม่ได้รับการส่งใน 10 นาทีตั้งแต่คุณส่งข้อมูล โปรดติดต่อทีม Solution Architect, Com2uS Platform.

URL

เซิร์ฟเวอร์ URL
ผลิต https://notification.withhive.com
แซนด์บ็อกซ์ https://sandbox-notification.withhive.com

ข้อมูลพื้นฐานและตัวแปรคำขอ

วิธีการ POST
URL /push/send
แผนก ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
Header Content-Type application/json;charset=utf-8
Authorization bearer {{API KEY}}
Body notice

ว่าจะส่งการแจ้งเตือนประกาศหรือไม่ (ค่าเริ่มต้น: 'false')

      true
    • ส่งเป็นการแจ้งเตือนประกาศ
    • ส่งการแจ้งเตือนตามข้อตกลงของผู้ใช้
      false
    • ส่งเป็นการแจ้งเตือนเกม
    • ส่งการแจ้งเตือนโดยไม่คำนึงถึงข้อตกลงของผู้ใช้

การแจ้งเตือนประกาศและการแจ้งเตือนในเวลากลางคืนเป็นรายการที่จำเป็นต้องได้รับความเห็นชอบจากผู้ใช้

  • หากผู้ใช้ไม่เห็นด้วยที่จะรับการแจ้งเตือนประกาศ การแจ้งเตือนทั้งหมดที่ตั้งค่าเป็นการประกาศจะถูกบล็อกไม่ให้ส่ง
  • การเห็นด้วยในการรับการแจ้งเตือนในเวลากลางคืนจะเปิดใช้งานได้เฉพาะหลังจากเห็นด้วยในการรับการแจ้งเตือนประกาศ; มิฉะนั้น การแจ้งเตือนทั้งหมดที่ตั้งค่าเป็นการประกาศจะถูกบล็อกไม่ให้ส่งในเวลากลางคืน เวลากลางคืนคือระหว่าง 21:00 น. ถึง 08:00 น.

Boolean O
identifiers ข้อมูลตัวระบุ (สูงสุด 100) ตรวจสอบ โครงสร้างตัวระบุและ ตัวอย่างด้านล่าง identifier[] O
เกม gameid รหัสเกม String O
appids

รายการของ AppID ไม่มีการส่งหาก AppID ที่แมพไม่ถูกต้อง

คำแนะนำ

  • หาก ID ที่อิงจากอุปกรณ์ (did): เพิ่ม AppID ที่แมพ
  • หาก ID ที่อิงจากบัญชี (playerId, vid, uid): เพิ่มรายการของ AppIDs ที่แมพทั้งหมด
  • หากมี ID หลายประเภท: อ้างอิงจาก โครงสร้างตัวระบุเพื่อตรวจสอบลำดับความสำคัญ

String[] X
enableLocale

ว่าจะเปิดใช้งานภาษาของแต่ละภาษาหรือไม่

    true
  • ส่งข้อความในภาษาที่ผู้ใช้เป้าหมายตั้งไว้ ซึ่งอิงจากโทเค็นและรหัสภาษาที่ตั้งไว้
  • จะกำหนดภาษาขณะจัดเก็บโทเค็น
  • ลำดับความสำคัญสูงสุด: ภาษาเกม
  • ลำดับความสำคัญที่สอง: ภาษาอุปกรณ์ (เว้นแต่จะส่งภาษาเกม)
    false
  • ไม่สนใจภาษาท้องถิ่นและส่งเป็นค่าของฟิลด์เดียวใน payload

Boolean O
payload single คำขอไปยังฟิลด์เดียวหาก enableLocale=false ตรวจสอบ โครงสร้างข้อความด้านล่าง Message O
defaultLanguage ตั้งค่าด้วยค่าของภาษาที่ตั้งไว้หาก enableLocale=true. String
locale {{LANGUAGE}} ตั้งค่าด้วยค่าของฟิลด์ locale หาก enableLocale=true ข้อมูลเดียวกันกับข้อมูลข้อความของฟิลด์เดียว Message
option อ้างอิงจาก ข้อมูลเพิ่มเติมด้านล่าง Option X
Note
  • สำหรับการรับข้อมูลแบบพุชที่เหมาะสม แนะนำให้ป้อนข้อมูลเพียงหนึ่งรายการสำหรับฟิลด์ appids และ identifiers เท่านั้น
    • เนื่องจากไม่สามารถกำหนดเงื่อนไขการค้นหาได้ การส่งพุชอาจล่าช้า หากคำขอมีตัวระบุและ appids หลายรายการ
  • แนะนำให้กำหนดค่าที่มีความสำคัญสูงสำหรับค่าตัวระบุ และหลีกเลี่ยงการกำหนดค่าตัวระบุเพียงแค่ค่าด้วย did เท่านั้น
  • คำขอที่ระบุเฉพาะ gameid ในฟิลด์เกมต้องหลีกเลี่ยง
    • การส่งพุชอาจล่าช้า หากไม่มีข้อมูลในฟิลด์ appids เนื่องจาก appids ทั้งหมดที่รวมอยู่ใน gameid จะถูกค้นหา
  • ฟิลด์ตัวเลือกไม่สามารถใช้ได้กับ Facebook.

โครงสร้างตัวระบุ

การแบ่ง ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
ตัวระบุ ตัวระบุ playerId ต้องรวมตัวระบุหนึ่งในสี่ตัว โดยให้ลำดับความสำคัญคือ playerId, vid, uid และ did ตามลำดับ Long O
vid
uid
did

ตัวอย่างตัวระบุ

[
  {
    "playerId":51234,
    "vid":11232,
    "did":1234
  }
]

โครงสร้างข้อความ

iostitleTitleStringOfacebooktitleTitle (ภายใน 1~30 ตัวอักษร)StringO

แผนก ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
ข้อความ แอนดรอยด์ ชื่อเรื่อง ชื่อเรื่อง สตริง ใช่
ข้อความ ข้อความ สตริง ใช่
ข้อความที่ขยาย ข้อความที่ขยาย สตริง ใช่
ลิงก์ภาพ ลิงก์ภาพ สตริง ไม่จำเป็น
ticker Ticker สตริง ไม่จำเป็น
ข้อความสรุป ข้อความที่สรุป สตริง ไม่จำเป็น
ข้อความ ข้อความ สตริง ใช่
ลิงก์สื่อ เส้นทางภาพ สตริง ไม่จำเป็น
เนื้อหา เนื้อหา (ภายใน 10~180 ตัวอักษร) สตริง ใช่
สื่อ ลิงก์ภาพ สตริง ใช่

ข้อมูลตัวเลือก

หมวดหมู่ ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
ตัวเลือก badge ค่าตัวเลขที่แสดงบนไอคอนแอปเมื่อได้รับการแจ้งเตือนแบบพุช (ค่าเริ่มต้น: 1) จำนวนเต็ม X
overwrite ว่าจะใช้ฟีเจอร์การเขียนทับแบบพุชบน Android หรือไม่ (ค่าเริ่มต้น: false) บูลีน X
collapseKey คีย์ค่า (รูปแบบสตริงของหมายเลข: "123") ที่ใช้เมื่อฟีเจอร์การเขียนทับแบบพุชเปิดใช้งาน สตริง X
engagement การมีส่วนร่วมของผู้ใช้ สตริง X
comment ข้อความ สตริง X
groupKey นี่คือค่ากุญแจกลุ่มที่ใช้ในการจัดกลุ่มการแจ้งเตือนเมื่อได้รับบนอุปกรณ์ iOS และ Android ตัวเลือกการแจ้งเตือนที่ตั้งไว้ในระบบปฏิบัติการของอุปกรณ์จะถูกนำไปใช้โดยอัตโนมัติ สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับตัวเลือก โปรดดูเอกสารด้านล่าง String X
แอนดรอยด์ ไอคอน ชื่อไฟล์ของภาพไอคอนที่ปรากฏเมื่อมีการรับการแจ้งเตือนแบบพุชบนอุปกรณ์ของผู้ใช้ ไฟล์ภาพต้องมีอยู่ใน /src/main/res/drawable รูปแบบไฟล์ภาพที่รองรับสามารถดูได้ ที่นี่. ถ้าคุณต้องการแสดงภาพจากเว็บ ให้ใส่ URL ของภาพในช่องนี้แทนชื่อไฟล์ หากช่องนี้ว่าง ไอคอนแอปจะถูกแสดง สตริง X
เสียง ชื่อไฟล์ของเสียงการแจ้งเตือนที่จะเล่นเมื่อมีการรับการแจ้งเตือนแบบพุชบนอุปกรณ์ของผู้ใช้ คุณสามารถระบุไฟล์เสียงที่รวมอยู่ในแอปบันเดิล และไฟล์เสียงต้องมีอยู่ใน /src/main/res/raw หากช่องนี้ว่าง เสียงเริ่มต้นของระบบจะถูกใช้ สตริง X
ความสำคัญ ความสำคัญของข้อความที่ถูกส่งไปยังอุปกรณ์ Android ความสำคัญนี้ควบคุมเวลาการส่งข้อความ ซึ่งเป็นแนวคิดจาก FCM มันสามารถมีค่าเป็น NORMAL หรือ HIGH โดยค่าเริ่มต้นคือ NORMAL สำหรับรายละเอียดเพิ่มเติม โปรดดูที่ คู่มือ Firebase.
  • NORMAL = ความสำคัญเริ่มต้นสำหรับข้อความข้อมูล ข้อความที่มีความสำคัญตามปกติจะถูกส่งทันทีเมื่ออุปกรณ์ไม่ได้อยู่ในโหมดพัก เมื่ออุปกรณ์อยู่ในโหมดพัก การส่งอาจถูกเลื่อนเพื่อประหยัดแบตเตอรี่จนกว่าอุปกรณ์จะออกจากโหมดพัก เลือกความสำคัญในการส่งปกติสำหรับข้อความที่ไม่เร่งด่วน เช่น การแจ้งเตือนอีเมลใหม่ การรักษา UI ให้ซิงค์ และการซิงโครไนซ์ข้อมูลแอปในพื้นหลัง
  • HIGH = FCM จะพยายามส่งข้อความที่มีความสำคัญสูงทันทีและอาจปลุกอุปกรณ์จากโหมดสลีปหากจำเป็น โดยจะดำเนินการงานประมวลผลที่จำกัด รวมถึงการเข้าถึงเครือข่ายที่มีข้อจำกัดมาก ข้อความที่มีความสำคัญสูงมักเกี่ยวข้องกับการโต้ตอบของผู้ใช้กับแอปหรือการแจ้งเตือน。
enum(NORMAL, HIGH) X
ios เสียง ชื่อไฟล์ของเสียงการแจ้งเตือนที่จะเล่นเมื่อได้รับการแจ้งเตือนแบบพุชบนอุปกรณ์ของผู้ใช้ ไฟล์เสียงต้องมีอยู่ใน Library/Sounds ของคอนเทนเนอร์แอปหรือในแพ็คเกจหลักของแอป หากฟิลด์นี้ว่าง จะถูกตั้งค่าเป็น "default" โดยอัตโนมัติ โดยใช้ เสียงเริ่มต้นของระบบ บนอุปกรณ์ Apple ของผู้ใช้。 String X

ผลลัพธ์

แบ่งส่วน ชื่อฟิลด์ คำอธิบาย
หัวข้อ Content-Type application/json;charset=utf-8
UUID {{UUID}}
เนื้อหา - เนื้อหาว่างเปล่าหากสำเร็จ

รหัสสถานะการตอบกลับ

คีย์ ค่า คำอธิบาย
200 สำเร็จ (เนื้อหาว่างเปล่า)
400 คำขอไม่ถูกต้อง ข้อมูล POST หายไป. ข้อผิดพลาดรูปแบบ JSON องค์ประกอบที่จำเป็นหายไปหรือไม่ถูกต้อง.
401 ไม่ได้รับอนุญาต หัวเรื่องการอนุญาตในข้อความคำขอหายไปหรือไม่ถูกต้อง. คีย์การอนุญาต (API KEY) ไม่ได้ลงทะเบียน. ไม่มีสิทธิ์เข้าถึง API ที่เกี่ยวข้อง
403 ห้าม รูปแบบการตรวจสอบสิทธิ์ของหัวเรื่องการอนุญาตไม่ใช่ "Bearer". (รองรับเฉพาะ Bearer เท่านั้น)
404 ไม่พบ URL คำขอผิด.
500 ข้อผิดพลาดภายในเซิร์ฟเวอร์ ข้อผิดพลาดภายในเซิร์ฟเวอร์
502 ประตูเชื่อมต่อไม่ถูกต้อง เซิร์ฟเวอร์เกตเวย์ที่ผลักดันมีภาระเกิน. การเชื่อมต่อเครือข่ายผิดพลาด.
503 บริการไม่พร้อมใช้งาน เซิร์ฟเวอร์ API หรือเซิร์ฟเวอร์การตรวจสอบสิทธิ์หยุดทำงาน.

ตัวอย่างโค้ด

  • เรียก ("enableLocale":false)

    curl -L -v
    > -d '{"notice":false,"identifiers":[{"vid":19239,"did":300010915}],"game":{"gameid":"com.com2us.hivesdk","appids":["com.com2us.hivesdk.normal.freefull.google.global.android.common"]},"enableLocale":false,"payload":{"single":{"android":{"title":"TEST","message":"TEST","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","mediaUrl":""},"facebook":{"title":"TEST", "body":"TEST MESSAGE BODY", "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"}},"option":{"badge":"1","overwrite":false,"collapseKey":"","engagement":"","groupKey": "", "android":{"icon":"","sound":"", "priority": "normal"},"ios":{"sound":""}}}}'
    > -d '{"notice":false,"identifiers":[{"vid":19239,"did":300010915}],"game":{"gameid":"com.com2us.hivesdk","appids":["com.com2us.hivesdk.normal.freefull.google.global.android.common"]},"enableLocale":false,"payload":{"single":{"android":{"title":"TEST","message":"TEST","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","mediaUrl":""},"facebook":{"title":"TEST", "body":"TEST MESSAGE BODY", "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"}},"option":{"badge":"1","overwrite":false,"collapseKey":"","engagement":"","groupKey": "", "android":{"icon":"","sound":"", "priority": "normal"},"ios":{"sound":""}}}}'
    > -H "Content-Type: application/json"
    > -H "Authorization: Bearer {API KEY}"
    > https://sandbox-notification.qpyou.cn/push/send
    
  • เรียก ("enableLocale":true)

    {
        "notice": false,
        "identifiers": [
            {
                "playerId": 30000028045
    }
    ],
        "game": {
            "gameid": "com.com2us.hivesdk",
            "appids": [
    "com.com2us.hivesdk.normal.freefull.google.global.android.common",
    "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal"
    ]
        },
        "enableLocale": true,
        "payload": {
            "defaultLanguage": "en",
            "locale": {
                "ko": {
                    "android": {
                        "title": "test_Korean_title",
                        "message": "test_Korean_message"
                    },
                    "ios": {
                        "title": "test_Korean_title",
                        "message": "test_Korean_message"
                    },
                    "facebook": {
                        "title": "test_Korean_title",
                        "body": "test_Korean_message",
                        "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
                    }
                },
                "en": {
                    "android": {
                        "title": "test_English title",
                        "message": "test_English message"
                    },
                    "ios": {
                        "title": "test_English title",
                        "message": "test_English message"
                    },
                    "facebook": {
                        "title": "test_English title",
                        "body": "test_English message",
                        "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
                    }
                }
            },
            "option": {
                "badge": 1,
                "overwrite": true,
                "collapseKey": "99",
                "groupKey: "",
                "android": {
                    "icon": "GoogleIcon",
                    "sound": "GoogleSound",
                    "priority": "normal"
                },
                "ios": {
                    "sound": "AppleSound"
                }
            }
        }
    }
    
Note

แนะนำให้ ส่งข้อมูลการโทรในแถวโดยไม่มีช่องว่าง เพื่อให้เซิร์ฟเวอร์ตรวจสอบบันทึกได้ทันที.

  • ขอร้อง
> POST /push/send HTTP/1.1
> User-Agent: curl/7.29.0
> Host: sandbox-notification.qpyou.cn
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NDE1NzMyOTcsImp0aSI6ImFkbWluaXN0cmF0b3IifQ.23nG9RnbuOwnMbRSebBi2i-Qt_fOfqU_vUKUZ2JJlWU
> Content-Length: 502
  • การตอบสนอง
< HTTP/1.1 200 OK
< content-length: 0
< Content-Type: application/json
< UUID: 3bc6b414-e2df-40d6-8006-9d2308a6edf9