Mengintegrasikan Google Cloud Fraud Defense dengan aplikasi iOS

Halaman ini menjelaskan cara mengintegrasikan Google Cloud Fraud Defense di aplikasi iOS Anda.

Karena variasi perangkat seluler dalam hal ukuran layar, performa, dan UI aplikasi, tantangan reCAPTCHA kotak centang visual (Saya bukan robot) tidak tersedia untuk aplikasi seluler iOS. Sebagai gantinya, Anda dapat menerapkan strategi penegakan bertingkat sendiri, seperti alur MFA untuk menyediakan jalur penukaran alternatif untuk traffic yang mencurigakan.

SDK menggunakan refleksi dan kode dinamis untuk memungkinkan pembaruan dan penyempurnaan sistem deteksi di aplikasi atau SDK yang sudah di-deploy. Untuk menghindari gangguan pada aplikasi, class yang tersedia dalam sistem dibatasi ke daftar yang dikontrol dengan cermat.

Penting: Perhatikan kebijakan penghentian dan penonaktifan serta rencanakan untuk mengupgrade SDK secara berkala.

Sebelum memulai

1. Tetapkan SDK minimum aplikasi Anda ke iOS 15 atau buat aplikasi seluler baru.

   Catatan: reCAPTCHA mendukung perangkat iPhone dan iPad.

2. Siapkan lingkungan Anda untuk reCAPTCHA.

3. Buat kunci reCAPTCHA untuk platform aplikasi iOS.

   Atau, Anda dapat menyalin ID kunci reCAPTCHA yang ada untuk iOS dengan melakukan salah satu langkah berikut:

   • Untuk menyalin ID kunci yang ada dari Google Cloud konsol, lakukan hal berikut:

     1. Buka halaman reCAPTCHA.

        Buka reCAPTCHA

     2. Dalam daftar kunci reCAPTCHA, arahkan kursor ke kunci yang ingin Anda salin, lalu klik .
   • Untuk menyalin ID kunci yang ada menggunakan REST API, gunakan metode projects.keys.list.
   • Untuk menyalin ID kunci yang ada menggunakan gcloud CLI, gunakan perintah gcloud recaptcha keys list.

4. Memiliki akun GitHub.

5. Baca detail privasi Apple.

Menyiapkan lingkungan iOS

Untuk menyiapkan lingkungan pengembangan, lakukan hal berikut:

1. Download dan instal Xcode versi terbaru, lalu buat aplikasi tampilan tunggal iOS kosong baru.

2. Download SDK menggunakan salah satu cara berikut:

   CocoaPods

   1. Download dan instal CocoaPods.

   2. Buat Podfile dan tambahkan baris berikut ke Podfile Anda:

      source "https://github.com/CocoaPods/Specs.git"
      
      target 'AppTarget' do
      
        # Podfiles must include use_frameworks! or
        # use_frameworks! :linkage => :static
        use_frameworks!
      
        pod "RecaptchaEnterprise", "18.9.0"
        ...
      
      end
      

   3. Instal dependensi yang diperlukan dengan menjalankan pod update.

      Catatan: Menjalankan pod clone tidak menginstal dependensi yang diperlukan.

   Swift Package Manager

   1. Di Xcode, pilih File > Add Packages, lalu masukkan URL berikut di kolom Search atau Enter Package URL:

      https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk
      

   2. Di dialog Xcode, masukkan detail berikut:

      • Nama pengguna GitHub.
      • Token akses pribadi yang Anda buat menggunakan petunjuk GitHub. Token Akses Pribadi harus memiliki cakupan yang tercantum dalam dialog Xcode Sign In.

      Xcode menginstal SDK dan dependensi yang diperlukan.

   Flutter

   Untuk mengetahui petunjuk mendetail tentang cara menggunakan reCAPTCHA melalui Flutter, lihat dokumentasi Flutter.

   ReactNative

   Untuk mengetahui petunjuk mendetail tentang cara menggunakan reCAPTCHA melalui React Native, lihat dokumentasi React Native.

   Download langsung

   1. Jika ingin mendownload SDK dan dependensinya sebagai xcframework, download klien.

      Catatan: Tambahkan semua biner sebagai xcframework statis.

Mengintegrasikan Fraud Defense dengan aplikasi iOS Anda

Untuk mengintegrasikan Fraud Defense dengan aplikasi iOS Anda, ikuti langkah-langkah berikut di Xcode:

