Panduan Integrasi Fungsi Android MA

Versi yang berlaku

Artikel ini berlaku untuk versi independen MA SDK 5.5.0 dan versi yang lebih baru.

Mulai dari 5.5.0, MA tidak lagi bergantung pada AppPush dan dapat diintegrasikan dan diinisialisasi secara mandiri. MA AppKey dan Push AppKey tidak bergantung satu sama lain dan bisa sama atau berbeda.

Untuk metode integrasi versi Fusion sebelum 5.5.0, silakan lihat Panduan Integrasi sebelum 5.5.0.

1. Impor SDK

Impor manual

Tambahkan mt-sdk-ma-5.5.0.aar dalam paket rilis ke direktori libs proyek aplikasi:

              
              dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
}

            

Impor Maven

              
              dependencies {
    implementation 'com.engagelab.plugin:oth_ma:5.5.0'
}

            

Jika Anda menggunakan AppPush secara bersamaan, ikuti dokumen AppPush untuk memperkenalkan paket utama engagelab; saat menggunakan MA saja, Anda tidak perlu memperkenalkan paket utama AppPush.

2. Konfigurasi izin

Deklarasikan izin jaringan di AndroidManifest.xml:

              
              <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

            

MA versi mandiri tidak memerlukan konfigurasi ENGAGELAB_PRIVATES_APPKEY, ENGAGELAB_PRIVATES_CHANNEL, Push Service, atau Push Receiver. Jika Anda menggunakan AppPush secara bersamaan, Anda masih perlu menyelesaikan konfigurasi yang sesuai sesuai dengan dokumen integrasi AppPush.

3. Inisialisasi SDK

Disarankan untuk menginisialisasi dalam Application.onCreate() dari proses utama. MA AppKey digunakan untuk inisialisasi, dan tidak perlu menunggu inisialisasi AppPush atau registrasi berhasil.

              
              import android.app.Application;

import com.engagelab.privates.push.oth.ma.api.MTMAApi;
import com.engagelab.privates.push.oth.ma.api.MTMAConfig;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResult;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResultCallback;

public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        MTMAApi.configDebugMode(true);
        MTMAConfig config = new MTMAConfig("your MA AppKey");
        // Opsional (didukung mulai 5.5.2): jika perlu mengontrol pengumpulan berdasarkan persetujuan pengguna, teruskan hasil persetujuan yang saat ini dicatat aplikasi; true mengaktifkan, false menonaktifkan, dan aktif secara default jika belum pernah diatur
        // config.dataCollectionEnabled(enabled);
        MTMAApi.getInstance(this).start(config, new MTMAInitResultCallback() {
            @Override
            public void onResult(MTMAInitResult result) {
                if (result.isSuccess()) {
                    String euid = result.getEuid();
                    String maRid = result.getMaRid();
                } else {
                    int code = result.getCode();
                    String message = result.getMessage();
                }
            }
        });
    }
}

            

Petunjuk inisialisasi

• MA AppKey diperlukan.
• Android MA SDK hanya mendukung inisialisasi pada proses utama aplikasi host. Memanggil start dalam proses non-utama akan mengembalikan kegagalan melalui panggilan balik dan tidak ada permintaan jaringan yang akan dimulai.
• Sebelum inisialisasi berhasil, API bisnis MA lainnya tidak tersedia kecuali untuk antarmuka konfigurasi pra-inisialisasi.
• Direkomendasikan agar semua API eksternal MA dipanggil dalam proses utama. Proses non-utama tidak akan membagikan status inisialisasi proses utama, dan panggilan bisnis tidak akan diteruskan ke proses utama.
• Setelah inisialisasi berhasil, nilai saat ini juga dapat diperoleh melalui getEuid() dan getMaRid().

Ganti MA AppKey saat runtime

Proses yang sama mendukung peralihan MA AppKey saat runtime. Silakan hubungi start lagi dengan AppKey baru setelah panggilan balik inisialisasi terakhir selesai.

              
              MTMAConfig newConfig = new MTMAConfig("new MA AppKey");
MTMAApi.getInstance(this).start(newConfig, callback);

            

Selama peralihan, API bisnis MA lainnya untuk sementara tidak tersedia; setelah AppKey baru berhasil diinisialisasi, kejadian berikutnya dan data pengguna menjadi milik AppKey baru. Jika AppKey baru gagal diinisialisasi, SDK tidak akan otomatis kembali ke AppKey lama, dan start perlu dipanggil lagi dengan AppKey yang valid.

Tetapkan ID pengguna selama inisialisasi

              
              UserIdentity identity = new UserIdentity();
identity.setUserId("your user id");
identity.setAnonymousId("your anonymous id");
identity.setEmail("user@example.com");
identity.setPhone("+8613800138000");

MTMAConfig config = new MTMAConfig("your MA AppKey", identity);
MTMAApi.getInstance(this).start(config, callback);

            

Diantaranya, setEmail dan setPhone didukung mulai dari versi 5.5.0.

Aturan bidang identitas pengguna: setelah spasi di awal dan akhir dihapus, user_id tidak boleh kosong, panjangnya maksimal 255 karakter Unicode, dan tidak boleh sama dengan 0, null, undefined, atau nan (tanpa membedakan huruf besar/kecil). Setelah spasi dihapus, anonymous_id tidak boleh kosong dan panjangnya maksimal 256 karakter Unicode. email tidak boleh kosong, panjangnya maksimal 256 karakter Unicode, harus berisi tepat satu @ dengan isi yang tidak kosong di kedua sisinya, serta tidak boleh berisi spasi, baris baru, atau tab. phone harus menggunakan format E.164: diawali dengan +, kode negara diawali digit 1–9, lalu diikuti 1–14 digit. Jika validasi gagal, SDK tidak mengirim permintaan identitas dan mengembalikan code = -3 melalui callback.

