API Tag Alias

API Perangkat digunakan untuk melakukan query, pengaturan, pembaruan, dan penghapusan informasi tag dan alias perangkat di sisi server. Saat menggunakannya, pastikan tag yang diatur di sisi server tidak ditimpa oleh sisi klien.

Jika Anda belum familiar dengan tag, logika alias menyarankan hanya menggunakan salah satu, baik di sisi klien atau server.
Jika digunakan di kedua sisi secara bersamaan, pastikan aplikasi Anda dapat menangani sinkronisasi tag dan alias.

Untuk informasi lebih lanjut tentang tag dan alias, silakan lihat dokumentasi API di platform klien terkait.

web-tag, alias

Aturan dan Batasan Penggunaan TAG

Batas Jumlah TAG: Maksimal 100.000 Tag per appkey.
Batas Panjang TAG: Maksimal 40 byte per Tag. Karakter valid: huruf (case sensitive), angka, garis bawah, dan karakter Tionghoa.
Batas Binding TAG per Perangkat: Maksimal 100 Tag per perangkat.
Batas Jumlah Perangkat per Tag: Maksimal 100.000 perangkat per Tag.

Jika Anda pelanggan paket berbayar dan ingin menyesuaikan batas AppKey, hubungi: Sales@engagelab.com

Aturan dan Batasan Penggunaan alias

Pemetaan Perangkat ke alias: Satu alias hanya untuk satu perangkat, dan satu perangkat hanya untuk satu alias (dalam satu appkey).
Batas Jumlah alias: Maksimal 100.000 alias per appkey.
Batas Panjang alias: Maksimal 40 byte. Karakter valid: huruf (case sensitive), angka, garis bawah, dan karakter Tionghoa.

Jika Anda pelanggan paket berbayar dan ingin menyesuaikan batas AppKey, hubungi: Sales@engagelab.com

Ringkasan API

API Perangkat digunakan untuk query, pengaturan, pembaruan, dan penghapusan tag dan alias perangkat di sisi server.

Terdiri dari tiga API utama: device, tag, alias:

device: query/pengaturan atribut perangkat (termasuk tag, alias)
tag: query/pengaturan/penghapusan tag perangkat
alias: query/pengaturan/penghapusan alias perangkat

registration ID adalah kunci utama yang digunakan:

registration_id perangkat didapat dari sisi klien, lihat dokumentasi API Web untuk detailnya.

Server tidak menyediakan API untuk mendapatkan registration ID perangkat; developer harus mendapatkannya dari klien dan menyimpannya di server developer.

Query Jumlah Tag di bawah AppKey

URL

GET /v4/tags_count

              
              GET /v4/tags_count

Tampilkan blok kode ini di jendela mengambang

Contoh Permintaan

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Contoh

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter

tags: String tag yang ingin di-query, wajib diisi, maksimal 1000 tag per query (tags=tag1&tags=tag2&tags=tag3)
platform: Platform yang ingin di-query, wajib diisi, nilai: android, ios

Contoh Respons

Sukses

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

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

Tampilkan blok kode ini di jendela mengambang

Gagal

{ "error": { "code": 21008, "message": "app_key bukan string 24 karakter atau tidak ada" } }

              
              {
    "error": {
        "code": 21008,
        "message": "app_key bukan string 24 karakter atau tidak ada"
    }
}

Tampilkan blok kode ini di jendela mengambang

Query alias dan tag perangkat

Dapatkan semua atribut perangkat saat ini, termasuk tags dan alias.

Endpoint

GET /v4/devices/{registration_id}

              
              GET /v4/devices/{registration_id}

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter: Tidak ada

Contoh Respons

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

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

Tampilkan blok kode ini di jendela mengambang

Set alias dan tag perangkat

Memperbarui atribut tags dan alias perangkat.

Endpoint

POST /v4/devices/{registration_id}

              
              POST /v4/devices/{registration_id}

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Body

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter

tags: Mendukung add, remove, atau string kosong. Jika tags kosong, maka hapus semua tag.
alias: Jika alias kosong, maka alias perangkat dihapus.

Contoh Respons

success

              
              success

Tampilkan blok kode ini di jendela mengambang

Gagal

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

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

Tampilkan blok kode ini di jendela mengambang

Hapus perangkat

Menghapus perangkat.

Endpoint

DELETE /v4/devices/{registration_id}

              
              DELETE /v4/devices/{registration_id}

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Contoh Respons

success

              
              success

Tampilkan blok kode ini di jendela mengambang

Gagal

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

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

Tampilkan blok kode ini di jendela mengambang

Query daftar tag

Dapatkan daftar semua tag aplikasi saat ini.

Endpoint

GET /v4/tags/

              
              GET /v4/tags/

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Contoh Respons

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

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

Tampilkan blok kode ini di jendela mengambang

Query binding perangkat dengan tag

Query apakah suatu perangkat berada di bawah tag tertentu.

Endpoint

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

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

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter

registration_id (wajib)

