API SDK iOS

Deskripsi Antarmuka SDK

1. MTMAService: berisi seluruh antarmuka SDK.
2. MTMAConfig: kelas konfigurasi aplikasi.
3. MTMAInitResult: kelas hasil inisialisasi SDK.
4. MTMAUserID: model pengenal pengguna.
5. MTMAUserContact: model informasi kontak pengguna.
6. MTMACollectControl: model kontrol pengumpulan data.

Memulai Fungsi MA

Versi yang Didukung

Didukung mulai versi: 5.0.0

Pengenal email dan phone didukung mulai versi: 5.5.0

Inisialisasi mandiri didukung mulai versi: 5.5.0

Konfigurasi sakelar pengumpulan data didukung mulai versi: 5.5.1. Lihat Sakelar Pengumpulan Data.

Definisi Antarmuka

• + (void)start:(MTMAConfig * )config;
  • Deskripsi antarmuka:
    • Mengaktifkan fungsi MA EngageLab.
    • start merupakan titik awal antarmuka lain. Panggil start terlebih dahulu sebelum menggunakan antarmuka lainnya.
    • Versi mandiri memerlukan MA AppKey. Inisialisasi tidak bergantung pada hasil registrasi AppPush.
    • Anda dapat menginisialisasi ulang atau mengganti MA AppKey dalam proses aplikasi yang sama tanpa memulai ulang aplikasi. Setiap pemanggilan yang valid dijalankan dan menerima callback secara terpisah, tanpa digabungkan.
    • start: dan identifyAccount: dijalankan sesuai urutan pemanggilan. Pemanggilan berikutnya baru dijalankan setelah pemanggilan sebelumnya beserta callback-nya selesai. Perubahan objek konfigurasi asli saat masih dalam antrean tidak memengaruhi parameter inisialisasi yang sudah dikirimkan.
    • Pergantian MA AppKey berlaku saat inisialisasi tersebut mulai dijalankan. Selama masih dalam antrean, proyek dan identitas saat ini tidak berubah.
    • Setiap inisialisasi memerlukan jaringan untuk mengonfirmasi identitas pengguna; gunakan EUID dari callback pemanggilan tersebut. Jika perangkat offline, proses menunggu jaringan pulih dan pemanggilan berikutnya menunggu sesuai urutan. Lihat hasil kegagalan di Kode Kesalahan.
  • Parameter
    • config: kelas konfigurasi

Contoh Pemanggilan

              
                  MTMAConfig *config = [[MTMAConfig alloc] init];
    config.appKey = @"MA AppKey Anda";
    config.resultCompletion = ^(MTMAInitResult *result) {
        if (result.isSuccess) {
            NSLog(@"Inisialisasi MTMA berhasil");
        } else {
            NSLog(@"Inisialisasi MTMA gagal, code=%ld, message=%@", (long)result.code, result.message);
        }
    };
    [MTMAService start:config];

            

Mengatur Informasi Kontak Pengguna

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• + (void)setUserContact:(MTMAUserContact * )contact;
  • Deskripsi antarmuka:
    • Mengatur informasi kontak pengguna.
  • Parameter
    • contacts: Mengatur beberapa informasi kontak. Saat ini mendukung email, mobile_phone, landline_phone, dan whatsapp_phone. Key harus berupa string sepanjang 1–256 karakter; value harus berupa string. "" menghapus informasi kontak tersebut; string yang tidak kosong tetapi hanya berisi karakter spasi tidak valid.

Contoh Pemanggilan

              
                  MTMAUserContact *contact = [[MTMAUserContact alloc] init];
    contact.contacts = @{@"mobile_phone":@"13*********"};
    contact.completion = ^(NSInteger code, NSString * _Nonnull message) { };
    [MTMAService setUserContact:contact];

            

Pelaporan Event

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• **+ (void)eventRecord:(MTMAEventObject )event;*
  • Deskripsi antarmuka:
    • Melaporkan event.
  • Parameter
    • Model event yang dilaporkan
    • eventName: nama event yang dilaporkan
    • property: properti event; key adalah nama properti dan value adalah nilainya

Contoh Pemanggilan

              
                  MTMAEventObject *object = [[MTMAEventObject alloc] init];
    object.eventName = @"sndefineevent2";
    object.property = @{
        @"key1":@"value1",
        @"key2":@"value2",
    };
    [MTMAService eventRecord:object];

            

Mengatur Pengenal Pengguna

