API Tag Alias

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

• Jika Anda belum memahami logika tag dan alias, disarankan untuk hanya menggunakan sisi klien atau sisi server saja.
• 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 merujuk ke dokumentasi API untuk platform klien yang sesuai.

• Android - tag, alias
• iOS - tag, alias
• HarmonyOS - 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 Mandarin.
• 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 Anda, silakan hubungi tim bisnis kami di Sales@engagelab.com.

Batasan dan Aturan Penggunaan Alias

• Pemetaan antara perangkat dan alias: Satu alias hanya dapat terhubung ke satu perangkat dan tidak dapat terhubung ke beberapa perangkat. Demikian pula, dalam cakupan satu AppKey, setiap perangkat hanya dapat dipetakan ke satu alias dan tidak dapat dipetakan ke beberapa 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 Mandarin.

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

Ringkasan API

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

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

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

Informasi penting lainnya yang diperlukan adalah registration ID:

registration_id perangkat diperoleh setelah integrasi klien. Untuk detailnya, lihat dokumentasi API untuk Android, iOS, dan HarmonyOS.

Sisi server tidak menyediakan API untuk memperoleh nilai registration_id perangkat. Developer perlu memperoleh registration ID di sisi klien dan mengunggahnya ke server developer untuk disimpan.

Menanyakan Jumlah Tag di Bawah AppKey

Endpoint

              
              GET /v4/tags_count

            

Contoh Permintaan

Request Header

              
              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: Menanyakan string tag yang ditentukan. Wajib. Hingga 1.000 tag dapat ditanyakan dalam satu permintaan (tags=tag1&tags=tag2&tags=tag3).
• platform: Menanyakan platform yang ditentukan. Wajib. Nilai yang valid adalah android, ios, dan hmos. Nilai lain tidak diperbolehkan.

Contoh Respons

• Respons yang berhasil mengembalikan objek JSON yang berisi field tagsCount, yaitu kumpulan pasangan key-value dengan key berupa nama tag dan value berupa jumlah 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"
  }
}

            

Menanyakan Alias dan Tag Perangkat

• Dapatkan semua atribut perangkat saat ini, termasuk tag dan alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Contoh Permintaan

Request Header

              
              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 ditemukan, nilainya adalah null; jika tidak, nilainya adalah nilai item statistik tersebut.

Menetapkan Alias dan Tag Perangkat

• Memperbarui atribut tertentu dari perangkat saat ini. Saat ini mendukung tags dan alias.

Endpoint

              
              POST /v4/devices/{registration_id}

            

Contoh Permintaan

Request Header

              
              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, semua tag akan dihapus. add/remove berarti menambahkan atau menghapus tag yang ditentukan.
• alias: Memperbarui atribut 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"
  }
}

            

Menanyakan Daftar Tag

• Dapatkan daftar semua tag untuk aplikasi saat ini.

Endpoint

              
              GET /v4/tags/

            

Contoh Permintaan

Request Header

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

            

Parameter Permintaan

• Tidak ada

Contoh Permintaan

Respons Berhasil

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

            

Data Respons

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

            

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

Menanyakan Hubungan Pengikatan antara Perangkat dan Tag

• Menanyakan apakah suatu perangkat berada di bawah sebuah tag.

Endpoint

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

            

Contoh Permintaan

Request Header

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

            

Parameter Permintaan

• tag_value: Wajib. Tag yang akan ditanyakan.
• 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 sebuah tag.

Endpoint

              
              POST /v4/tags/{tag_value}

            

Contoh Permintaan

Request Header

              
              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 ditanyakan.
• action: Jenis operasi, dengan dua opsi: add dan remove, yang menunjukkan apakah permintaan ini menambahkan atau menghapus perangkat.
• registration_ids: Nilai registration_id perangkat yang akan ditambahkan atau dihapus.
• add/remove: Mendukung hingga masing-masing 1.000 entri.

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

Hapus sebuah tag dan asosiasi antara tag tersebut dengan perangkat.

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Contoh Permintaan

Request Header

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

            

Parameter Permintaan

• tag_value: Wajib. Tag yang akan ditanyakan.
• platform: Opsional. Jika tidak ditentukan, semua platform digunakan secara default.

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

            

Menanyakan Alias (Hubungan Pengikatan dengan Perangkat)

              
              GET /v4/aliases/{alias_value}
Get the devices under the specified alias.

            

Menanyakan Alias

• Dapatkan perangkat di bawah alias yang ditentukan.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Contoh Permintaan

Request Header

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

            

Parameter Permintaan

• alias_value: Wajib. Alias yang akan ditanyakan.
• platform: Opsional. Jika tidak ditentukan, semua platform digunakan secara default.

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 ditemukan, nilainya adalah null; jika tidak, nilainya adalah nilai item statistik tersebut.

Menghapus Alias

Hapus sebuah alias dan hubungan pengikatan antara alias tersebut dengan perangkat.

              
              DELETE /v4/aliases/{alias_value}

            

Contoh Permintaan

Request Header

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

            

Parameter Permintaan

• alias_value: Wajib. Alias yang akan dihapus.
• platform: Opsional. Jika tidak ditentukan, semua platform digunakan secara default.

Contoh Respons

• Berhasil

              
              success

            

• Gagal

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

            

Mendapatkan Status Online Pengguna

Endpoint

              
              POST /v4/devices/status/

            

Contoh Permintaan

Request Header

              
              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 status online-nya dibutuhkan. Hingga 1.000 nilai registration_id didukung per kueri.
• API ini hanya dapat dipanggil untuk AppKey yang telah disetujui untuk fitur 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, berarti waktu online terakhir lebih dari dua hari yang lalu.
• Nilai regid yang tidak valid atau nilai regid yang bukan milik AppKey akan gagal divalidasi.

API Kueri Informasi Kuota TAG/Alias

Menanyakan informasi kuota yang terkait dengan AppKey, platform, dan tag yang ditentukan. Maksimal 1.000 tag dapat ditanyakan dalam satu permintaan.

Endpoint

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

            

Contoh Permintaan

              
              curl --location 'https://pushapi-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 untuk jumlah tag dalam aplikasi.
• useTagQuota: Menunjukkan kuota tag yang telah digunakan.
• totalAliasQuota: Menunjukkan total kuota untuk jumlah alias dalam aplikasi.
• useAliasQuota: Menunjukkan kuota alias yang telah digunakan.
• tagUidQuota: Menunjukkan kuota perangkat untuk 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 Return Bisnis