API Registrasi Perangkat

API Registrasi Perangkat menyediakan antarmuka sisi server untuk mendaftarkan token perangkat dan mendapatkan registration_id di AppPush.

Mendapatkan registration_id melalui Token

API ini memungkinkan server mendaftarkan pengguna AppPush dengan FCM Tokens atau APNs Device Tokens dan memperoleh registration_id yang dibuat oleh EngageLab. Setelah memperoleh registration_id, Anda dapat menggunakannya untuk push yang ditujukan kepada pengguna tertentu serta APIs terkait perangkat seperti tag dan alias.

Batasan penggunaan

• Setiap permintaan dapat mendaftarkan 1–500 Tokens.
• Satu permintaan hanya boleh berisi Tokens dari satu platform: satu batch FCM Tokens atau satu batch APNs Device Tokens. Tokens FCM dan APNs tidak dapat dicampur dalam permintaan yang sama.
• Permintaan berulang dengan aplikasi, platform, dan Token yang sama bersifat idempoten. Pengguna duplikat tidak dibuat dan registration_id yang sudah ada akan dikembalikan.
• Hasil dikembalikan dalam urutan yang sama dengan Tokens pada permintaan.

Endpoint

              
              POST /v4/devices/token/registration_id

            

URL permintaan lengkap terdiri dari Base URL pusat data aplikasi dan path di atas. Untuk alamat pusat data dan autentikasi, lihat Ringkasan REST API.

Header permintaan

              
              Content-Type: application/json
Accept: application/json
Authorization: Basic base64_auth_string

            

Parameter permintaan

Aturan format Token

• FCM Token: Harus berupa string tidak kosong dengan panjang maksimal 400 karakter. Hanya karakter ASCII yang dapat dicetak (0x21–0x7E) yang diizinkan. Spasi, baris baru, serta spasi di awal atau akhir tidak diizinkan.
• APNs Device Token: Harus berupa string heksadesimal tidak kosong dengan jumlah karakter genap dan panjang maksimal 400 karakter. Hanya 0-9, a-f, dan A-F yang diizinkan. Spasi, tanda kurung sudut, dan pemisah lain tidak diizinkan.

API ini hanya memvalidasi format Token dan tidak dapat memastikan apakah Token masih valid. Validitas Token ditentukan oleh hasil push FCM atau APNs yang sebenarnya.

Contoh permintaan Android (FCM)

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "android",
    "tokens": [
      "fcm_token_1",
      "fcm_token_2"
    ]
  }'

            

Contoh permintaan iOS (APNs)

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "ios",
    "tokens": [
      "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ],
    "apns_production": true
  }'

            

Parameter respons

Kode hasil individual:

Contoh respons berhasil

Pada registrasi pertama, is_new bernilai true:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": true,
      "code": 0
    },
    {
      "token": "fcm_token_2",
      "registration_id": "13065ffa4e1a6cc91c4",
      "is_new": true,
      "code": 0
    }
  ]
}

            

Jika Token yang sudah terdaftar dikirimkan kembali, registration_id yang sama dikembalikan dan is_new bernilai false:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    }
  ]
}

            

Contoh kegagalan satu Token

Jika satu Token dalam batch memiliki format tidak valid atau gagal didaftarkan, item tersebut mengembalikan kesalahan melalui code dan message, sedangkan Tokens lainnya tetap dapat diproses secara normal. Pada contoh berikut, Token kosong gagal dalam validasi format:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    },
    {
      "token": "",
      "is_new": false,
      "code": 21003,
      "message": "invalid fcm token format"
    }
  ]
}

            

Contoh permintaan gagal

Jika parameter permintaan secara keseluruhan tidak valid, API mengembalikan HTTP 400. Misalnya, permintaan iOS tanpa apns_production akan mengembalikan:

              
              {
  "error": {
    "code": 21003,
    "message": "apns_production is required for ios"
  }
}

            

Kesalahan permintaan yang umum:

• platform bukan android atau ios;
• tokens kosong atau berisi lebih dari 500 item;
• permintaan Android menyertakan apns_production;
• permintaan iOS tidak menyertakan apns_production.

Respons API

Kode status HTTP

Lihat Kode Status HTTP.

Kode kesalahan

Tabel berikut menampilkan kode kesalahan pada tingkat permintaan. Dalam permintaan batch, kesalahan untuk satu Token dikembalikan melalui results[].code dan results[].message dan tidak memengaruhi pemrosesan Tokens lainnya.