Versi yang Didukung

Didukung mulai versi: 5.0.0

Pengenal email dan phone didukung mulai versi: 5.5.0

Definisi Antarmuka

• + (void)identifyAccount:(MTMAUserID * )userID;
  • Deskripsi antarmuka:
    • Mengatur pengenal pengguna.
  • Parameter
    • Model pengenal pengguna
    • userID: pengenal unik pengguna yang telah login
    • anonymousID: Jika pengguna belum login tetapi memberikan informasi lain yang dapat digunakan sebagai pengenal, atur sebagai ID anonim, misalnya alamat email atau ID yang dibuat pihak ketiga.
    • email: alamat email pengguna untuk mengenali identitas pengguna
    • phone: nomor ponsel pengguna, termasuk kode negara atau wilayah, misalnya +8613800000000
    • Berikan setidaknya satu pengenal yang valid; tidak perlu mengisi semuanya. Lihat tipe, panjang, dan format pengenal pengguna.

Contoh Pemanggilan

              
                  MTMAUserID *userid = [[MTMAUserID alloc] init];
    userid.userID = @"member_10001";
    userid.anonymousID = @"anonymous_10001";
    userid.email = @"member_10001@example.com";
    userid.phone = @"+8613800000000";
    userid.completion = ^(NSInteger code, NSString *message) {
        NSLog(@"result：%ld - %@", code, message);
    };
    [MTMAService identifyAccount:userid];

            

email dan phone di sini digunakan untuk mencocokkan identitas pengguna dan dapat menghasilkan EUID baru. Keduanya tidak dapat saling menggantikan dengan informasi kontak yang diatur melalui setUserContact:.

Callback dengan code=0 berarti EUID yang dapat digunakan telah diperoleh, bukan berarti semua pengenal berhasil diatur. JSON di message berisi hasil per kolom dari validasi lokal dan server, dengan key user_id, anonymous_id, email, dan phone. Periksa code pada kolom terkait untuk mengetahui hasilnya; kolom yang tidak ada tidak berarti berhasil.

Jika server tidak memberikan hasil per kolom, message hanya berisi hasil penolakan lokal; jika tidak ada penolakan lokal, nilainya success. message kegagalan tidak selalu berupa JSON. Lihat kode kesalahan per kolom di Hasil per Pengenal Pengguna.

Contoh:

              
              code=0
message={"email":{"code":0},"phone":{"code":3003,"msg":"Nilai pengenal pengguna melebihi batas panjang"}}

            

Mengatur ID Kontak Kanal

Versi yang Didukung

Didukung mulai versi: 5.5.0

Definisi Antarmuka

• **+ (void)setChannelValueWithChannelId:(NSInteger)channelId values:(NSArray<NSString *> )values completion:(void (^)(NSInteger code, NSString message))completion;
  • Deskripsi antarmuka:
    • Mengatur RID atau Token untuk kanal Push pihak ketiga.
    • Hubungan kanal EngageLab AppPush ditangani otomatis oleh SDK; antarmuka ini tidak perlu dipanggil untuk mengaturnya.
    • Tidak mengintegrasikan AppPush atau kegagalan registrasi AppPush tidak memengaruhi fungsi MA lainnya.
    • Untuk pemanggilan berturut-turut, SDK mengirim permintaan sesuai urutan dan memberikan callback masing-masing.
    • Jika MA AppKey, proyek, atau identitas berubah selama permintaan dalam antrean, permintaan terkait mengembalikan -2.
  • Parameter
    • channelId: ID kanal Push pihak ketiga di konsol MA; harus lebih besar dari 0.
    • values: Array RID atau Token kanal saat ini. SDK memangkas karakter spasi di awal dan akhir setiap nilai sebelum mengirimnya. Array maupun elemen setelah dipangkas tidak boleh kosong.
    • completion: callback hasil permintaan; code bernilai 0 berarti berhasil.

Contoh Pemanggilan

              
                  [MTMAService setChannelValueWithChannelId:136
                                       values:@[@"RID atau Token Push pihak ketiga"]
                                   completion:^(NSInteger code, NSString *message) {
    }];

            

Mengatur Interval Pelaporan Data

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• + (void)setReportInterval:(NSInteger)interval;
  • Deskripsi antarmuka:
    • Mengatur interval pelaporan data. Jika tidak dipanggil, data event dilaporkan setiap 10 detik secara default.
    • Interval pelaporan disimpan dalam memori. Panggil antarmuka ini pada setiap siklus hidup aplikasi agar pengaturan berlaku.
  • Parameter
    • interval: interval pelaporan dalam s (detik)

