Membuat Push API

Kirim notifikasi atau pesan ke satu perangkat atau ke daftar perangkat. Konten yang dikirim hanya berupa objek push dalam format JSON.

Batas Frekuensi Permintaan

API kami menerapkan batas frekuensi panggilan untuk menjaga stabilitas dan keadilan layanan. Batas QPS (Queries Per Second) untuk setiap AppKey adalah:

• Batas Standar: Maksimal 500 permintaan per detik.
• Batas Lanjutan: Jika Anda adalah pelanggan paket berbayar dan AppKey Anda membutuhkan batas QPS lebih tinggi, silakan hubungi tim bisnis kami: Sales@engagelab.com.

Metode Permintaan

POST

Alamat Endpoint

Alamat layanan antarmuka sesuai dengan pusat data yang dipilih. Silakan pilih alamat endpoint yang sesuai dengan pusat data aplikasi Anda.

Saat ini, EngageLab menyediakan dua pusat data, dan data antar pusat data benar-benar terpisah. Pilih alamat endpoint sesuai pusat data yang dipilih saat membuat produk.

              
              POST v4/push

            

Validasi Permintaan

Untuk informasi lebih lanjut, lihat ringkasan REST API pada Metode Autentikasi.

Contoh Permintaan

Header Permintaan

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

            

Body Permintaan

              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "alert" :"Hello, Push!",
            "android": {
                "alert": "Hi, Push!",
                "title": "Kirim ke 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 untuk Anda"
    }
}'
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

            

Parameter Permintaan

Struktur parameter push dijelaskan pada tabel berikut:

from

Pengirim layanan saat ini, tipe String, field opsional.

Contoh Permintaan

              
              {
    "from":"push"
}

            

to

Objek Perangkat Push, menunjukkan daftar perangkat yang dapat dikirimi push. Penentuan target perangkat push bisa menggunakan alias, tag, registration ID, subgroup, broadcast, dan lainnya.

Target Push

Beberapa cara memilih perangkat selain broadcast:

Contoh

• Push ke semua perangkat (broadcast):

              
              {
  "to": "all",
}

            

• Push ke beberapa tag (cukup salah satu tag): di Shenzhen, Guangzhou, atau Beijing

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

            

• Push ke beberapa tag (harus memenuhi semua tag): di Shenzhen dan "perempuan"

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

            

• Push ke beberapa alias:

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

            

• Push ke beberapa registration ID:

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

            

• Push ke beberapa tipe target sekaligus: di Shenzhen atau Guangzhou dan "perempuan" "anggota"

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

            

• Push pesan live activity

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

            

Push ke ID segmentasi pengguna:

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

            

Body

Body permintaan push. Field yang didukung sebagai berikut:

Platform

MTPush mendukung push ke Android, iOS, dan HarmonyOS. Kata kuncinya: "android", "ios", "hmos".

Push ke semua platform:

              
              { "platform" : "all" }

            

Pilih platform tertentu:

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

            

Notification

Objek "Notification" adalah salah satu entitas konten push (satunya lagi "Message"), dikirim ke klien sebagai notifikasi.

Alert

Properti "alert" di sini (langsung di bawah notification) adalah shortcut. Jika pesan alert sama di semua platform, cukup di sini. Jika ada di tiap platform, maka menimpa yang di sini.

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

            

Objek notification di atas akan dikirim ke semua platform yang ditentukan oleh "platform" dan semua akan menerima pesan notifikasi yang sama.

Android

Notifikasi di Android ditampilkan oleh MTPush SDK sesuai gaya notifikasi bar. Field yang didukung:

              
              {
    "notification": {
        "android": {
            "alert": "hello, MTPush!",
            "title": "Tes Push",
            "builder_id": 3,
            "style": 1,
            "big_text": "isi big text",
            "inbox":JSONObject,
            "big_pic_path": "url gambar",
            "priority": 0,
            "category": "kategori string",
            "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": "nilai"
            }
        }
    }
}

            

iOS

Notifikasi APNs di iOS.

Konten notifikasi dikirim oleh MTPush ke server Apple APNs dan ditampilkan di perangkat iOS sebagai notifikasi sistem.

Field notifikasi sesuai spesifikasi APNs dan mendukung:

Contoh pengiriman server:

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

            

Pesan yang diterima klien:

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

            

hmos

Notifikasi di HarmonyOS ditampilkan oleh MTPush SDK sesuai gaya notifikasi bar. Field yang didukung:

Contoh:

              
              {
  "notification": {
    "hmos": {
      "alert": "Hi, MTPush!",
      "title": "",
      "category": "",
      "intent": {"url": ""},
      "badge_add_num": 1,
      "test_message": true,
      "receipt_id": "",
      "extras": {},
      "style": 0,
      "inbox_content": [],
      "push_type": 0,
      "extra_data": "",
      "display_foreground": "1"
    }
  }
}

            

Message

Pesan dalam aplikasi (pesan custom, pesan pass-through).

• Tidak tampil di notifikasi bar, SDK MTPush menerima pesan dan meneruskannya ke aplikasi.
• iOS menerima bagian ini melalui channel pesan in-app push (bukan APNS) saat aplikasi di foreground.

Field yang didukung:

Contoh:

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

            

