API Tag Alias

API Device digunakan untuk melakukan kueri, menetapkan, memperbarui, dan menghapus informasi tag dan alias perangkat di sisi server. Saat menggunakannya, harap berhati-hati agar tag yang ditetapkan di sisi server tidak tertimpa oleh sisi klien.

• Jika Anda belum familier dengan logika tag dan alias, disarankan untuk hanya menggunakan satu sisi saja: sisi klien atau sisi server.
• Jika kedua sisi digunakan secara bersamaan, pastikan aplikasi Anda dapat menangani sinkronisasi tag dan alias dengan benar.

Untuk informasi terperinci tentang tag dan alias, silakan lihat dokumentasi API untuk platform klien yang sesuai.

• web - tag, alias

Batasan dan Aturan Penggunaan TAG

• Batas jumlah TAG: Dalam satu appkey, Anda dapat membuat hingga 100.000 tag.
• Batas panjang TAG: Panjang maksimum setiap tag adalah 40 byte. Karakter yang valid mencakup huruf (peka huruf besar/kecil), angka, garis bawah, dan karakter Tiongkok.
• Batas pengikatan TAG perangkat: Setiap perangkat dapat diikat ke hingga 100 tag.
• Batas jumlah perangkat: Dalam satu tag, Anda dapat menambahkan hingga 100.000 perangkat.

Jika Anda adalah pengguna paket berbayar dan ingin menyesuaikan batas penggunaan untuk AppKey berbayar, silakan hubungi tim penjualan kami di Sales@engagelab.com.

Batasan dan Aturan Penggunaan alias

• Hubungan pemetaan perangkat dan alias: Satu alias hanya dapat terkait dengan satu perangkat dan tidak dapat terkait dengan beberapa perangkat. Demikian juga, setiap perangkat hanya dapat dipetakan ke satu alias dalam cakupan appkey dan tidak dapat dipetakan ke beberapa alias.
• Batas jumlah alias: Dalam satu appkey, Anda dapat membuat hingga 100.000 alias.
• Batas panjang alias: Panjang maksimum setiap alias adalah 40 byte. Karakter yang valid mencakup huruf (peka huruf besar/kecil), angka, garis bawah, dan karakter Tiongkok.

Jika Anda adalah pengguna paket berbayar dan ingin menyesuaikan batas penggunaan untuk AppKey berbayar, silakan hubungi tim penjualan kami di Sales@engagelab.com.

Ringkasan API

API Device digunakan untuk melakukan kueri, menetapkan, memperbarui, dan menghapus informasi tag dan alias perangkat di sisi server.

API ini mencakup tiga grup API: device, tag, dan alias. Di antaranya:

• device digunakan untuk mengkueri/menetapkan berbagai properti perangkat, termasuk tags dan alias;
• tag digunakan untuk mengkueri/menetapkan/menghapus tag perangkat;
• alias digunakan untuk mengkueri/menetapkan/menghapus alias perangkat.

Informasi penting lain yang perlu Anda ketahui adalah registration ID:

registration_id perangkat diperoleh setelah integrasi klien. Untuk detailnya, lihat dokumentasi Web API.

Sisi server tidak menyediakan API untuk memperoleh nilai registration_id perangkat. Pengembang perlu memperoleh registration ID dari sisi klien dan mengunggahnya ke server pengembang untuk disimpan.

Mengkueri Jumlah Tag di Bawah AppKey

Endpoint

              
              GET /v4/tags_count

            

Contoh Permintaan

Header Permintaan

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

            

Contoh Permintaan

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

            

Parameter Permintaan

• tags: Mengkueri string tag yang ditentukan. Wajib. Hingga 1000 tag dapat dikueri dalam satu permintaan (tags=tag1&tags=tag2&tags=tag3).
• platform: Mengkueri platform yang ditentukan. Wajib. Nilai yang valid adalah android, ios, hmos, dan web. Nilai lain tidak diperbolehkan.

Contoh Respons

• Respons yang berhasil akan mengembalikan objek JSON yang berisi field tagsCount, yaitu kumpulan pasangan key-value dengan key berupa nama tag dan value berupa jumlah perangkat di bawah tag tersebut.
• Jika permintaan gagal, objek JSON yang berisi informasi kesalahan akan dikembalikan. Field code menunjukkan kode kesalahan, dan field message menunjukkan pesan kesalahan.

Respons Berhasil

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

            

Respons Gagal

              
              {
  "error": {
    "code": 21008,
    "message": "app_key is not a 24 size string or does not exist"
  }
}

            

Mengkueri Alias dan Tag Perangkat

• Mendapatkan semua properti perangkat saat ini, termasuk tags dan alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Contoh Permintaan

Header Permintaan

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

            

Parameter Permintaan

• registration_id: Wajib. registration_id perangkat.

Contoh Respons

Respons Berhasil

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

            

Data Respons

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

            

• Jika item statistik tidak dapat ditemukan, nilainya adalah null; jika tidak, nilainya adalah nilai item statistik tersebut.

Menetapkan Alias dan Tag Perangkat

• Memperbarui properti yang ditentukan dari perangkat saat ini. Saat ini mendukung tags dan alias.

Endpoint

              
              POST /v4/devices/{registration_id}

            

Contoh Permintaan

Header Permintaan

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

            

Data Permintaan

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

            

Parameter Permintaan

• registration_id: Wajib. registration_id perangkat.
• tags: Mendukung add, remove, atau string kosong. Saat parameter tags berupa string kosong, artinya semua tag akan dihapus. add/remove digunakan untuk menambahkan atau menghapus tag yang ditentukan.
• alias: Memperbarui properti alias perangkat. Saat alias berupa string kosong, alias perangkat yang ditentukan akan dihapus.