Opsional: Mengontrol Pengumpulan Berdasarkan Persetujuan Pengguna

Jika aplikasi Anda perlu mengontrol pengumpulan berdasarkan persetujuan pengguna, gunakan sakelar pengumpulan data. Jika tidak diperlukan, tidak ada yang perlu diubah: pengumpulan aktif secara default dan perilakunya sama seperti sebelum peningkatan versi. Kemampuan ini tersedia mulai MA SDK 5.5.2.

Sakelar disimpan terpisah untuk setiap MA AppKey. Saat inisialisasi, teruskan nilai dataCollectionEnabled secara dinamis sesuai status persetujuan pengguna. Jangan menuliskannya sebagai nilai tetap, karena setiap inisialisasi akan mengatur ulang status ke nilai tetap tersebut. Ketika pengguna mengubah pilihannya saat aplikasi berjalan, panggil setDataCollectionEnabled setelah inisialisasi berhasil. Keduanya dijalankan di proses utama:

              
              // enabled adalah status sakelar yang ditentukan aplikasi Anda berdasarkan persetujuan pengguna
MTMAConfig config = new MTMAConfig(maAppKey);
config.dataCollectionEnabled(enabled);
MTMAApi.getInstance(this).start(config, initCallback);

// Ketika pengguna mengubah pilihannya saat aplikasi berjalan
MTMAApi.getInstance(this).setDataCollectionEnabled(enabled);

            

Hal yang perlu diperhatikan saat integrasi:

• Saat dinonaktifkan, event, atribut pengguna, UTM, dan informasi perangkat berhenti dikumpulkan dan dilaporkan. Inisialisasi, identitas pengguna, informasi kontak, dan saluran push tetap tersedia, dan SDK tetap mengirim permintaan yang diperlukan tersebut.
• Saat beralih dari aktif ke nonaktif, SDK langsung mengirim satu kali data yang dihasilkan sebelum peralihan, tidak mencoba ulang jika gagal, lalu menghapus cache lokal.
• Saat memanggil config.dataCollectionEnabled, Anda harus meneruskan true atau false, dan nilainya berlaku pada setiap start: jika berbeda dari status sebelumnya, peluncuran kali ini langsung diinisialisasi dengan status baru; jika start dipanggil lagi ketika SDK sudah berjalan dan statusnya berubah, pemrosesan penonaktifan atau pengaktifan dijalankan satu kali.
• Setelah diaktifkan kembali, SDK otomatis melanjutkan pengumpulan. Event, atribut pengguna, dan UTM yang dipanggil sebelum pemulihan selesai tidak disimpan.

Untuk parameter antarmuka, perilaku setiap antarmuka saat dinonaktifkan, dan kode kesalahan, lihat Sakelar Pengumpulan Data di Panduan API.

4. Gunakan AppPush secara bersamaan

Saat mengonfigurasi sumber data seluler di konsol MA, silakan pilih untuk menggunakan AppPush secara bersamaan, dan pilih aplikasi AppPush yang benar-benar terhubung. Saat menginisialisasi AppPush, gunakan AppKey dari aplikasi yang dipilih.

MA dan AppPush diinisialisasi secara terpisah dan tidak memerlukan urutan tetap. Setelah AppPush berhasil didaftarkan dan Push RID diperoleh, MA SDK akan secara otomatis mengikat saluran AppPush.

AppPush tidak terintegrasi, belum terdaftar, atau pengikatan saluran gagal, yang tidak memengaruhi inisialisasi MA, pengumpulan peristiwa, dan pelaporan.

Catatan: MA RID dan AppPush RID adalah dua pengidentifikasi perangkat independen. Silakan dapatkan dan gunakan masing-masing melalui SDK yang sesuai, jangan gunakan salah satu sebagai yang lain.

5. Tetapkan ID kontak saluran

Jika Anda perlu mengatur ID kontak saluran untuk saluran Push pihak ketiga, silakan hubungi setelah MA berhasil diinisialisasi:

              
              List<String> values = Collections.singletonList("push rid or token");
MTMAApi.getInstance(this).setChannelValue(136L, values, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        // code == 0 means success
    }
});

            

• channelId: ID saluran Push pihak ketiga yang dikonfigurasi pada konsol MA harus lebih besar dari 0.
• values: Daftar nilai ID kontak saluran (seperti RID atau Token) tidak boleh kosong, dan elemen daftar tidak boleh kosong.
• Setelah ID kontak saluran berubah, pembaruan antarmuka perlu dipanggil lagi.
• Antarmuka ini digunakan untuk mengatur ID kontak saluran Push pihak ketiga; saluran AppPush secara otomatis terikat oleh SDK.

6. Petunjuk peningkatan versi lama

• Setelah memutakhirkan ke 5.5.0, MA AppKey harus diteruskan secara eksplisit menggunakan MTMAConfig.
• Tidak perlu lagi menunggu koneksi AppPush yang lama atau registrasi berhasil untuk menghubungi MA start.
• start(CallBack) dan start(UserIdentity, CallBack) sudah usang, harap gunakan start(MTMAConfig, MTMAInitResultCallback) untuk versi mandiri.
• Aplikasi yang awalnya menggunakan AppPush dan MA secara bersamaan dapat terus mengintegrasikan AppPush, namun harus diinisialisasi secara terpisah.
• MA RID dan AppPush RID adalah dua pengidentifikasi perangkat independen. Silakan dapatkan dan gunakan masing-masing melalui SDK yang sesuai, jangan gunakan salah satu sebagai yang lain.

Untuk antarmuka bisnis lainnya, silakan lihat Panduan API.