1. Untuk membuat instance SDK dengan kunci reCAPTCHA (KEY_ID) yang Anda buat, perbarui aplikasi dengan kode berikut:

   Swift dengan Storyboard

   1. Perbarui ViewController.swift.

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Task {
            do {
              self.recaptchaClient = try await Recaptcha.fetchClient(withSiteKey: "KEY_ID")
            } catch let error as RecaptchaError {
               print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
            }
          }
        }
      }
      

      Jika versi OS minimum aplikasi Anda kurang dari 13, gunakan penutupan akhir sebagai gantinya:

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Recaptcha.fetchClient(withSiteKey: "KEY_ID") { client, error in
            guard let client = client else {
                print("RecaptchaClient creation error: \(error).")
              return
            }
            self.recaptchaClient = client
          }
        }
      }
      

   Swift dengan SwiftUI

   1. Buat class ViewModel.

      import RecaptchaEnterprise
      
      @MainActor class ViewModel: ObservableObject {
        private var recaptchaClient: RecaptchaClient?
      
        init() {
           Task {
            do {
              self.recaptchaClient = try await Recaptcha.fetchClient(withSiteKey: "KEY_ID")
            } catch let error as RecaptchaError {
               print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
            }
          }
        }
      }
      

      Jika versi OS minimum aplikasi Anda kurang dari 13, gunakan penutupan akhir sebagai gantinya:

      import RecaptchaEnterprise
      
      class ViewController: UIViewController {
        var recaptchaClient: RecaptchaClient?
      
        override func viewDidLoad() {
          super.viewDidLoad()
          Recaptcha.fetchClient(withSiteKey: "KEY_ID") { client, error in
            guard let client = client else {
                print("RecaptchaClient creation error: \(error).")
              return
            }
            self.recaptchaClient = client
          }
        }
      }
      

   2. Buat instance ViewModel di ContentView.swift.

      import SwiftUI
      import RecaptchaEnterprise
      
      struct ContentView: View {
        @StateObject private var viewModel = ViewModel()
      
        var body: some View {
        }
      }
      
      struct ContentView_Previews: PreviewProvider {
        static var previews: some View {
          ContentView()
        }
      }
      

   Objective-C

   1. Jika aplikasi Anda ditulis dalam Objective-C, buat file Swift dummy dan sertakan impor berikut untuk memastikan Xcode dapat menemukan dan menautkan library Swift.

      import Foundation
      

   2. Untuk memastikan kode Swift ditautkan dengan benar, buka Target > Build Settings > Always Embed Swift Standard Libraries dan pastikan opsi tersebut ditetapkan ke Yes.

   3. Perbarui ViewController.h.

      #import <RecaptchaEnterprise/RecaptchaEnterprise.h>
      
      @interface ViewController : UIViewController
      @property (strong, atomic) RecaptchaClient *recaptchaClient;
      @end
      

   4. Perbarui ViewController.m.

      @implementation ViewController
      [Recaptcha fetchClientWithSiteKey:@"KEY_ID"
            completion:^void(RecaptchaClient* recaptchaClient, NSError* error) {
              if (!recaptchaClient) {
                NSLog(@"%@", (RecaptchaError *)error.errorMessage);
                return;
              }
              self->_recaptchaClient = recaptchaClient;
            }
      ];
      @end
      

   Inisialisasi SDK dapat memerlukan waktu beberapa detik untuk diselesaikan. Untuk mengurangi latensi ini, lakukan inisialisasi klien sesegera mungkin, seperti selama panggilan onCreate() class Application kustom. Anda tidak boleh membuat elemen UI memblokir reCAPTCHA SDK.