Contoh Respons

{"result": true/false}

              
              {"result": true/false}

Tampilkan blok kode ini di jendela mengambang

Update tag

Menambah atau menghapus perangkat untuk suatu tag.

Endpoint

POST /v4/tags/{tag_value}

              
              POST /v4/tags/{tag_value}

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Body

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter

add/remove: Masing-masing mendukung hingga 1000 perangkat.

Contoh Respons

success

              
              success

Tampilkan blok kode ini di jendela mengambang

Gagal

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

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

Tampilkan blok kode ini di jendela mengambang

Hapus Tag

Menghapus tag beserta hubungan tag dengan perangkat.

Endpoint

DELETE /v4/tags/{tag_value}

              
              DELETE /v4/tags/{tag_value}

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter

platform (opsional)

Contoh Respons

success

              
              success

Tampilkan blok kode ini di jendela mengambang

Gagal

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

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

Tampilkan blok kode ini di jendela mengambang

Query alias (binding dengan perangkat)

Dapatkan perangkat di bawah alias tertentu.

Endpoint

GET /v4/aliases/{alias_value}

              
              GET /v4/aliases/{alias_value}

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter

platform (opsional)

Contoh Respons

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

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

Tampilkan blok kode ini di jendela mengambang

Hapus Alias

Menghapus alias dan binding antara alias dengan perangkat.

Endpoint

DELETE /v4/aliases/{alias_value}

              
              DELETE /v4/aliases/{alias_value}

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter

platform (opsional)

Contoh Respons

success

              
              success

Tampilkan blok kode ini di jendela mengambang

Gagal

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

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

Tampilkan blok kode ini di jendela mengambang

Mendapatkan status online pengguna

Endpoint

POST /v4/devices/status/

              
              POST /v4/devices/status/

Tampilkan blok kode ini di jendela mengambang

Header

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

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

Tampilkan blok kode ini di jendela mengambang

Body

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

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

Tampilkan blok kode ini di jendela mengambang

Parameter

registration_ids: Maksimal 1000 registration_ids per query.
Anda perlu mengajukan AppKey yang sudah mengaktifkan layanan ini sebelum dapat menggunakan API ini.

Contoh Respons

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

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

Tampilkan blok kode ini di jendela mengambang

Penjelasan Data

online: true jika online ≤ 10 menit; false jika lebih dari 10 menit.
last_online_time: Jika online=true, field ini tidak ada. Jika online=false dan field ini tidak ada, berarti terakhir online dua hari lalu.

Query informasi kuota TAG/alias

Query informasi kuota AppKey, platform, dan tag tertentu. Maksimal 1.000 tag per query.

Endpoint

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

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

Tampilkan blok kode ini di jendela mengambang

Contoh

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=='

              
              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=='

Tampilkan blok kode ini di jendela mengambang

Respons Sukses

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

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

Tampilkan blok kode ini di jendela mengambang

Definisi Field:

totalTagQuota: Total kuota tag aplikasi.
useTagQuota: Jumlah kuota tag yang terpakai.
totalAliasQuota: Total kuota alias aplikasi.
useAliasQuota: Jumlah kuota alias yang terpakai.
tagUidQuota: Kuota jumlah perangkat per tag.
useUidQuota: Jumlah perangkat yang terikat pada setiap tag.

Respons Gagal

{ "error": { "code": 27002, "message": "Parameter tidak valid" } }

              
              {
    "error": {
        "code": 27002,
        "message": "Parameter tidak valid"
    }
}

Tampilkan blok kode ini di jendela mengambang

Kode Status HTTP

Referensi: Http-Status-Code

Kode Return Bisnis

Kode	Deskripsi	Penjelasan	HTTP Status Code
21004	Error Autentikasi	appkey tidak valid.	401
27000	Error Memori Sistem	Silakan coba lagi.	500
27001	Error Parameter	Informasi verifikasi kosong.	401
27002	Error Parameter	Parameter tidak valid.	400
27004	Error Parameter	Verifikasi gagal.	401
27005	Error Parameter	Format regisID tidak valid.	400
21008	Error Parameter	app_key bukan string 24 karakter atau tidak ada.	400
27010	Error Parameter	Alias sudah terhubung ke regid lain.	400
27011	Batas Sistem	Jumlah tag yang terhubung ke perangkat melebihi batas (maks. 100 tag per perangkat).	401
27012	Error Parameter	Tag yang ingin dihubungkan perangkat tidak ada.	401
27013	Error Parameter	Jumlah tag dalam aplikasi melebihi batas (maks. 100.000 tag).	401
27014	Batas Sistem	Jumlah perangkat pada tag melebihi batas (maks. 100.000 perangkat per tag).	401
27015	Error Parameter	Alias yang terhubung ke perangkat tidak ada.	401
27016	Batas Sistem	Jumlah alias dalam aplikasi melebihi batas (maks. 100.000 alias).	401
27017	Error Parameter	Panjang tag melebihi 40 karakter.	401