Panduan Integrasi iOS

iOS SDK EngageLab Behavioral Verification dirancang untuk pengembang yang ingin mengintegrasikan ke dalam pengembangan klien native iOS. SDK ini tidak bergantung pada pustaka pihak ketiga mana pun.

Gambaran Produk

Persyaratan Lingkungan

Mengimpor SDK

1. Jika Anda menambahkan SDK secara manual, seret file GTCaptcha4.framework yang diperoleh dari hasil unduhan ke dalam proyek Anda, pastikan opsi Copy items if needed dicentang.

   Gunakan metode Linked Frameworks and Libraries untuk mengimpor framework. Setelah menyeret GTCaptcha4.framework ke dalam proyek, pastikan file .framework sudah ditambahkan ke PROJECT -> Build Phases -> Linked Frameworks and Libraries.

   

   SDK menyediakan format XCFramework, yang dapat ditemukan di direktori SDK -> XCFramework pada file unduhan sebagai GTCaptcha4.xcframework.

2. Untuk Category pada pustaka statis, tambahkan -ObjC pada Other Linker Flags di bawah Build Settings untuk target yang sesuai.

   

3. Anda juga perlu menyertakan GT4Captcha4.Bundle ke dalam proyek Anda; jika tidak, proses verifikasi tidak akan berjalan. Seret GTCaptcha4.Bundle dari direktori SDK ke dalam proyek Anda.

   

Pada WWDC23, Apple mengumumkan kebijakan privasi baru untuk aplikasi (termasuk SDK), dengan sesi khusus Get started with privacy manifests - WWDC23 - Videos - Apple Developer. Pada 27 Juli, Apple merilis pembaruan bahwa mulai musim gugur 2023, jika aplikasi yang diunggah menggunakan API terkait tanpa menyediakan privacy manifest, Anda akan menerima notifikasi email. Mulai musim semi 2024, privacy manifest menjadi wajib. Untuk API yang terlibat dan alasan penggunaannya, silakan lihat: Describing use of required reason API | Apple Developer Documentation. Jika alasan penggunaan tidak tercantum, Anda dapat langsung mengajukan penjelasan penggunaan spesifik.

Untuk membuat privacy manifest baru, silakan lihat Privacy manifest files | Apple Developer Documentation.

SDK iOS Behavioral Verification menggunakan beberapa fungsi untuk mendapatkan kapasitas disk dan informasi deteksi lingkungan demi tujuan kontrol risiko, melibatkan kategori NSPrivacyAccessedAPICategoryDiskSpace dan NSPrivacyAccessedAPICategoryFileTimestamp. Hal ini dinyatakan di sini.

Antarmuka Konfigurasi

Silakan merujuk ke Proses Struktur Produk Behavioral Verification. Anda harus terlebih dahulu menyiapkan antarmuka sisi server yang sesuai di backend Anda dan mengonfigurasi captchaId serta Key yang diperoleh dari EngageLab Management Console.

Pengembang yang mengintegrasikan SDK perlu menggunakan antarmuka berikut yang disediakan oleh iOS SDK:

1. Konfigurasi inisialisasi verifikasi menggunakan ID.
2. Memulai proses verifikasi.
3. Mendapatkan parameter hasil verifikasi dan melakukan validasi sekunder pada parameter hasil yang dikirimkan untuk mencegah pemalsuan.
4. Menangani kemungkinan masalah selama proses verifikasi dengan metode error delegate.

Anda perlu mengikuti protokol <GTCaptcha4SessionTaskDelegate> untuk menangani hasil verifikasi dan kemungkinan error.

Silakan lihat Contoh Kode di bawah ini untuk kode integrasi.

Kompilasi dan Jalankan Proyek Anda

Kompilasi proyek Anda dan rasakan proses verifikasi perilaku.

Contoh Kode

Inisialisasi dan Pemanggilan Verifikasi

Impor file header dari pustaka dinamis verifikasi GTCaptcha4.framework ke dalam proyek Anda.

              
              #import <GTCaptcha4/GTCaptcha4.h>

            

Sebagai contoh, integrasi dilakukan pada sebuah UIButton.

