Panduan Integrasi iOS SDK

Versi yang Didukung

Artikel ini berlaku untuk MTPush iOS SDK versi: v3.0.0 ke atas.

File Sumber

Nama Paket engagelab-ios-{nomor versi}

Mulai versi 4.3.3, paket .a tidak lagi disediakan. Hanya paket .xcframework yang tersedia.

• Folder lib: Berisi mtpush-ios-x.x.x.xcframework, mtpush-extension-ios-x.x.x.xcframework. (Catatan: APNs tidak didukung pada simulator).
• File README: Instruksi terkait SDK.
• Folder demo: Contoh penggunaan.

Mendapatkan Informasi Aplikasi

Setelah aplikasi dibuat di konsol, sebuah AppKey akan otomatis dihasilkan untuk mengidentifikasi aplikasi tersebut.

Konfigurasi Proyek

Mengimpor SDK

Import menggunakan Cocoapods

              
                  pod 'MTPush'

    Catatan: Jika Anda tidak dapat mengimpor versi terbaru, jalankan perintah pod repo update master untuk memperbarui pustaka pod lokal, lalu ulangi pod 'MTPush'.

            

• Untuk instalasi versi tertentu, gunakan metode berikut (contoh MTPush 3.5.0):

              
                  pod 'MTPush', '3.5.0'

            

Import Manual

• Ekstrak paket SDK, di Xcode pilih "Add files to 'Nama proyek Anda'...", lalu tambahkan mtpush-ios-x.x.x.xcframework ke direktori proyek Anda.
• Tambahkan Framework:
  • CFNetwork.framework
  • CoreFoundation.framework
  • CoreTelephony.framework
  • SystemConfiguration.framework
  • CoreGraphics.framework
  • Foundation.framework
  • UIKit.framework
  • Security.framework
  • libz.tbd
  • UserNotifications.framework
  • libresolv.tbd
  • libsqlite3.tbd

Pengaturan Build

Jika proyek Anda membutuhkan dukungan untuk iOS di bawah 7.0, buka Build Settings dan matikan opsi bitCode. Jika tidak, proyek tidak akan dapat dikompilasi dengan benar.

• Atur User Header Search Paths dan Library Search Paths di bagian Search Paths. Contoh: folder SDK (default: lib) berada pada level yang sama dengan file proyek. Atur parameter ini ke $(SRCROOT)/{nama folder library statis}.

Capabilities

Jika Anda menggunakan Xcode 8 ke atas, aktifkan Capabilities->Push Notifications pada Application Target, seperti gambar berikut:
Jika Anda menggunakan Xcode 10 ke atas, aktifkan Capabilities-> Access WIFI Infomation pada Application Target Anda.

Menambahkan File Header

Tambahkan kode berikut pada file header referensi AppDelegate.m.

              
              // import file header fungsi MTPush yang diperlukan
#import "MTPushService.h"
// iOS10 Register file header yang diperlukan untuk APNs
#ifdef NSFoundationVersionNumber_iOS_9_x_Max
#import <UserNotifications/UserNotifications.h>
#endif
// File header untuk menggunakan fungsionalitas idfa (opsional)
#import <AdSupport/AdSupport.h>

            

Menambahkan Delegate

Tambahkan Delegate pada AppDelegate. Contoh kode:

              
              @interface AppDelegate ()<MTPushRegisterDelegate>

@end

            

Menambahkan Kode Inisialisasi

Menambahkan Kode Inisialisasi APNs

Tambahkan kode berikut ke -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

              
                //Wajib
 
    MTPushRegisterEntity * entity = [[MTPushRegisterEntity alloc] init];
  entity.types = MTPushAuthorizationOptionAlert|MTPushAuthorizationOptionSound|MTPushAuthorizationOptionProvidesAppNotificationSettings;
  if ([[UIDevice currentDevice].systemVersion floatValue] >= 8.0) {
    // Kustomisasi kategori dapat ditambahkan
    // NSSet<UNNotificationCategory *> *categories untuk iOS10 atau lebih baru
    // NSSet<UIUserNotificationCategory *> *categories untuk iOS8 dan iOS9
  }
  [MTPushService registerForRemoteNotificationConfig:entity delegate:self];

            

Menambahkan Kode Inisialisasi MTPush

Tambahkan kode berikut ke -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

              
              // Opsional
// Mendapatkan IDFA
// Untuk menggunakan fungsi IDFA, tambahkan kode ini dan isi parameter advertisingIdentifier pada metode inisialisasi
NSString *advertisingId = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];