Contoh Respons

Respons Berhasil

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

            

Data Respons

              
              success

            

Respons Gagal

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

            

Mengkueri Daftar Tag

• Mendapatkan daftar semua tag dalam aplikasi saat ini.

Endpoint

              
              GET /v4/tags/

            

Contoh Permintaan

Header Permintaan

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

            

Parameter Permintaan

• Tidak ada

Contoh Respons

Respons Berhasil

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

            

Data Respons

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

            

• Jika item statistik tidak dapat ditemukan, nilainya adalah null; jika tidak, nilainya adalah nilai item statistik tersebut.

Mengkueri Hubungan Pengikatan Antara Perangkat dan Tag

• Mengkueri apakah sebuah perangkat termasuk dalam suatu tag.

Endpoint

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

            

Contoh Permintaan

Header Permintaan

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

            

Parameter Permintaan

• tag_value: Wajib. Tag yang akan dikueri.
• registration_id: Wajib. registration_id perangkat.

Contoh Respons

Respons Berhasil

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

            

Data Respons

              
              {"result": true}

            

Memperbarui Tag

• Menambahkan atau menghapus perangkat untuk suatu tag.

Endpoint

              
              POST /v4/tags/{tag_value}

            

Contoh Permintaan

Header Permintaan

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

            

Data Permintaan

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

            

Parameter Permintaan

• tag_value: Wajib. Tag yang akan dikueri.
• action: Jenis operasi, dengan dua opsi: "add" dan "remove", yang menunjukkan apakah permintaan ini untuk menambah atau menghapus.
• registration_ids: Nilai registration_id perangkat yang akan ditambahkan atau dihapus.
• add/remove: Masing-masing mendukung hingga 1000 item.

Contoh Respons

Respons Berhasil

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

            

Data Respons

              
              success

            

Respons Gagal

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

            

Menghapus Tag

Menghapus sebuah tag dan asosiasi antara tag tersebut dengan perangkat.

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Contoh Permintaan

Header Permintaan

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

            

Parameter Permintaan

• tag_value: Wajib. Tag yang akan dikueri.
• platform: Opsional. Jika dihilangkan, default-nya adalah semua platform.

Contoh Respons

Respons Berhasil

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

            

Data Respons

              
              success

            

Respons Gagal

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

            

Mengkueri Alias (Hubungan Pengikatan dengan Perangkat)

              
              GET /v4/aliases/{alias_value}
Dapatkan perangkat di bawah alias yang ditentukan.

            

Mengkueri Alias

• Mendapatkan perangkat di bawah alias yang ditentukan.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Contoh Permintaan

Header Permintaan

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

            

Parameter Permintaan

• alias_value: Wajib. Alias yang akan dikueri.
• platform: Opsional. Jika dihilangkan, default-nya adalah semua platform.

Contoh Respons

Respons Berhasil

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

            

Data Respons

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

            

• Jika item statistik tidak dapat ditemukan, nilainya adalah null; jika tidak, nilainya adalah nilai item statistik tersebut.

Menghapus Alias

Menghapus sebuah alias dan hubungan pengikatan antara alias dengan perangkat.

              
              DELETE /v4/aliases/{alias_value}

            

Contoh Permintaan

Header Permintaan

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

            

Parameter Permintaan

• alias_value: Wajib. Alias yang akan dihapus.
• platform: Opsional. Jika dihilangkan, default-nya adalah semua platform.

Contoh Respons

• Berhasil

              
              success

            

• Gagal

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

            

Mendapatkan Status Online Pengguna

Endpoint

              
              POST /v4/devices/status/

            

Contoh Permintaan

Header Permintaan

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

            

Data Permintaan

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

            

Parameter Permintaan

• registration_ids: Nilai registration_id pengguna yang memerlukan status online. Hingga 1000 nilai registration_id didukung per kueri.
• API ini hanya dapat dipanggil untuk AppKey yang telah mengajukan dan mengaktifkan layanan ini.

Contoh Respons

Respons Berhasil

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

            

Data Respons

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

            

Data Respons

• online
  • true: online dalam 10 menit terakhir
  • false: tidak online dalam 10 menit terakhir
• last_online_time
  • saat online bernilai true, field ini tidak dikembalikan
  • saat online bernilai false dan field ini tidak dikembalikan, artinya waktu online terakhir lebih dari dua hari yang lalu
• Untuk nilai regid yang tidak valid atau nilai regid yang tidak termasuk dalam appkey, validasi akan gagal.

API Kueri Informasi Kuota TAG/alias

Mengkueri informasi kuota terkait untuk AppKey, platform, dan tag yang ditentukan. Tidak lebih dari 1000 tag dapat dikueri dalam satu waktu.

Endpoint

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

            

Contoh Permintaan

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

            

Respons Berhasil

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

            

Deskripsi Field Respons:

• totalTagQuota: Menunjukkan total kuota jumlah tag dalam aplikasi.
• useTagQuota: Menunjukkan kuota tag yang telah digunakan.
• totalAliasQuota: Menunjukkan total kuota jumlah alias dalam aplikasi.
• useAliasQuota: Menunjukkan kuota alias yang telah digunakan.
• tagUidQuota: Menunjukkan kuota jumlah perangkat di bawah satu tag.
• useUidQuota: Menunjukkan jumlah perangkat yang terikat pada setiap tag.

Respons Gagal

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

            

Kode Status HTTP

Dokumen referensi: Http-Status-Code

Kode Respons Bisnis