Panduan API

Atur Identifikasi Pengguna

Versi yang Didukung

Identitas email dan phone didukung sejak: 2.1.0

Definisi Antarmuka

• identifyAccount(user);
  • Deskripsi Antarmuka:
    • Mengatur identifikasi pengguna, misal nomor kartu anggota.
  • Deskripsi Parameter
    • identity: ID identifikasi pengguna. Key mendukung 4 nilai: user_id, anonymous_id, email, phone. Berikan minimal satu, tidak perlu mengisi semuanya
    • completion: Callback
  • Aturan Identifikasi Pengguna
    • user_id: tidak kosong setelah spasi di awal dan akhir dihapus, maksimal 255 karakter, tidak boleh bernilai 0, null, undefined, nan (tidak peka huruf besar/kecil)
    • anonymous_id: tidak kosong setelah spasi di awal dan akhir dihapus, maksimal 256 karakter
    • email: alamat email pengguna, tidak kosong setelah spasi di awal dan akhir dihapus, maksimal 256 karakter, harus berformat email yang valid, misal user@example.com
    • phone: nomor telepon pengguna, harus berformat E.164 yang menyertakan kode negara atau wilayah, misal +8613800000000
    • Jika ada field yang tidak memenuhi aturan, pemanggilan ini tidak mengirim permintaan, completion mengembalikan -1, dan message berisi alasan spesifiknya

Contoh Pemanggilan

              
                  let user = {completion: (code, message)=>{}, identity:{"user_id":"value","anonymous_id":"value","email":"user@example.com","phone":"+8613800000000"}}
    window.MAInterface.identifyAccount(user)

            

Di sini email dan phone digunakan untuk pencocokan identitas pengguna dan dapat mengembalikan EUID baru; keduanya tidak dapat saling menggantikan dengan informasi kontak yang diatur melalui "Atur Informasi Kontak Pengguna" (setUserContact).

Dapatkan EUID

Definisi Antarmuka

• + EUID()
  • Deskripsi Antarmuka:
    • Mendapatkan EUID dari EngageLab MA

Contoh Pemanggilan

              
                  window.MAInterface.EUID((code,euid)=>{
        console.log(code, euid)
    })

            

Atur Informasi Kontak Pengguna

Definisi Antarmuka

• setUserContact(user)
  • Deskripsi Antarmuka:
    • Mendukung pengaturan beberapa nilai metode kontak sekaligus. Key adalah nama metode kontak, value adalah nilai metode kontak. Saat ini mendukung 4 jenis metode kontak: email, mobile_phone, landline_phone, whatsapp_phone
  • Deskripsi Parameter
    • contacts: Informasi kontak pengguna
    • completion: Callback

Contoh Pemanggilan

              
                    let user = {
          completion: (code, message)=>{ },
          contacts: {}
       }
      user.contacts["Nama Metode Kontak"] = "Nilai Metode Kontak"   // Contoh: mobile_phone=18800000000
      window.MAInterface.setUserContact(user)

            

Atur ID Kontak Channel

Versi yang Didukung

Didukung sejak: 2.1.0

Definisi Antarmuka

• setChannelValue(channelId, values, completion)
  • Deskripsi Antarmuka:
    • Mengatur RID atau Token untuk channel Push yang dikonfigurasi di konsol MA (misal WebPush, Push pihak ketiga).
    • Harus dipanggil setelah SDK berhasil diinisialisasi; jika tidak, completion mengembalikan -1.
    • Jika RID atau Token berubah, panggil antarmuka ini lagi untuk memperbarui.
  • Deskripsi Parameter
    • channelId: ID channel Push yang dikonfigurasi di konsol MA, harus berupa bilangan bulat lebih besar dari 0
    • values: array nilai ID kontak channel (misal RID atau Token), tidak boleh kosong, dan elemen array juga tidak boleh berupa string kosong
    • completion: Callback, code 0 berarti berhasil