1. Inisialisasi

   Inisialisasi instance dari manajer verifikasi GTCaptcha4Session. Pada metode inisialisasi UIButton, panggil metode registrasi dari instance GTCaptcha4Session untuk mendapatkan data registrasi:

   #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" @interface ViewController () <GTCaptcha4SessionTaskDelegate> @property (strong, nonatomic) IBOutlet UIButton *startBtn; @property (nonatomic, strong) GTCaptcha4Session *captchaSession; @end @implementation ViewController - (GTCaptcha4Session *)captchaSession { if (!_captchaSession) { /// Membuat instance GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration]; // config.timeout = 8.0f; /// Atur alamat halaman perantara, wajib diisi sesuai contoh config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html"; /// Atur apiServer dan staticServer, wajib diisi sesuai contoh config.apiServers = @[@"captcha-api.engagelab.com"]; config.staticServers = @[@"captcha-stat.engagelab.com/www/js"]; /// Protokol permintaan config.protocol = @"https"; _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config]; _captchaSession.delegate = self; } return _captchaSession; } - (void)viewDidLoad { [super viewDidLoad]; // Pre-inisialisasi sesi verifikasi. Jika tidak dipanggil di sini, akan dilakukan lazy loading. [self captchaSession]; [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside]; }

                 
                 #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   
   @interface ViewController () <GTCaptcha4SessionTaskDelegate>
   
   @property (strong, nonatomic) IBOutlet UIButton *startBtn;
   
   @property (nonatomic, strong) GTCaptcha4Session *captchaSession;
   
   @end
   
   @implementation ViewController
   
   - (GTCaptcha4Session *)captchaSession {
       if (!_captchaSession) {
           /// Membuat instance
           GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration];
           // config.timeout = 8.0f;
           /// Atur alamat halaman perantara, wajib diisi sesuai contoh
           config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html";
           /// Atur apiServer dan staticServer, wajib diisi sesuai contoh
           config.apiServers = @[@"captcha-api.engagelab.com"];
           config.staticServers = @[@"captcha-stat.engagelab.com/www/js"];
           /// Protokol permintaan
           config.protocol = @"https";
           _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config];
   
           _captchaSession.delegate = self;
       }
   
       return _captchaSession;
   }
   
   - (void)viewDidLoad {
       [super viewDidLoad];
   
       // Pre-inisialisasi sesi verifikasi. Jika tidak dipanggil di sini, akan dilakukan lazy loading.
       [self captchaSession];
   
       [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside];
   }
   
               

   Tampilkan blok kode ini di jendela mengambang

   Untuk item konfigurasi opsional lainnya, silakan lihat antarmuka atau properti yang didefinisikan dalam GTCaptcha4SessionConfiguration.

2. Memanggil Verifikasi

   Setelah inisialisasi, panggil metode berikut untuk menjalankan verifikasi:

   - (void)start { [self.captchaSession verify]; }

                 
                 - (void)start {
       [self.captchaSession verify];
   }
   
               

   Tampilkan blok kode ini di jendela mengambang

Menangani Hasil Verifikasi

Verifikasi hanya dianggap selesai setelah hasil verifikasi divalidasi. Anda perlu menangani metode delegate berikut setelah mengikuti protokol GTCaptcha4SessionTaskDelegate:

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceive:(NSString *)code result:(NSDictionary *)result {
    NSLog(@"result: %@", result);
    // code bernilai @"1" jika pengguna berhasil verifikasi, @"0" jika gagal
    if ([@"1" isEqualToString:code]) {
        if (result && result.count > 0) {
            // Konversi dictionary ke format form untuk dikirim (susun sesuai kebutuhan format data antarmuka aktual)
            __block NSMutableArray<NSString *> *kvPairs = [NSMutableArray array];

            [result enumerateKeysAndObjectsUsingBlock:^(id  _Nonnull key, id  _Nonnull obj, BOOL * _Nonnull stop) {
                if ([key isKindOfClass:[NSString class]] &&
                    [obj isKindOfClass:[NSString class]]) {
                    NSString *kvPair = [NSString stringWithFormat:@"%@=%@", key, obj];
                    [kvPairs addObject:kvPair];
                }
            }];

            NSString *formStr = [kvPairs componentsJoinedByString:@"&"];
            NSData *data = [formStr dataUsingEncoding:NSUTF8StringEncoding];

            // Antarmuka verifikasi backend yang disediakan bisnis
            NSURL *url = [NSURL URLWithString:@"https://***/validate"];
            NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
            request.HTTPMethod  = @"POST";
            request.HTTPBody    = data;

            // Kirim ke backend untuk validasi hasil
            [[[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
                if (!error && data) {
                    // Tangani hasil verifikasi
                    NSString *msg = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
                    NSLog(@"result: %@", msg);
                }
                else {
                    NSLog(@"error: %@", error);
                }
            }] resume];
        }
    }
}

            

Menangani Error Verifikasi

Error tak terduga dapat terjadi selama proses verifikasi. Anda dapat menanganinya pada metode delegate berikut setelah mengikuti protokol GTCaptcha4SessionTaskDelegate:

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceiveError:(GTC4Error *)error {
    // Tampilkan informasi error dan kode error kepada pengguna

    // Catat detail error
    NSLog(@"error: %@", error.description);
}

            

Sangat disarankan untuk menampilkan alasan error dan kode error kepada pengguna saat terjadi error verifikasi, agar memudahkan penelusuran masalah secara online.

Contoh Swift

Untuk contoh kode yang lebih lengkap, silakan lihat Demo resmi yang disediakan. Untuk contoh kode Swift, silakan lihat file DefaultDemoViewController.swift pada source code Demo.