Mengintegrasikan Google Cloud Fraud Defense dengan aplikasi iOS

Anda dapat mengintegrasikan Google Cloud Fraud Defense ke dalam aplikasi iOS untuk mengevaluasi sinyal perangkat klien dan melindungi interaksi pengguna seluler dari penyalahgunaan otomatis.

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

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

Peringatan: Upgrade Mobile SDK iOS Fraud Defense Anda untuk mencegah potensi error aplikasi. Kami telah mengidentifikasi masalah teknis yang memengaruhi versi SDK sebelum v18.9.0 yang menyebabkan error bagi pengguna di iOS 27 Beta. Untuk memastikan stabilitas aplikasi yang berkelanjutan dan melindungi pengguna akhir Anda, upgrade dependensi aplikasi Anda ke Fraud Defense iOS Mobile SDK versi 18.9.0 atau yang lebih baru.

Penting: Perhatikan kebijakan penghentian penggunaan dan penonaktifan dan rencanakan untuk mengupgrade SDK secara rutin.

Sebelum memulai

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

   Catatan: reCAPTCHA mendukung perangkat iPhone dan iPad.

2. Menyiapkan lingkungan Anda untuk Google Cloud Fraud Defense.

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 konsolGoogle Cloud , lakukan hal berikut:

     1. Buka halaman Google Cloud Fraud Defense.

        Buka Google Cloud Fraud Defense

     2. Pilih tab Keys.
     3. Dalam daftar kunci reCAPTCHA, temukan 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 Anda

Untuk menyiapkan lingkungan pengembangan, lakukan hal berikut:

1. Download dan instal Xcode versi terbaru dan buat aplikasi tampilan tunggal iOS kosong yang 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.10.0-beta01"
        ...
      
      end
      

   3. Instal dependensi yang diperlukan dengan menjalankan pod update.

      Catatan: Menjalankan pod clone tidak akan 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. Dalam dialog Xcode, masukkan detail berikut:

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

      Xcode akan menginstal SDK dan dependensi yang diperlukan.

   Flutter

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

   React Native

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

   Download langsung

   1. Jika Anda 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, update aplikasi dengan kode berikut:

   Swift dengan Storyboard

   1. Update 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 closure di akhir:

      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 closure di akhir:

      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 tiruan 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. Update ViewController.h.

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

   4. Update 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 selesai. Untuk mengurangi latensi ini, lakukan inisialisasi klien sedini mungkin, seperti selama panggilan onCreate() dari class Application kustom. Anda tidak boleh membuat elemen UI memblokir SDK reCAPTCHA.

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 closure di akhir:

      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 closure di akhir:

      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() dengan 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);
      }];
      

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

3. Menguji 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 Anda untuk menemukan token reCAPTCHA (string alfanumerik), yang ditampilkan jika integrasi berhasil.

Bermigrasi dari metode getClient 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 lagi 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 RecaptchaError.

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 closure di akhir:

// 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
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 closure di akhir:

// 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: Batas waktu default 10 detik digunakan untuk konsistensi.

Swift

1. Menetapkan 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 trailing closure:

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

Objective-C

1. Menetapkan waktu tunggu saat memanggil execute.

     [recaptchaClient execute:RecaptchaAction.login
         withTimeout: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 dapat berkomunikasi dengan layanan reCAPTCHA dengan berhasil, hal itu mungkin karena API mengalami error. Anda harus menambahkan logika di aplikasi untuk menangani error tersebut dengan baik.

Untuk mengetahui detail selengkapnya tentang mitigasi 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 dianotasi dari server backend Anda, bukan dari perangkat seluler.