Live_activity

Catatan: Pesan aktivitas real-time membutuhkan sertifikat iOS P8, yang sesuai dengan memilih "Konfigurasi Autentikasi Token" di Pengaturan metode autentikasi iOS WebPortal.

Body pesan aktivitas real-time mencakup field berikut:

iOS JSON Object

iOS alert JSON Object

• Pesan aktivitas real-time iOS untuk Engagelab Push diteruskan ke server Apple. Apple membatasi data update dinamis aktivitas real-time (ActivityKit) maksimal 4096 byte.
• Engagelab Push membatasi total panjang parameter "live_activity" untuk "iOS": { } maksimal 3584 byte. JPush memakai encoding UTF-8, satu karakter Tionghoa = 3 byte.

Contoh Push Aktivitas Real-time

attributes-type dan live_activity_id untuk aktivitas real-time dilaporkan dari SDK developer. Sebelum menggunakan aktivitas real-time, token push-to-start dan update-token perangkat harus dilaporkan. Lihat instruksi aktivitas real-time Apple.

• Membuat

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

  Tampilkan blok kode ini di jendela mengambang

• Memperbarui

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

  Tampilkan blok kode ini di jendela mengambang

Voip

Fungsi VOIP iOS. Tipe ini tidak bisa bersamaan dengan tipe pesan iOS lain. Lihat struktur parameter permintaan:

              
              { 
    "from": "push", 
    "to": { 
        "registration_id": [ "1a0018970a91da03de5" ] 
    }, 
    "request_id": "12345", 
    "custom_args": "12345", 
    "body": { 
        "platform": "ios", 
        "voip": { 
            "key": "value // Key/value custom apa pun yang akan diteruskan ke APP" 
        } 
    } 
}

            

Options

Opsi notifikasi push saat ini meliputi:

Multi_language

Field ini untuk fitur push multibahasa dari EngageLab Push. Anda bisa mengirim konten notifikasi yang disesuaikan untuk pengguna dengan bahasa berbeda. Dengan menentukan beberapa bahasa beserta konten pesan, judul, dan subtitle iOS pada permintaan push, Anda dapat mengirim notifikasi push yang sesuai dengan pengaturan bahasa pengguna.

Parameter Permintaan

• Catatan HarmonyOS: Untuk HarmonyOS, gunakan third_party_channel.hmos.distribution_new. Tidak terpengaruh oleh konfigurasi global.

Contoh Permintaan

              
                 Metode HTTP: POST
   URL Permintaan: /v4/grouppush atau /v4/push
   Format Data Permintaan: JSON
   Contoh Permintaan:
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
          "ios_subtitle": ""
        }
      }
    }
   }

            

Contoh Respons

              
              Respons Berhasil:
{
   
}

            

              
              
Respons Gagal:
{   
    "code": 400,  
    "data": "",
  "message": "Pesan Error"
}   

            

Third_party_channel

Field ini digunakan untuk mengisi informasi personalisasi channel produsen Android, key mendukung channel: xiaomi, huawei, meizu, oppo, vivo, fcm, honor, hmos. Bisa ada satu atau lebih bersamaan, KEY tiap vendor dapat berisi opsi berikut:

Parameter Permintaan

Untuk menyatukan strategi multi-channel vendor dan menyederhanakan logika konfigurasi, metode konfigurasi field distribution_new disesuaikan sebagai berikut. Konfigurasi level vendor lama Anda tetap berlaku, tetapi disarankan untuk beralih secara bertahap ke konfigurasi global untuk menghindari risiko kompatibilitas di masa depan. (Aturan baru berlaku mulai 2025.04.03):

• Prioritas Konfigurasi (Aturan Baru)
  • Prioritas Pertama: Konfigurasi global third_party_channel.distribution_new (Metode baru yang direkomendasikan)
    Contoh: "distribution_new": "pns_mtpush"
  • Prioritas Kedua: Konfigurasi level vendor third_party_channel.{vendor_key}.distribution_new (Metode kompatibel lama)
    Hanya berlaku saat konfigurasi global tidak diatur
  • Tanpa Konfigurasi: strategi default: pns_mtpush

Contoh Permintaan

              
              {
    "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": "*******",
            "big_picture_id": "",
            "small_picture_id": ""
        },
        "vivo": {
            "pushMode": 0
        },
        "hmos": {
            "distribution_new": "pns_mtpush"
        }
    }
}

            

Request_id

ID permintaan, field opsional yang ditentukan oleh pelanggan. Digunakan oleh klien untuk mengidentifikasi permintaan mana yang sedang dibuat dan dikembalikan pada respons.

Contoh Permintaan

              
              {
      "request_id":"12345678"
}

            

Contoh Pengembalian

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

            

Custom_args

Ditentukan oleh pelanggan, field opsional yang tidak dikembalikan pada respons dan dikembalikan pada callback.

Contoh Permintaan

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

            

Parameter Pengembalian

Pengembalian Berhasil

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

            

Pengembalian Gagal

Kode status http adalah 4xx atau 5xx dan body respons berisi field berikut:

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

            

Pengembalian Panggilan

Kode Status HTTP

Dokumen Referensi:HTTP-Status-Code

Kode Error

Batasan Push

Kode Multi-bahasa