// Wajib
// Inisialisasi Push
[MTPushService setupWithOption:launchOptions appKey:appKey
                      channel:channel
             apsForProduction:isProduction
        advertisingIdentifier:advertisingId];

            

Penjelasan Parameter

• appKey
  • Pastikan appkey yang dikonfigurasi di aplikasi sama dengan yang dihasilkan setelah aplikasi dibuat di Console.
• channel
  • Tentukan channel unduhan paket aplikasi. Untuk statistik per channel, Anda dapat mendefinisikan nilai spesifik, misal App Store.
• apsForProduction
  • Menandakan lingkungan sertifikat APNs yang digunakan aplikasi saat ini.
  • 0 (default) berarti menggunakan sertifikat pengembangan, 1 berarti menggunakan sertifikat produksi.
  • Catatan: Nilai field ini harus sama dengan lingkungan sertifikat yang dikonfigurasi di Code Signing pada Build Settings.

APNs Berhasil Terdaftar dan DeviceToken Dilaporkan

Tips: Anda dapat login ke EngageLab tanpa memanggil metode ini. Namun, notifikasi APNs tidak tersedia, hanya dapat menggunakan pesan kustom.

Implementasikan metode callback di AppDelegate.m dan tambahkan kode berikut:

              
              - (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

  /// Wajib - mendaftarkan DeviceToken
  [MTPushService registerDeviceToken:deviceToken];
}

            

Implementasi Interface Kegagalan Registrasi APNs (Opsional)

              
              - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  //Opsional
  NSLog(@"Gagal Mendaftar Remote Notifications Dengan Error: %@", error);
   [MTPushService registerDeviceToken:deviceToken];
}

            

Menambahkan Metode Callback untuk Menangani Notifikasi APNs

Implementasikan metode callback di AppDelegate.m dan tambahkan kode berikut:

              
              #pragma mark- MTPushRegisterDelegate