Contoh Pemanggilan

              
                 window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message)=>{})

            

Sakelar Pengumpulan Data

Versi yang Didukung

Didukung sejak: 2.2.0

Deskripsi Fungsi

Aplikasi mengaktifkan atau menonaktifkan pengumpulan data MA SDK berdasarkan hasil persetujuan pengguna, untuk memenuhi persyaratan kepatuhan bahwa data perilaku tidak boleh dilaporkan setelah pengguna menolak atau menarik persetujuan.

• Nonaktif: menghentikan pembuatan, penyimpanan cache, dan pelaporan event, properti pengguna, UTM, dan informasi perangkat. Inisialisasi, mendapatkan EUID/RID, mengatur identifikasi pengguna, mengatur informasi kontak, dan mengatur ID kontak channel tetap dapat digunakan seperti biasa.
• Aktif: melanjutkan pengumpulan; data selama periode nonaktif tidak dikirim ulang.
• Default aktif: jika tidak diatur, default aktif, konsisten dengan perilaku sebelum upgrade.
• Disimpan lokal: status disimpan secara lokal di browser (localStorage) dan tetap tersimpan setelah halaman dimuat ulang atau dibuka kembali. Menghapus data situs akan mengembalikan ke default.
• Sakelar ditentukan oleh aplikasi: SDK tidak menentukan wilayah pengguna, tidak menampilkan jendela persetujuan, dan tidak membaca platform manajemen persetujuan (CMP).

Definisi Antarmuka

• init({ dataCollectionEnabled })

  • Deskripsi Antarmuka: mengatur status sakelar pada peluncuran pertama saat inisialisasi.
  • Deskripsi Parameter: true aktif; false nonaktif; jika tidak diisi, default aktif.

• setDataCollectionEnabled(enabled, completion)

  • Deskripsi Antarmuka: mengaktifkan atau menonaktifkan pengumpulan data, berlaku segera dan disimpan secara lokal.
  • Deskripsi Parameter:
    • enabled: true aktif, false nonaktif
    • completion: Callback, code 0 berarti berhasil; mengembalikan -1 jika parameter bukan boolean
  • Catatan Pemanggilan:
    • Jika nilai yang diatur sama dengan status saat ini, proses peralihan tidak dipicu, sehingga menyinkronkan pilihan pengguna pada setiap pemuatan halaman tidak menimbulkan efek tambahan.
    • Saat beralih dari aktif ke nonaktif, SDK segera mencoba mengirim satu kali data yang sudah dihasilkan sebelum peralihan (disertai event akhir sesi saat ini), tidak mencoba ulang jika gagal, lalu menghapus cache lokal.
    • Saat beralih dari nonaktif ke aktif, SDK melaporkan informasi perangkat dan memulai sesi baru (melaporkan el_session_start dan el_page_view halaman saat ini).
    • Selama nonaktif, atribusi konversi dari klik notifikasi WebPush tidak lagi dihitung.

• isDataCollectionEnabled()

  • Deskripsi Antarmuka: mengembalikan status sakelar saat ini; hanya membaca status lokal, tidak melakukan permintaan jaringan.
  • Deskripsi Nilai Kembali: true aktif, false nonaktif; mengembalikan true jika belum pernah disimpan. Nilai kembali menunjukkan status sakelar SDK, bukan berarti pengguna telah menyetujui.

Perilaku Setiap Antarmuka Selama Nonaktif

Contoh Pemanggilan

              
                // Saat inisialisasi, berikan nilai dataCollectionEnabled secara dinamis sesuai status persetujuan pengguna. Jangan hardcode konfigurasi, agar setiap inisialisasi tidak mengatur ulang status ke nilai yang ditulis tetap
  window.MAInterface.init({
    appKey: "your appKey",
    dataCollectionEnabled: false,
    completion: (code, msg) => {}
  })

  // Setelah pengguna memberikan persetujuan
  window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {})

  // Setelah pengguna menarik persetujuan
  window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {})

  // Periksa status
  const enabled = window.MAInterface.isDataCollectionEnabled()

            

