Panduan Integrasi Web SDK

Dokumen ini merupakan panduan integrasi standar untuk MA Web SDK.

Deskripsi Produk

MA Web SDK menyediakan fungsi pengumpulan dan pelaporan data, digunakan untuk skenario seperti pembuatan EUID, pengaturan properti pengguna, dan pelaporan event

Pilihan Integrasi

MA Web SDK mendukung 2 mode integrasi: digunakan bersama WebPush, atau hanya menggunakan MA Web SDK secara mandiri

• Bersama WebPush: saat mengintegrasikan modul EngageLab WebPush, aktifkan fungsi MA, maka MA SDK akan dimuat secara otomatis
• Hanya MA Web SDK: integrasikan alamat MA SDK langsung ke website Anda, tanpa fungsi WebPush

Bersama WebPush

Persiapan Sebelum Integrasi

• Anda juga perlu mengintegrasikan modul WebPush
• Siapkan nama domain layanan web HTTPS yang dapat diakses. Setelah integrasi, halaman harus diuji dan di-debug di bawah nama domain ini. Push web offline tidak mendukung debug lokal maupun HTTP.
• Masuk ke Engagelab WebPush, lalu pada halaman [Pengaturan Integrasi] - [Nama Domain Website], isi nama domain layanan web HTTPS Anda.

Mendapatkan Informasi Aplikasi

Anda perlu membuat aplikasi pada konsol WebPush. Setelah berhasil dibuat, AppKey akan otomatis dihasilkan sebagai identitas aplikasi tersebut. Untuk detailnya, lihat Dokumen Pengaturan Aplikasi.

Konfigurasi Sumber Data MA

Pada proyek MA, buka Sumber Data - Tambah Sumber Data - Web, pilih "Gunakan bersama WebPush", pilih aplikasi yang telah dibuat di WebPush dari daftar drop-down, lalu simpan

Akses SDK

Masuk ke Konsol, unduh SDK, dan sertakan js berikut di setiap halaman:

              
              <script type="text/javascript" src="./WebSDK.3.3.4.js"></script>

            

Tips

Setelah mengimpor js ini, berikan properti maOpen dengan nilai true untuk mengaktifkan konfigurasi MA, sehingga Anda dapat menggunakan API dan fungsi terkait MA

Inisialisasi SDK

              
                  //  Inisialisasi (aktifkan MA)
  MTpushInterface.init({
    appkey: "", // Wajib diisi, lihat "Mendapatkan Informasi Aplikasi" di atas
    user_str: "adminDemo", // Wajib diisi, penanda pengguna untuk mengidentifikasi user
    swUrl: "url", // Default: "/sw.min." + sdkEnv.version + ".js". Konfigurasi ini adalah alamat file server worker; domain harus domain saat ini, dan path menentukan cakupan server worker.
    debugMode: true,// Atur apakah mode debug diaktifkan. true akan mencetak lebih banyak log; false hanya mengeluarkan log level w dan e.
    channel: "default-channel",// Nama channel, nilai default: default-channel
    appName: "string",// Digunakan untuk mengatur nama website, dipakai saat pelaporan
    maOpen: true, // Aktifkan sakelar untuk menggunakan fungsi MA
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },// Atur identitas pengguna saat inisialisasi MA. Didukung sejak versi 3.3.4, berlaku untuk perusahaan yang menyediakan layanan MA hanya bagi anggota yang sudah login
    maDataCollectionEnabled: false, // Status awal pengumpulan data MA; jika tidak diisi, default aktif. Didukung sejak WebPush SDK 3.3.9
    maCompletion: (code, msg) => {// Callback inisialisasi MA
                if (code === 0) {
                    console.log("✅MA SDK berhasil diinisialisasi!");
                } else {
                    console.error("❌Inisialisasi MA SDK gagal:", msg);
                }
    }
  });

            

Sakelar Pengumpulan Data (Bersama WebPush)

Didukung sejak: MA Web SDK 2.2.0, WebPush SDK 3.3.9

• Saat inisialisasi MTpushInterface.init, berikan nilai maDataCollectionEnabled secara dinamis sesuai status persetujuan pengguna; WebPush SDK akan meneruskannya ke MA SDK. Jangan menuliskan konfigurasi secara tetap (hardcode), agar setiap inisialisasi tidak mengatur ulang status ke nilai yang ditulis tetap tersebut
• Saat status pengumpulan data pengguna berubah, panggil window.MAInterface.setDataCollectionEnabled(true/false) setelah callback maCompletion dipicu. maCompletion adalah sinyal bahwa MA SDK sudah tersedia; sebelum itu, window.MAInterface mungkin belum dimuat.
• Selama pengumpulan dinonaktifkan, notifikasi WebPush tetap dapat terkirim dan diklik, tetapi atribusi konversi dari klik notifikasi tidak lagi dihitung.

Untuk penjelasan detail, lihat Sakelar Pengumpulan Data.

Hanya Menggunakan MA Web SDK

Konfigurasi Sumber Data MA

Pada proyek MA, buka Sumber Data - Tambah Sumber Data - Web, pada "Gunakan bersama WebPush" pilih "Tidak digunakan", masukkan nama sumber data dan nama domain website, lalu simpan. Setelah itu Anda akan mendapatkan informasi AppKey dari sumber data Web tersebut