2. Buat tombol untuk memanggil reCAPTCHA dan memicu execute().

   Swift dengan Storyboard

   1. Di storyboard, buat tombol.
   2. Buat tindakan di ViewController yang ditautkan ke tombol yang Anda buat.

   3. Panggil metode execute() yang meneruskan tindakan Login untuk menampilkan token reCAPTCHA menggunakan cuplikan kode berikut:

      guard let recaptchaClient = recaptchaClient else {
        print("RecaptchaClient creation failed.")
        return
      }
      Task {
        do {
          let token = try await recaptchaClient.execute(withAction: RecaptchaAction.login)
          print(token)
        } catch let error as RecaptchaError {
          print(error.errorMessage)
        }
      }
      

      Jika versi OS minimum aplikasi Anda kurang dari 13, gunakan penutupan akhir sebagai gantinya:

      guard let recaptchaClient = recaptchaClient else {
        print("RecaptchaClient creation failed.")
        return
      }
      recaptchaClient.execute(withAction: RecaptchaAction.login) { token, error in
        if let token = token {
          print(token)
        } else {
          print(error)
        }
      }
      

   Swift dengan SwiftUI

   1. Perbarui ViewModel.swift dengan kode eksekusi:

      import RecaptchaEnterprise
      
      @MainActor class ViewModel: ObservableObject {
      
        func execute() {
          guard let recaptchaClient = self.recaptchaClient else {
            print("Client not initialized correctly.")
            return
          }
      
          Task {
            do {
              let token = try await recaptchaClient.execute(withAction: RecaptchaAction.login)
              print(token)
            } catch let error as RecaptchaError {
              print(error.errorMessage)
            }
          }
        }
      }
      

      Jika versi OS minimum aplikasi Anda kurang dari 13, gunakan penutupan akhir sebagai gantinya:

      guard let recaptchaClient = recaptchaClient else {
        print("RecaptchaClient creation failed.")
        return
      }
      recaptchaClient.execute(withAction: RecaptchaAction.login) { token, error in
        if let token = token {
          print(token)
        } else {
          print(error)
        }
      }
      

   2. Perbarui ContentView.swift.

      import SwiftUI
      import RecaptchaEnterprise
      
      struct ContentView: View {
        @StateObject private var viewModel = ViewModel()
      
        var body: some View {
      
          Button {
            viewModel.execute()
          } label: {
            Text("Execute")
          }.padding()
      
          Spacer()
        }
      }
      
      struct ContentView_Previews: PreviewProvider {
        static var previews: some View {
          ContentView()
        }
      }
      

   Objective-C

   1. Di storyboard, buat tombol.
   2. Buat tindakan di ViewController yang ditautkan ke tombol yang Anda buat.

   3. Panggil metode execute() yang meneruskan tindakan Login untuk menampilkan token reCAPTCHA:

      if (!self->_recaptchaClient) {
        return;
      }
      
      [recaptchaClient execute:RecaptchaAction.login
          completion:^void(NSString* _Nullable  token, NSError* _Nullable error) {
        if (!token) {
          NSLog (@"%@", (RecaptchaError *)error.errorMessage);
          return;
        }
        NSLog (@"%@", token);
      }];
      

   execute API klien dapat memerlukan waktu beberapa detik untuk diselesaikan, seperti dalam kondisi jaringan yang lambat atau jika menunggu inisialisasi latar belakang selesai. Pastikan panggilan execute() tidak memblokir peristiwa UI, seperti menekan tombol.

3. Uji aplikasi Anda:

   1. reCAPTCHA menggunakan App Attest Apple sebagai bagian dari mesin deteksinya. Jika Anda tidak berencana menggunakan kunci pengujian dengan skor tetap untuk pengembangan lokal, lakukan hal berikut:

      1. Di Xcode, tambahkan kemampuan App Attest ke aplikasi Anda.

      2. Di file .entitlements project Anda, tetapkan lingkungan App Attest ke production.

   2. Untuk membersihkan lingkungan build Xcode, di menu Product , klik Clean Build Folder.

   3. Untuk menjalankan aplikasi, di menu Product, klik Run.

   4. Di aplikasi yang dimuat, klik tombol yang Anda buat sebelumnya.

   5. Amati jendela output debug untuk token reCAPTCHA (string alfanumerik), yang ditampilkan jika integrasi berhasil.

Bermigrasi dari method API ke metode fetchClient

Metode fetchClient menampilkan RecaptchaClient yang mencoba ulang inisialisasi saat terjadi kegagalan jaringan. Jika aplikasi tidak memiliki akses jaringan saat klien dibuat, klien akan terus mencoba dan berhasil melakukan inisialisasi saat jaringan diperoleh.

Jika Anda memanggil execute(timeout) dan klien belum siap, klien akan mencoba melakukan inisialisasi sebelum menampilkan token atau RecaptchaErrorCode.

Contoh berikut menunjukkan cara bermigrasi dari getClient ke fetchClient.

Swift dengan Storyboard

// Migrate from getClient
func initializeWithGetClient() {
  Task {
    do {
      self.recaptchaClient = try await Recaptcha.getClient(withSiteKey: "KEY_ID")
    } catch let error as RecaptchaError {
        print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
    }
  }
}