Atur Properti UTM

Definisi Antarmuka

• setUtmProperties(attrs:any)
  • Deskripsi Antarmuka:
    • Properti UTM adalah properti event standar. Jika pengembang dapat mengidentifikasi dari iklan mana pengguna diarahkan untuk mengakses App, disarankan untuk mengatur informasi UTM; kami akan menyertakan parameter ini saat pelaporan event. Saat ini properti UTM yang dapat diatur meliputi:
      • utm_source: Sumber kampanye iklan
      • utm_medium: Media kampanye iklan
      • utm_term: Kata kunci kampanye iklan
      • utm_content: Konten kampanye iklan
      • utm_campaign: Nama kampanye iklan
      • utm_id: ID kampanye iklan

Contoh Pemanggilan

              
                 window.MAInterface.setUtmProperties({"utm_source":"value1"})

            

Atur Properti Pengguna

Mengatur nilai properti pengguna. Jika properti pengguna belum ada, sistem akan membuatnya secara otomatis.

Timpa dan Perbarui Properti Pengguna

• setProperty(user, completion)
  • Deskripsi Antarmuka:
    • Menimpa dan memperbarui nilai properti pengguna
    • Hanya data terakhir yang dilaporkan yang disimpan, menimpa data historis, misal level keanggotaan pengguna.
    • Konten properti pengguna disimpan dalam sebuah object. Key adalah nama properti pengguna dan harus berupa string; Value adalah isi properti pengguna, mendukung tipe string, number, Array, object, dan object_array.
    • Untuk value bertipe Array, saat ini hanya mendukung elemen bertipe string; array yang seluruh elemennya object diperlakukan sebagai object_array; array yang mencampur object dengan tipe lain tidak valid.
    • Jika suatu properti pengguna sudah ada sebelumnya, maka akan ditimpa; jika belum ada, akan dibuat. Aturan pembaruan object dan object_array dijelaskan di bawah.
  • Contoh Pemanggilan:

              
                 window.MAInterface.setProperty({key:"value"}, (code, message)=>{})

            

Aturan object / object_array

Didukung sejak: 2.1.0

• object adalah objek biasa yang tidak kosong, misal { city: "Singapore", score: 100 }; object_array adalah array yang seluruh elemennya berupa objek biasa yang tidak kosong.
• Nama sub-field harus berupa string tidak kosong dan tidak boleh mengandung . atau $; nilai sub-field mendukung string, number, dan array string, tidak mendukung object atau object_array bersarang lebih lanjut.
• object menggunakan semantik penggabungan sub-field: saat diatur lagi, hanya sub-field yang dikirim kali ini yang diperbarui, sub-field yang tidak dikirim tetap tidak berubah; mengirim null sebagai nilai sub-field berarti menghapus sub-field tersebut.
• object_array menggunakan semantik penggantian keseluruhan: saat diatur lagi, array baru menggantikan seluruh array lama dan urutan array dipertahankan. Saat pertama kali membuat object_array, kirim array objek yang tidak kosong.
• Tipe sub-field harus sesuai dengan definisi properti pengguna tersebut di konsol MA; jika tidak sesuai, server mengembalikan kegagalan.

              
                 window.MAInterface.setProperty({
       profile: { city: "Singapore", score: 100 },
       addresses: [
           { id: "home", city: "Singapore" },
           { id: "office", city: "Tokyo" }
       ]
   }, (code, message)=>{})

   // Hanya memperbarui profile.score, profile.city tetap tidak berubah
   window.MAInterface.setProperty({ profile: { score: 200 } }, (code, message)=>{})

            

Tambah Nilai Properti Pengguna