// Dukungan iOS 12
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center openSettingsForNotification:(UNNotification *)notification{if (notification && [notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {// Masuk langsung ke aplikasi dari antarmuka notifikasi.}else{// Masuk ke aplikasi dari pengaturan notifikasi.}
}

// Dukungan iOS 10
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(NSInteger))completionHandler {
  // Wajib
  NSDictionary * userInfo = notification.request.content.userInfo;
  if([notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {[MTPushService handleRemoteNotification:userInfo];
  }
  completionHandler(UNNotificationPresentationOptionAlert); // Untuk menjalankan metode ini, pilih apakah akan menampilkan Alert ke pengguna atau tidak. Ada tiga tipe: Badge, Sound, dan Alert.
}

// Dukungan iOS 10
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)())completionHandler {
  // Wajib
  NSDictionary * userInfo = response.notification.request.content.userInfo;
  if([response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {[MTPushService handleRemoteNotification:userInfo];
  }
  completionHandler();	// Sistem mengharuskan metode ini dijalankan}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {

  // Wajib, Dukungan iOS 7
  [MTPushService handleRemoteNotification:userInfo];
  completionHandler(UIBackgroundFetchResultNewData);
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {

  // Wajib, Untuk sistem dengan iOS 6 atau lebih rendah
  [MTPushService handleRemoteNotification:userInfo];
}

            

Menambahkan Metode Callback untuk Menangani Pesan Kustom MTPush

Untuk menggunakan fungsi pesan kustom MTPush, silakan lihat 【Panduan API iOS】 untuk mengimplementasikan callback pemrosesan pesan kustom.

Berhasil Berjalan

Debug proyek Anda. Jika konsol menampilkan log berikut, berarti integrasi Anda berhasil.

              
              2016-08-19 17:12:12.745823 219b28[1443:286814] | MTP | I - [MTCORETcpEventController] 
----- hasil login -----
uid:123456 
registrationID:171976fa8a8620a14a4 
idc:0

            

Jika Anda mengalami masalah saat debugging, silakan merujuk ke 【Panduan Debugging iOS SDK】.

Fitur Lanjutan

Pemantauan Event SDK MTush

Disarankan pengembang memasukkan jenis notifikasi berikut yang disediakan API:

extern NSString *const kMTCNetworkIsConnectingNotification; // Sedang membangun koneksi
extern NSString * const kMTCNetworkDidSetupNotification; // Koneksi berhasil
extern NSString * const kMTCNetworkDidCloseNotification; // Koneksi ditutup
extern NSString * const kMTCNetworkDidRegisterNotification; // Registrasi berhasil
extern NSString *const kMTCNetworkFailedRegisterNotification; // Registrasi gagal
extern NSString * const kMTCNetworkDidLoginNotification; // Login berhasil

extern NSString * const kMTCNetworkDidReceiveMessageNotification; // Menerima pesan kustom (non-APNS)
Data transfer KMTCNetworkDidReceiveMessageNotification dapat diperoleh melalui userInfo pada NSNotification, termasuk informasi title, content, dan extras, dll. Lihat dokumen: API SDK iOS

Layanan Statistik Notifikasi

Pengembang dapat menggunakan SDK Notification Service Extension untuk melaporkan status pengiriman setiap pesan APNs. Catatan: Data Impressions yang ditampilkan di konsol EngageLab diambil dari data pengiriman yang dilaporkan di sini.

Cara penggunaan:

• Buat Service Extension Service. Untuk detail, lihat iOS 10 Service Extension.
• Import file mtpush-extension-ios-xxx.xcframework ke proyek Service Extension Anda.
• Tambahkan Framework: libz.tbd dan libresolv.tbd.
• Panggil [mtpushSetAppkey:] untuk mengatur appkey Anda. Pastikan appkey sama dengan appkey pada aplikasi EngageLab Anda.
• Panggil metode [mtpushReceiveNotificationRequest:] untuk melaporkan apns Anda, statistik telah dilayani dengan semestinya; tampilkan apns pada callback blok metode ini.

Untuk contoh penggunaan lebih spesifik, silakan lihat kode Demo yang disertakan dalam paket zip versi. Dokumentasi referensi: API SDK iOS

Voip Push

• Diperkenalkan di iOS 8, Voip push berbasis framework PushKit memungkinkan aplikasi dibangunkan dan menjalankan kode bahkan saat aplikasi dimatikan.
• Voip tidak membedakan antara sertifikat pengembangan dan produksi. Baik Apple Push Notification service SSL (Sandbox & Production) maupun VoIP Services Certificate mendukung push Voip.

Menambahkan Library PushKit.Framework

• Tambahkan library PushKit.framework di Xcode Build Phases - Link Binary With Libraries.
• Import file header #import <PushKit/PushKit.h>.
• Implementasikan protokol PKPushRegistryDelegate di AppDelegate.

Menambahkan Izin Voip

Di Project-> Capabilities->Background Modes, aktifkan opsi Voice over IP.

Implementasi Kode

• Implementasi registrasi Voip pada metode didFinishLaunchingWithOptions.

              
              - (void)voipRegistration{
  dispatch_queue_t mainQueue = dispatch_get_main_queue();
  PKPushRegistry *voipRegistry = [[PKPushRegistry alloc] initWithQueue:mainQueue];
  voipRegistry.delegate = self;
  // Atur tipe push ke VoIP
  voipRegistry.desiredPushTypes = [NSSet setWithObject:PKPushTypeVoIP];
}

            

• Submit Token

              
              /// Sistem mengembalikan VoipToken, laporkan ke server EngageLab
- (void)pushRegistry:(PKPushRegistry *)registry didUpdatePushCredentials:(PKPushCredentials *)pushCredentials forType:(PKPushType)type{
   if (type == PKPushTypeVoIP) {
    [MTPushService registerVoipToken:pushCredentials.token];
   }
}

            

• Saat menerima push Voip, panggil interface penerimaan untuk menghitung pengiriman Voip.

              
              - (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(PKPushType)type{
  if (type == PKPushTypeVoIP) {
    // Kirim penerimaan ke server EngageLab
    [MTPushService handleVoipNotification:payload.dictionaryPayload];
  }
}

- (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(PKPushType)type withCompletionHandler:(void(^)(void))completion{
   if (type == PKPushTypeVoIP) {
    // Kirim penerimaan ke server EngageLab
    [MTPushService handleVoipNotification:payload.dictionaryPayload];
   }
}

            

Dukungan Teknis

Jika mengalami masalah saat integrasi

• Bacalah dokumen dengan seksama untuk memastikan tidak ada langkah yang terlewat.
• Anda dapat mencari pertanyaan serupa di EngageLab. Agar masalah dapat diselesaikan lebih cepat, mohon sertakan informasi berikut saat meminta bantuan:
  • Produk yang ingin dikonsultasikan adalah MTPush, apakah menggunakan produk EngageLab lainnya.
  • API yang Anda panggil, parameter yang dikirimkan, pesan error lengkap, dan waktu terjadinya exception.
  • Jika tidak menerima pesan, sertakan Appkey aplikasi, Message ID pesan, dan registration ID perangkat.
  • Jika masalah disebabkan oleh SDK, sertakan versi SDK terkait dan catatan log lengkap. Upload log menggunakan file TXT.
  • Jika perangkat bermasalah adalah iOS, sertakan model dan sistem secara spesifik.