Contoh Pemanggilan

              
                  [MTMAService setReportInterval:10];

            

Mengatur Batas Maksimal Cache Event

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• + (void)setMaxEventCacheCount:(NSInteger)count;
  • Deskripsi antarmuka:
    • Mengatur jumlah maksimum event dalam cache; default 50 dan tidak boleh melebihi 500.
    • Jika jumlah event melebihi batas cache, seluruh data akan dilaporkan.
  • Parameter
    • count: jumlah maksimum event dalam cache

Contoh Pemanggilan

              
                  [MTMAService setMaxEventCacheCount:50];

            

Mengatur Timeout Sesi

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• + (void)setNoActiveSessionEndDurationTime:(NSInteger)interval;
  • Deskripsi antarmuka:
    • Mengatur timeout sesi; default 30 menit.
    • Saat aplikasi berpindah ke latar belakang, penghitung timeout sesi dimulai. Jika tidak ada aktivitas selama periode tersebut, sesi saat ini berakhir.
  • Parameter
    • interval: durasi timeout dalam s (detik)

Contoh Pemanggilan

              
                  [MTMAService setNoActiveSessionEndDurationTime:50];

            

Mendapatkan EUID

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• + (nullable NSString * )EUID;
  • Deskripsi antarmuka:
    • Mendapatkan EUID EngageLab MA.
    • Mengembalikan nil jika SDK belum berhasil diinisialisasi.

Contoh Pemanggilan

              
                  [MTMAService EUID];

            

Mengatur Properti UTM

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• + (void)setUtmProperties:(NSDictionary * )property;
  • Deskripsi antarmuka:
    • Properti UTM adalah properti event standar. Jika Anda dapat mengenali iklan yang membawa pengguna ke aplikasi, disarankan mengatur informasi UTM; parameter ini akan disertakan saat pelaporan event. Properti yang tersedia:
      • utm_source: sumber kampanye
      • utm_medium: media kampanye
      • utm_term: kata kunci kampanye
      • utm_content: konten kampanye
      • utm_campaign: nama kampanye
      • utm_id: ID kampanye

Contoh Pemanggilan

              
                  [MTMAService setUtmProperties:@{@"utm_source":@"value"}];

            

Mengatur Properti Pengguna

Menimpa dan Memperbarui Properti Pengguna

• + (void)setProperty:(NSDictionary * )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;
  • Deskripsi antarmuka:
    • Mengatur properti pengguna secara massal, maksimal 100 per pemanggilan. Jika satu properti gagal divalidasi oleh SDK, seluruh permintaan dalam batch tidak dikirim.
    • Nama properti harus berupa NSString: dimulai dengan huruf kecil, hanya berisi huruf kecil, angka, dan garis bawah, maksimal 50 byte UTF-8, dan tidak boleh diawali el, engagelab, atau metaverse.
    • Value mendukung NSString, NSNumber bernilai terbatas (finite), NSSet/NSArray berisi string, NSDictionary (object), dan NSArray<NSDictionary *> (object_array).
    • Properti bertipe biasa ditimpa jika sudah ada dan dibuat jika belum ada; object menggabungkan subkolom, sedangkan object_array mengganti seluruh array dengan mempertahankan urutannya.
  • Contoh pemanggilan:

              
                 [MTMAService setProperty:@{
       @"level": @"gold",
       @"profile": @{ @"city": @"Singapore", @"score": @100 },
       @"addresses": @[
           @{ @"id": @"home", @"city": @"Singapore" },
           @{ @"id": @"office", @"city": @"Tokyo" }
       ]
   } completion:^(NSInteger code, NSString * _Nonnull message) {
       // code == 0 berarti server berhasil memproses permintaan
   }];

            

• + (void)setProperty:(NSString * )key to:(id)value completion:(void (^)(NSInteger code, NSString * message))completion;
  • Deskripsi antarmuka:
    • Mengatur isi satu properti pengguna.
    • Aturan nama properti, tipe Value, dan perilaku pembaruan sama persis dengan antarmuka massal.
  • Contoh pemanggilan:

              
                 [MTMAService setProperty:@"profile"
                         to:@{ @"city": @"Singapore", @"score": @100 }
                 completion:^(NSInteger code, NSString * _Nonnull message) {
   }];

            