• increaseProperty(user, completion)
  • Deskripsi Antarmuka:
    • Melakukan penambahan (akumulasi) pada nilai properti pengguna.
    • Menambahkan nilai pada beberapa properti pengguna bertipe numerik. Semua data yang dilaporkan diakumulasikan, misal jumlah konsumsi kumulatif.
    • Antarmuka ini hanya dapat dipanggil untuk properti pengguna bertipe number; selain itu akan diabaikan. Jika properti pengguna ini belum ada sebelumnya, nilai awal dianggap 0.
  • Contoh Pemanggilan:

              
               window.MAInterface.increaseProperty({key:1}, (code, message)=>{})

            

Tambah Elemen Properti Pengguna

• addProperty(key, content completion)
  • Deskripsi Antarmuka:
    • Menambahkan nilai pada properti pengguna.
    • Elemen himpunan dapat terus ditambahkan dan dideduplikasi saat disimpan. Jika sudah ada ABC dan ditambahkan CD, hasil akhirnya ABCD, misal berita yang disukai pengguna.
    • Menambahkan beberapa nilai ke properti bertipe Array. Elemen Array harus berupa string; jika tidak, akan diabaikan. Jika properti pengguna yang akan ditambahkan (append) belum ada sebelumnya, Array kosong akan diinisialisasi.
  • Contoh Pemanggilan:

              
               window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})

            

Hapus Elemen Properti Pengguna

• removeProperty(key, content completion)
  • Deskripsi Antarmuka:
    • Menghapus satu atau beberapa nilai dari properti bertipe array.
    • Menghapus beberapa nilai dari properti bertipe Array. Elemen Array harus berupa string; jika tidak, akan diabaikan. Jika properti pengguna yang akan di-removeEventListAttrValue belum ada sebelumnya, tidak ada efek.
  • Contoh Pemanggilan:

              
               window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})

            

Operasi Elemen object_array

Versi yang Didukung

Didukung sejak: 2.1.0

Penggunaan berikut hanya untuk properti pengguna bertipe object_array, yang menemukan elemen dalam array melalui sub-field penanda unik. Saat addProperty dan removeProperty menerima array string, keduanya tetap digunakan untuk array string dan perilakunya tidak berubah.

• addProperty(key, object, completion)
  • Deskripsi Antarmuka:
    • Jika parameter kedua berupa satu object (bukan array), satu elemen ditambahkan ke akhir object_array tanpa memengaruhi elemen yang sudah ada.
    • object harus berupa objek tidak kosong; aturan sub-field sama dengan tipe object, tidak mendukung object atau object_array bersarang.
    • Jika properti tersebut belum didefinisikan di konsol MA, server secara otomatis membuatnya sebagai properti bertipe object_array dan menulis elemen ini; jika properti sudah didefinisikan tetapi pengguna saat ini belum memiliki nilai, array akan dibuat dengan satu elemen ini.
  • Contoh Pemanggilan:

              
               window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})

            

• updateProperty(key, content, completion)
  • Deskripsi Antarmuka:
    • Menemukan satu elemen dalam object_array melalui sub-field penanda unik, lalu memperbarui sub-field elemen tersebut secara gabungan (merge).
    • Struktur content adalah { $identifier_key, $identifier_value, $new_object }:
      • $identifier_key: nama sub-field yang digunakan untuk menemukan elemen; sub-field ini harus sudah didefinisikan di konsol MA dengan tipe string atau number
      • $identifier_value: nilai pencocokan, bertipe string atau number; jika lebih dari satu elemen cocok, pembaruan diterapkan ke semua elemen tersebut
      • $new_object: sub-field yang akan diperbarui, harus berupa objek tidak kosong dan tidak boleh mengandung sub-field yang sesuai dengan$identifier_key; sub-field yang tidak dikirim tetap tidak berubah, mengirim null sebagai nilai sub-field berarti menghapus sub-field tersebut
    • Jika tidak ada elemen yang cocok dalam array, atau sub-field tidak sesuai dengan definisi properti, server mengembalikan kegagalan dan tidak mengubah elemen lain; jika lebih dari satu elemen cocok, pembaruan yang sama diterapkan ke semua elemen yang cocok.
    • Jika properti tersebut belum didefinisikan, server mengembalikan kegagalan (55004); jika properti sudah didefinisikan tetapi pengguna saat ini belum memiliki nilai properti tersebut, server mengembalikan code=0 tanpa melakukan perubahan.
  • Contoh Pemanggilan:

              
               // Memperbarui city elemen dengan id home menjadi Tokyo, dan menghapus sub-field zip
 window.MAInterface.updateProperty("addresses", {$identifier_key:"id", $identifier_value:"home", $new_object:{city:"Tokyo", zip:null}}, (code, message)=>{})

            