• Siapkan nama domain layanan web HTTPS yang dapat diakses. Setelah integrasi, halaman harus diuji dan di-debug di bawah nama domain ini.

Akses SDK

Sertakan js berikut di setiap halaman:

              
              <script type="text/javascript" src="https://websdk-res.engagelab.com/lib/ma-web.min.js"></script>
        

            

Setelah mengimpor JS ini, Anda dapat menggunakan objek global MAInterface pada Window.

Catatan khusus: gunakan tautan ini secara langsung. Jangan mengunduh file ini ke dalam proyek Anda; jika tidak, statistik dapat menjadi tidak valid setelah kami memperbarui struktur data atau antarmuka API.

Inisialisasi SDK

              
                window.MAInterface.init({
    appKey: "7ccf93e0950b5e22f4ca2124",  // Wajib diisi, lihat "Mendapatkan Informasi Aplikasi" di atas
    debugMode: true,
    channel: "default-channel22",// Nama channel, nilai default: default-channel
    appName: "EngageLab-MA test-appName", // Nama website, digunakan sebagai app_name pada properti perangkat dan pelaporan event
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, // Atur identitas pengguna saat inisialisasi MA; mendukung user_id, anonymous_id, email, phone
      completion: (code, msg) => {
        if (code === 0) {
            console.log("✅ SDK berhasil diinisialisasi!");
        } else {
            console.error("❌ Inisialisasi SDK gagal:", msg);
        }
    }
  })
        

            

Penjelasan Identitas Pengguna

• userIdentity mendukung 4 jenis identitas pengguna: user_id, anonymous_id, email, phone (email dan phone didukung sejak versi 2.1.0). Berikan minimal satu. Aturan setiap field dapat dilihat di Atur Identifikasi Pengguna.
• Field yang tidak memenuhi aturan saat inisialisasi akan diabaikan dan peringatan dicetak di konsol; field lain yang valid tetap berlaku.
• email dan phone digunakan untuk pencocokan identitas pengguna, bukan sebagai informasi kontak. Untuk alamat email dan nomor telepon yang digunakan untuk pengiriman pesan, gunakan antarmuka "Atur Informasi Kontak Pengguna" (setUserContact).

Inisialisasi Ulang dan Beralih AppKey

Didukung sejak: 2.1.0

Setelah SDK diinisialisasi, Anda dapat memanggil init lagi tanpa memuat ulang halaman:

• AppKey yang sama: SDK akan mengambil ulang EUID. Jika userIdentity baru diberikan sekaligus, SDK menggunakan identitas pengguna baru tersebut untuk mengambil ulang EUID; cocok untuk skenario berganti akun setelah logout dalam halaman yang sama.
• AppKey yang berbeda: SDK beralih ke sumber data MA yang sesuai dengan AppKey baru, dan data selanjutnya dilaporkan ke sumber data baru; data yang dihasilkan sebelum peralihan tetap dilaporkan ke sumber data semula.
• Pemanggilan init berulang kali dieksekusi berurutan sesuai urutan pemanggilan, dan setiap pemanggilan mengembalikan hasil melalui completion. Gunakan hasil callback dari pemanggilan yang bersangkutan.
• Peralihan AppKey hanya didukung saat menggunakan MA Web SDK secara mandiri; mode integrasi "Bersama WebPush" tidak mendukungnya.

              
                // Beralih ke sumber data MA lain
  window.MAInterface.init({
    appKey: "AppKey sumber data lain",
    completion: (code, msg) => {
      console.log(code, msg)
    }
  })

            

Atur ID Kontak Channel

Didukung sejak: 2.1.0

Jika Anda perlu mengatur RID atau Token untuk channel WebPush atau Push pihak ketiga, panggil setelah SDK berhasil diinisialisasi:

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

            

• channelId: ID channel Push yang dikonfigurasi di konsol MA, harus lebih besar dari 0.
• values: array RID atau Token; array maupun elemennya tidak boleh kosong. Jika RID atau Token berubah, panggil antarmuka ini lagi untuk memperbarui.

Untuk penjelasan detail, lihat Atur ID Kontak Channel.

Sakelar Pengumpulan Data

Didukung sejak: 2.2.0

Aplikasi mengendalikan apakah MA SDK mengumpulkan data berdasarkan hasil persetujuan pengguna. Setelah dinonaktifkan, SDK tidak membuat, tidak menyimpan cache, dan tidak melaporkan event, properti pengguna, UTM, maupun informasi perangkat; inisialisasi, identitas pengguna, informasi kontak, dan ID kontak channel tetap dapat digunakan seperti biasa. Status disimpan secara lokal di browser dan tetap tersimpan setelah halaman dimuat ulang.

              
                // 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, // Jika tidak diisi, default aktif
    completion: (code, msg) => {}
  })

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

            

• 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.
• Selama dinonaktifkan, pemanggilan antarmuka properti pengguna mengembalikan -8 pada completion; antarmuka tanpa callback seperti event dan UTM dibuang secara diam-diam.
• Saat penyimpanan terdegradasi (localStorage tidak tersedia), status sakelar hanya berlaku pada tab saat ini.

Untuk penjelasan detail, lihat Sakelar Pengumpulan Data.

API Lainnya

Untuk penggunaan API lainnya, silakan lihat dokumentasi antarmuka: Web SDK API.