Aturan object / object_array

• object harus berupa NSDictionary yang tidak kosong. Nama subkolom harus berupa NSString yang tidak kosong dan tidak boleh mengandung . atau $.
• Nilai subkolom object mendukung NSString, NSNumber bernilai terbatas (finite), NSSet/NSArray berisi string, dan NSNull. object atau object_array bersarang tidak didukung.
• Pemanggilan ulang setProperty untuk object hanya menggabungkan subkolom yang dikirim pada pemanggilan itu; subkolom yang tidak dikirim tetap sama. Nilai NSNull menghapus subkolom terkait.
• object_array harus berupa NSArray<NSDictionary *>; setiap objek harus tidak kosong dan mengikuti aturan subkolom yang sama. Pemanggilan ulang setProperty mengganti seluruh array.
• Setiap elemen object_array harus menyisakan setidaknya satu subkolom bernilai selain NSNull. Objek dengan seluruh nilai subkolom berupa NSNull tidak diperbolehkan.
• Array kosong dapat digunakan untuk mengosongkan properti array yang sudah ada, tetapi saat pertama dibuat, array kosong tidak dapat membedakan daftar string dari object_array. Untuk membuat object_array pertama kali, kirim array objek yang tidak kosong.
• NSNull hanya boleh digunakan sebagai nilai subkolom object/object_array. NSNull pada tingkat teratas tidak dapat menghapus seluruh properti; gunakan deleteProperty:completion:.

Contoh pembaruan sebagian object dan penghapusan subkolom:

              
              // Hanya memperbarui profile.score; profile.city tetap sama
[MTMAService setProperty:@"profile"
                      to:@{ @"score": @200 }
              completion:completion];

// Hanya menghapus profile.city
[MTMAService setProperty:@"profile"
                      to:@{ @"city": NSNull.null }
              completion:completion];

            

Memperbarui Sebagian Elemen object_array

Didukung mulai versi: 5.5.0

• **+ (void)updateObjectArrayProperty:(NSString *)key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue values:(NSDictionary<NSString *, id> )values completion:(void (^)(NSInteger code, NSString * message))completion;
  • Deskripsi antarmuka:
    • Menemukan objek dalam object_array melalui subkolom unik, lalu menggabungkan subkolom dalam values.
    • Subkolom yang ditunjuk identifierKey harus sudah didefinisikan dalam metadata server dan hanya boleh bertipe string atau number. identifierValue harus memiliki tipe yang sama: NSString atau NSNumber bernilai finite dan bukan boolean. Nilainya harus cocok dengan tepat satu elemen dalam array saat ini.
    • values harus berupa dictionary yang tidak kosong, tidak boleh berisi identifierKey, dan tidak boleh memuat object/object_array bersarang. Kolom yang tidak dikirim tetap sama; nilai NSNull menghapus subkolom terkait.
    • Properti harus sudah didefinisikan sebagai object_array dalam metadata server dan pengguna saat ini harus sudah memiliki nilainya. Untuk pembuatan pertama, gunakan setProperty:to: dengan array objek yang tidak kosong.
    • Jika properti belum didefinisikan, atau sudah didefinisikan tetapi pengguna saat ini belum memiliki nilai, server mengembalikan code=0 tanpa membuat perubahan. code=0 hanya berarti permintaan berhasil diproses; periksa perubahan sebenarnya melalui konsol MA atau properti pengguna di server.
    • Jika array sudah ada tetapi tidak ada kecocokan, ada beberapa kecocokan, tipe kolom pengenal tidak cocok, atau subkolom tidak sesuai dengan definisi metadata, server mengembalikan kode kegagalan tanpa membuat atau mengubah elemen lain.
  • Contoh pemanggilan:

              
              // Objek dengan id == home: perbarui city menjadi Tokyo dan hapus zip