• removeProperty(key, content, completion)
  • Deskripsi Antarmuka:
    • Jika parameter kedua berupa { $identifier_key, $identifier_value }, elemen yang cocok dalam object_array akan dihapus secara keseluruhan (jika lebih dari satu elemen cocok, semua elemen yang cocok akan dihapus); content hanya boleh berisi dua field ini.
    • Persyaratan $identifier_key dan$identifier_value sama dengan updateProperty.
    • Jika properti tersebut belum didefinisikan, server mengembalikan kegagalan (55004); jika pengguna saat ini tidak memiliki nilai properti tersebut atau tidak ada elemen yang cocok, server mengabaikan permintaan ini dan mengembalikan code=0; jika lebih dari satu elemen cocok, semua elemen yang cocok akan dihapus.
  • Contoh Pemanggilan:

              
               // Menghapus elemen dengan id office
 window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})

            

Hapus Properti Pengguna

Definisi Antarmuka

• deleteProperty(key, completion)
  • Deskripsi Antarmuka:
    • Menghapus seluruh isi value dari suatu properti pengguna.
    • Jika properti pengguna ini belum ada sebelumnya, akan langsung diabaikan.

Contoh Pemanggilan

              
               window.MAInterface.deleteProperty("key", (code, message)=>{})

            

Atur Waktu Kedaluwarsa Sesi

Definisi Antarmuka

• setSessionTimeout(time)
  • Deskripsi Antarmuka:
    • Mengatur waktu kedaluwarsa sesi. Saat halaman berada di latar belakang, penghitungan waktu kedaluwarsa sesi dimulai; jika melebihi waktu yang ditetapkan (default 30 menit), sesi ini akan diakhiri.

Contoh Pemanggilan

              
               window.MAInterface.setSessionTimeout(60)

            

Atur Durasi Tinggal di Halaman

Definisi Antarmuka

• setPageStayTime(time)
  • Deskripsi Antarmuka:
    • Mengatur durasi waktu tinggal di halaman.
    • Penghitungan waktu dimulai setelah halaman diakses. Jika pengguna tetap berada di halaman tersebut selama time detik tanpa berpindah, event ini akan dilaporkan.
    • Secara default dilaporkan pada 6 titik waktu: 5 detik, 30 detik, 60 detik, 2 menit, 5 menit, dan 10 menit. Pengembang dapat memanggil antarmuka ini untuk menambah titik waktu lainnya

Contoh Pemanggilan

              
               window.MAInterface.setPageStayTime(60)

            

Laporkan Event

Jika event belum ada dan langsung dilaporkan, sistem akan membuat event tersebut secara otomatis

Definisi Antarmuka

• onEvent(event)
  • Deskripsi Antarmuka:
    • Melaporkan event
  • Deskripsi Parameter
    • event: Event yang dilaporkan. name adalah nama event, properties adalah informasi properti event, dengan Key sebagai nama properti dan value sebagai nilai properti

Contoh Pemanggilan

              
                 let event = {name:"name", properties:{key:"value"}}
    window.MAInterface.onEvent(event)