// Migrate to fetchClient
func initializeWithFetchClient() {
  Task {
    do {
      self.recaptchaClient = try await Recaptcha.fetchClient(withSiteKey: "KEY_ID")
    } catch let error as RecaptchaError {
        print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
    }
  }
}

Jika versi OS minimum aplikasi Anda kurang dari 13, gunakan penutupan akhir sebagai gantinya:

// Migrate from getClient
override func initializeWithGetClient() {
  Recaptcha.getClient(withSiteKey: "KEY_ID") { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }
}

// Migrate to fetchClient
override func initializeWithFetchClient() {
  Recaptcha.fetchClient(withSiteKey: "KEY_ID") { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }
}

Swift dengan SwiftUI

// Migrate from getClient
initializeWithGetClient() {
    Task {
    do {
      self.recaptchaClient = try await Recaptcha.getClient(withSiteKey: "KEY_ID")
    } catch let error as RecaptchaError {
        print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
    }
  }
}

// Migrate to fetchClient
initializeWithFetchClient() {
    Task {
    do {
      self.recaptchaClient = try await Recaptcha.fetchClient(withSiteKey: "KEY_ID")
    } catch let error as RecaptchaError {
        print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
    }
  }
}

Jika versi OS minimum aplikasi Anda kurang dari 13, gunakan penutupan akhir sebagai gantinya:

// Migrate from getClient
func initializeWithGetClient() {
  super.viewDidLoad()
  Recaptcha.getClient(withSiteKey: "KEY_ID") { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }
}

// Migrate to fetchClient
func initializeWithFetchClient() {
  super.viewDidLoad()
  Recaptcha.fetchClient(withSiteKey: "KEY_ID") { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }
}

Objective-C

// Migrate from getClient
@implementation ViewController
[Recaptcha getClientWithSiteKey:@"KEY_ID"
      completion:^void(RecaptchaClient* recaptchaClient, NSError* error) {
        if (!recaptchaClient) {
          NSLog(@"%@", (RecaptchaError *)error.errorMessage);
          return;
        }
        self->_recaptchaClient = recaptchaClient;
      }
];
@end

// Migrate to fetchClient
@implementation ViewController
[Recaptcha fetchClientWithSiteKey:@"KEY_ID"
      completion:^void(RecaptchaClient* recaptchaClient, NSError* error) {
        if (!recaptchaClient) {
          NSLog(@"%@", (RecaptchaError *)error.errorMessage);
          return;
        }
        self->_recaptchaClient = recaptchaClient;
      }
];
@end

Menetapkan waktu tunggu untuk panggilan API

Anda dapat menentukan nilai waktu tunggu untuk execute API menggunakan properti withTimeout.

Catatan: Waktu tunggu default 10 detik digunakan untuk konsistensi.

Swift

1. Tetapkan waktu tunggu saat memanggil execute.

     Task {
       do {
         let token = try await recaptchaClient.execute(
           withAction: RecaptchaAction.login,
           withTimeout: 10000)
         print(token)
       } catch let error as RecaptchaError {
         print(error.errorMessage)
       }
     }
   

   Jika versi OS minimum aplikasi Anda kurang dari 13, gunakan a penutupan akhir sebagai gantinya:

     recaptchaClient.execute(
       withAction: RecaptchaAction.login,
       withTimeout: 10000
     ) { token, error in
       if let token = token {
         print(token)
       } else {
         print(error)
       }
     }
   

Objective-C

1. Tetapkan waktu tunggu saat memanggil execute.

     [recaptchaClient execute:RecaptchaAction.login
         witTimeout:10000.0
         completion:^void(NSString* _Nullable  token, NSError* _Nullable error) {
       if (!token) {
         NSLog (@"%@", (RecaptchaError *)error.errorMessage);
         return;
       }
       NSLog (@"%@", token);
     }];
   

Menangani error

Jika aplikasi Anda tidak berhasil melakukan komunikasi dengan layanan reCAPTCHA, hal itu mungkin karena API mengalami error. Anda harus menambahkan logika ke dalam aplikasi untuk menangani error tersebut dengan baik.

Untuk mengetahui detail selengkapnya tentang mitigasi untuk error API umum, lihat RecaptchaErrorCode.

Referensi API

Untuk referensi lengkap reCAPTCHA API untuk iOS, lihat RecaptchaEnterprise.

Langkah berikutnya

• Untuk menilai token respons reCAPTCHA, buat penilaian.

  Catatan: Token respons reCAPTCHA dinilai dan diberi anotasi dari server backend Anda, bukan dari perangkat seluler.