[MTMAService updateObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"home"
                                values:@{
                                    @"city": @"Tokyo",
                                    @"zip": NSNull.null
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

Menambahkan Elemen object_array

Didukung mulai versi: 5.5.0

• **+ (void)addObjectArrayProperty:(NSString )key object:(NSDictionary<NSString *, id> )object completion:(void (^)(NSInteger code, NSString * message))completion;
  • Deskripsi antarmuka:
    • Menambahkan satu objek ke akhir object_array tanpa memengaruhi elemen yang ada. Ini berbeda dari mengirim seluruh array ke setProperty:to:, yang mengganti array secara keseluruhan.
    • object harus berupa NSDictionary yang tidak kosong dan menyisakan setidaknya satu subkolom bernilai selain NSNull. Aturan subkolom sama dengan object; object/object_array bersarang tidak didukung.
    • Properti harus sudah didefinisikan sebagai object_array dalam metadata server. Jika belum didefinisikan, server mengembalikan code=0 tanpa membuat perubahan; buat terlebih dahulu menggunakan setProperty:to: dengan array objek yang tidak kosong.
    • Jika properti sudah didefinisikan tetapi pengguna saat ini belum memiliki nilai, antarmuka ini membuat array dengan satu elemen tersebut.
  • Contoh pemanggilan:

              
              [MTMAService addObjectArrayProperty:@"addresses"
                                object:@{
                                    @"id": @"school",
                                    @"city": @"Osaka"
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

Menghapus Elemen object_array

Didukung mulai versi: 5.5.0

• **+ (void)removeObjectArrayProperty:(NSString )key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue completion:(void (^)(NSInteger code, NSString * message))completion;
  • Deskripsi antarmuka:
    • Menemukan dan menghapus seluruh elemen array melalui subkolom unik. Untuk menghapus hanya satu subkolom di dalam elemen, gunakan updateObjectArrayProperty: dengan nilai NSNull untuk subkolom tersebut.
    • Batasan identifierKey / identifierValue sama persis dengan updateObjectArrayProperty:: subkolom harus sudah didefinisikan dalam metadata, hanya boleh bertipe string atau number, dan harus cocok dengan tepat satu elemen dalam array saat ini.
    • Jika properti belum didefinisikan di server, pengguna saat ini tidak memiliki nilainya, atau tidak ada kecocokan, server mengabaikan permintaan dan mengembalikan code=0. Periksa perubahan sebenarnya melalui konsol MA atau properti pengguna di server.
    • Jika terdapat beberapa kecocokan atau tipe kolom pengenal tidak cocok, server mengembalikan kode kegagalan tanpa menghapus elemen lain secara keliru.
  • Contoh pemanggilan:

              
              // Menghapus alamat dengan id == office
[MTMAService removeObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"office"
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

Menambah Nilai Properti Pengguna secara Kumulatif

• **+ (void)increaseProperty:(NSString )key by:(NSNumber )amount completion:(void (^)(NSInteger code, NSString * message))completion;
  • Deskripsi antarmuka:
    • Menambahkan nilai ke satu properti pengguna numerik untuk mengakumulasi seluruh data yang dilaporkan, misalnya total belanja.
    • Hanya dapat digunakan pada properti bertipe NSNumber; selain itu diabaikan. Jika properti belum ada, nilai awalnya dianggap 0.
  • Contoh pemanggilan:

              
                  [MTMAService increaseProperty:@"key" by:@(2) completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

• **+ (void)increaseProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;*
  • Deskripsi antarmuka:
    • Menambahkan nilai ke beberapa properti pengguna numerik untuk mengakumulasi seluruh data yang dilaporkan, misalnya total belanja.
    • Hanya dapat digunakan pada properti bertipe NSNumber; selain itu diabaikan. Jika properti belum ada, nilai awalnya dianggap 0.
  • Contoh pemanggilan:

              
                  [MTMAService increaseProperty:@{@"key1":@(5),@"key2":@(3)} completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

Menambahkan Nilai ke Properti Pengguna

• **+ (void)addProperty:(NSString )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion
  • Deskripsi antarmuka:
    • Menambahkan beberapa nilai ke satu properti bertipe NSSet atau NSArray.
    • Elemen NSSet atau NSArray harus berupa NSString; jika tidak, operasi diabaikan. Jika properti yang akan ditambahkan nilainya belum ada, NSSet atau NSArray kosong akan diinisialisasi.
  • Contoh pemanggilan:

              
                  [MTMAService addProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

• **+ (void)addProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger, NSString * _Nonnull))completion;*
  • Deskripsi antarmuka:
    • Menambahkan beberapa nilai ke beberapa properti bertipe NSSet atau NSArray.
    • Elemen NSSet atau NSArray harus berupa NSString; jika tidak, operasi diabaikan. Jika properti yang akan ditambahkan nilainya belum ada, NSSet atau NSArray kosong akan diinisialisasi.
  • Contoh pemanggilan:

              
                  [MTMAService addProperty:@{@"key1":@[@"value"],@"key2":@[@"value"]} completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

Menghapus Nilai dari Properti Pengguna

• **+ (void)removeProperty:(NSString * )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion;*
  • Deskripsi antarmuka:
    • Menghapus beberapa nilai dari satu properti bertipe NSSet atau NSArray.
    • content harus bertipe NSSet atau NSArray dengan elemen NSString.
  • Contoh pemanggilan:

              
                  [MTMAService removeProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

Menghapus Properti Pengguna

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• + (void)deleteProperty:(NSString * )key completion:(void (^)(NSInteger code, NSString * message))completion;
  • Deskripsi antarmuka:
    • Menghapus seluruh isi suatu properti pengguna, termasuk tipe biasa, object, dan object_array.
    • Jika properti belum ada, operasi diabaikan.

Contoh Pemanggilan

              
                  [MTMAService deleteProperty:@"key" completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

Sakelar Pengumpulan Data

Versi yang Didukung

Didukung mulai versi: 5.5.1

Aplikasi dapat mengaktifkan atau menonaktifkan pengumpulan data MA sesuai pilihan pengguna. Saat dinonaktifkan, pengumpulan event, properti pengguna, UTM, dan informasi perangkat berhenti. Inisialisasi, pengenal pengguna, informasi kontak, dan kanal pesan tetap dapat digunakan.

Mengatur Status Pengumpulan Saat Inisialisasi

Atur dataCollectionEnabled di MTMAConfig, lalu panggil start:.

              
              @property (nonatomic, strong, nullable) NSNumber *dataCollectionEnabled;

            

Status pengumpulan dipisahkan berdasarkan MA AppKey. Setiap pemanggilan start: menggunakan konfigurasi saat itu. Misalnya, jika sebelumnya dinonaktifkan, inisialisasi dengan @YES atau tanpa pengaturan ini akan mengaktifkannya. SDK menyimpan status pengumpulan secara lokal per AppKey, tetapi setiap start: tetap menggunakan parameter saat itu. Jika tidak diberikan, pengumpulan aktif secara default dan persetujuan sebelumnya tidak diterapkan otomatis. Halaman persetujuan dan catatan persetujuan dikelola oleh aplikasi; berikan pilihan pengguna saat ini pada setiap inisialisasi.

Atur dataCollectionEnabled berdasarkan status persetujuan pengguna saat ini pada setiap inisialisasi. Hindari selalu memberikan @YES atau @NO, karena akan menimpa pilihan pengguna sebelumnya saat start: dipanggil kembali.

Contoh Pemanggilan

Jika pengguna belum menyetujui pengumpulan, berikan @NO saat inisialisasi. Status saat ini dapat diperiksa dalam callback keberhasilan inisialisasi.

              
              MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = @"MA AppKey Anda";
config.dataCollectionEnabled = @NO;
config.resultCompletion = ^(MTMAInitResult *result) {
    if (result.isSuccess) {
        NSNumber *enabled = [MTMAService isDataCollectionEnabled];
        if (enabled == nil) {
            return;
        }
        NSLog(@"Pengumpulan data MA: %@", enabled.boolValue ? @"aktif" : @"nonaktif");
    } else {
        NSLog(@"Inisialisasi MTMA gagal, code=%ld, message=%@", (long)result.code, result.message);
    }
};
[MTMAService start:config];

            

Mengatur Status Pengumpulan

Definisi Antarmuka

              
              + (void)setDataCollectionEnabled:(BOOL)enabled;

            

• enabled: YES mengaktifkan pengumpulan, NO menonaktifkannya.
• Panggil start: terlebih dahulu untuk menentukan MA AppKey, lalu panggil antarmuka ini. Status pengumpulan awal diberikan melalui konfigurasi inisialisasi.
• Pengaturan langsung berlaku pada MA AppKey saat ini. Pengaturan berulang dengan nilai yang sama tidak mengulangi perubahan.
• Menonaktifkan pengumpulan menghapus UTM yang sebelumnya diatur. Nilai tersebut tidak dipulihkan saat pengumpulan diaktifkan kembali.
• Setelah diaktifkan kembali, hanya perilaku baru yang dicatat. Event selama pengumpulan nonaktif tidak dilaporkan ulang.

Contoh Pemanggilan

              
              // start: telah dipanggil untuk menginisialisasi MA AppKey saat ini.
// Aktifkan pengumpulan setelah pengguna memberikan persetujuan.
[MTMAService setDataCollectionEnabled:YES];

// Nonaktifkan saat pengguna menolak atau mencabut persetujuan.
[MTMAService setDataCollectionEnabled:NO];

            

Dampak pada API yang Ada

setCollectControl: tetap mengontrol kolom seperti IDFA, IDFV, dan operator seluler. Saat seluruh pengumpulan nonaktif, kolom ini juga tidak dikumpulkan. Setelah diaktifkan kembali, konfigurasi kolom sebelumnya tetap berlaku.

Sakelar ini hanya mengontrol SDK MA. Perilaku SDK Push dan izin notifikasi sistem tetap mengikuti pengaturannya masing-masing. Data yang telah dibuat sebelum pengumpulan dinonaktifkan akan dicoba dikirim sebagai batch terakhir, tanpa percobaan ulang jika gagal. Data historis yang sudah dilaporkan tidak dihapus. Lihat definisi kode kesalahan di Kode Kesalahan SDK iOS.

Memeriksa Status Pengumpulan

Definisi Antarmuka

              
              + (nullable NSNumber *)isDataCollectionEnabled;

            

@YES berarti aktif, @NO berarti nonaktif, dan nil berarti SDK belum siap. Periksa nil sebelum membaca boolValue.

Mengontrol Pengumpulan Data

Versi yang Didukung

Didukung mulai versi: 5.0.0

Definisi Antarmuka

• **+ (void)setCollectControl:(MTMACollectControl )control;*
  • Deskripsi antarmuka:
    • Mengontrol apakah data pada kelas MTMACollectControl dikumpulkan.

Contoh Pemanggilan

              
                  MTMACollectControl *collectControl = [[MTMACollectControl alloc] init];
    collectControl.idfa = YES;
    collectControl.idfv = YES;
    collectControl.carrier = YES;
    [MTMAService setCollectControl:collectControl];

            

Kelas MTMAConfig

Kelas konfigurasi aplikasi. Berikut penjelasan propertinya:

Kelas MTMAInitResult

Objek hasil inisialisasi SDK yang dikembalikan oleh resultCompletion. Tidak perlu dibuat atau dipanggil secara terpisah. Berikut penjelasan propertinya:

Kelas MTMAUserID

Model pengenal pengguna. Dikirim melalui MTMAConfig.userID saat inisialisasi dan melalui identifyAccount: saat aplikasi berjalan.

Keempat pengenal bersifat opsional. Spasi di awal dan akhir dihapus; nilai kosong dan 0/null/undefined/nan (tanpa membedakan huruf besar/kecil) dianggap tidak dikirim, tidak digunakan untuk pencocokan, dan tidak menghasilkan hasil per kolom. Batasan berikut berlaku untuk nilai yang tersisa setelah pembersihan:

Kolom yang bukan NSString atau berformat tidak valid dikeluarkan dengan 3013, sedangkan kolom yang terlalu panjang dikeluarkan dengan 3003. Hasil tersebut dicatat dan kolom valid lainnya tetap dikirim. Jika tidak ada kolom valid, inisialisasi berlanjut tanpa identitas, sedangkan identifyAccount: mengembalikan -3 tanpa mengirim permintaan. SDK tidak mengubah objek milik pemanggil; email diubah menjadi huruf kecil oleh server.

Jika inisialisasi berhasil, userID.completion mengembalikan code=0 dengan message berupa string kosong atau JSON yang hanya memuat kolom yang ditolak secara lokal. Hasil per kolom dari server tidak disertakan, sehingga ini tidak berarti semua pengenal telah tertaut. Gunakan config.resultCompletion sebagai acuan hasil inisialisasi SDK; callback tersebut tidak memuat JSON per pengenal. Lihat penjelasan callback saat aplikasi berjalan di Mengatur Pengenal Pengguna.

Kelas MTMACollectControl

Model kontrol pengumpulan data pengguna. Berikut penjelasan propertinya:

Kelas MTMAUserContact

Model kanal kontak pengguna. Berikut penjelasan propertinya:
Jika tidak diatur atau bernilai nil, kontak tidak diubah. String kosong "" menghapus informasi kontak tersebut; string yang tidak kosong tetapi hanya berisi karakter spasi tidak valid.

Kelas MTMAEventObject

Kelas objek event kustom. Berikut penjelasan propertinya: