reCAPTCHA Enterprise と iOS アプリの統合

このページでは、reCAPTCHA Enterprise を iOS アプリに統合する方法について説明します。

画面サイズ、パフォーマンス、アプリの UI に関してモバイル デバイスが多様なため、ビジュアル チェックボックス reCAPTCHA チャレンジ（私はロボットではありません）は利用できません。代わりに、MFA フローなどの独自の階層型適用戦略を実装し、不審なトラフィックに対する代替的な救済パスを提供できます。

注: SDK では、リフレクションと動的コードを利用して、すでにデプロイされているアプリケーションや SDK で検出システムを更新、調整できます。アプリケーションとの干渉を避けるために、システムで使用できる一連のクラスは慎重に管理されたリストに制限されています。

準備

1. アプリの最小 SDK を iOS 11 に設定するか、新しいモバイルアプリを作成します。

2. reCAPTCHA Enterprise の環境を準備します。

3. iOS アプリ プラットフォーム用の reCAPTCHA キーを作成します。

   別の方法としては、次のいずれかの手順で、iOS 用の既存の reCAPTCHA キーの ID をコピーできます。

   • Google Cloud コンソールから既存のチェックボックスのキーの ID をコピーするには、次の操作を行います。

     1. [reCAPTCHA Enterprise] ページに移動します。

        [reCAPTCHA Enterprise] に移動

     2. reCAPTCHA キーのリストで、コピーするキーの上にポインタを置き、[] をクリックします。
   • REST API を使用して既存の鍵の ID をコピーするには、projects.keys.list メソッドを使用します。
   • gcloud CLI を使用して既存の鍵の ID をコピーするには、gcloud recaptcha keys list コマンドを使用します。

4. GitHub アカウントを用意します。

5. Apple 関連のプライバシーの詳細を確認します。

iOS 環境を準備する

開発環境を準備する手順は次のとおりです。

1. 最新バージョンの Xcode をダウンロードしてインストールし、空の新しい iOS シングルビュー アプリケーションを作成します。

2. 次のいずれかの方法で SDK をダウンロードします。

   CocoaPods

   1. CocoaPods をダウンロードしてインストールします。

   2. Podfile を作成し、次の行を Podfile に追加します。

      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.5.0"
        ...
      
      end
      

   3. pod update を実行して、必要な依存関係をインストールします。

      注: pod clone を実行しても、必要な依存関係はインストールされません。

   Swift Package Manager

   1. XCode で [File] > [Add Packages] を選択し、[Search] または [Enter Package URL] フィールドに次の URL を入力します: https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk

   2. [XCode] ダイアログで次の項目を入力します。

      • GitHub のユーザー名。
      • GitHub の手順を使用して作成した個人用のアクセス トークン。個人用アクセス トークンには、[XCode ログイン] ダイアログに表示されているスコープが必要です。

      Xcode で SDK と必要な依存関係がインストールされます。

   Flutter

   Flutter で reCAPTCHA Enterprise を使用する方法について詳しくは、Flutter のドキュメントをご覧ください。

   ReactNative

   React Native で reCAPTCHA Enterprise を使用する方法について詳しくは、React Native のドキュメントをご覧ください。

   直接ダウンロード

   1. SDK とその依存関係を xcframework としてダウンロードする場合は、クライアントをダウンロードしてください。

      注: すべてのバイナリを静的 xcframework として追加します。

アプリを構成する

Swift または Objective-C でアプリを作成できます。

アプリを構成するには、アプリに次のファイルを追加します。

Swift

1. アプリが Swift で記述されている場合は、次のインポートを含めます。

   #import RecaptchaEnterprise
   

Objective-C

1. アプリが Objective-C で記述されている場合は、ダミーの Swift ファイルを作成し、次のインポートを含めて、Xcode が Swift ライブラリを検出、リンクできるようにします。

   import Foundation
   

2. Swift コードが正しくリンクされていることを確認します。[Target] > [Build Settings] > [Always Embed Swift Standard Libraries] に移動して、オプションが Yes に設定されていることを確認してください。

reCAPTCHA Enterprise と iOS アプリを統合する

reCAPTCHA Enterprise を iOS アプリと統合するには、Xcode で次の手順を行います。

注: reCAPTCHA SDK のレイテンシが高くなる可能性があるため、たとえばアプリの読み込み時などは、できるだけ早く Recaptcha.getClient(siteKey:) と execute() を呼び出すことをおすすめします。reCAPTCHA SDK で UI 要素をブロックしないでください。

1. 作成した reCAPTCHA キー（KEY_ID）を使用して SDK をインスタンス化するには、次のコードでアプリを更新します。

   Swift とストーリーボード

   1. ViewController.swift を更新します。

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

      アプリケーションの最小 OS バージョンが 13 未満の場合は、代わりに末尾クロージャを使用します。

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

   Swift と SwiftUI

   1. ViewModel クラスを作成します。

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

      アプリケーションの最小 OS バージョンが 13 未満の場合は、代わりに末尾クロージャを使用します。

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

   2. ContentView.swift で ViewModel をインスタンス化します。

      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. ViewController.h を更新します。

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

   2. ViewController.m を更新します。

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

2. reCAPTCHA Enterprise を呼び出して execute() をトリガーするボタンを作成します。

   Swift とストーリーボード

   1. ストーリーボードにボタンを作成します。
   2. 作成したボタンにリンクされている ViewController にアクションを作成します。

   3. execute() メソッドを呼び出して Login アクションを渡し、次のコード スニペットを使用して reCAPTCHA トークンを返します。

      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)
        }
      }
      

      アプリケーションの最小 OS バージョンが 13 未満の場合は、代わりに末尾クロージャを使用します。

      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 と SwiftUI

   1. 実行コードで ViewModel.swift を更新します。

      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)
            }
          }
        }
      }
      

      アプリケーションの最小 OS バージョンが 13 未満の場合は、代わりに末尾クロージャを使用します。

      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. 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. ストーリーボードにボタンを作成します。
   2. 作成したボタンにリンクされている ViewController にアクションを作成します。

   3. execute() メソッドを呼び出して Login アクションを渡し、次のコード スニペットを使用して 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);
      }];
      

3. アプリケーションをテストする

   1. reCAPTCHA Enterprise は、検出エンジンの一部として Apple の AppAttest を使用します。ローカルでの開発に固定スコアを持つテストキーを使用する予定がない場合は、次の手順を行います。

      1. Xcode で、アプリに App Attest 機能を追加します。

      2. プロジェクトの .entitlements ファイルで、App Attest 環境を production に設定します。

   2. Xcode ビルド環境をクリーンアップするには、[Product] メニューで [Clean Build Folder] をクリックします。

   3. アプリケーションを実行するには、[Product] メニューで [Run] をクリックします。

   4. 読み込んだアプリケーションで、前に作成したボタンをクリックします。

   5. デバッグ出力ウィンドウを確認します。統合が成功した場合、reCAPTCHA トークン（英数字文字列）が返されます。

API 呼び出しのタイムアウトを設定する

getClient API と execute API のタイムアウト値を指定するには、各 API の withTimeout プロパティを使用します。

注: 整合性を保つために、getClient と execute の両方の API でデフォルトのタイムアウト（10 秒）が使用されます。

Swift

1. getClient を呼び出すときのタイムアウトを設定します。

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

   アプリケーションの最小 OS バージョンが 13 未満の場合は、代わりに末尾クロージャを使用します。

     Recaptcha.getClient(
       withSiteKey: "KEY_ID",
       withTimeout: 15000
     ) { client, error in
       guard let client = client else {
           print("RecaptchaClient creation error: \(error).")
         return
       }
       self.recaptchaClient = client
     }
   

2. execute を呼び出すときのタイムアウトを設定します。

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

   アプリケーションの最小 OS バージョンが 13 未満の場合は、代わりに末尾クロージャを使用します。

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

Objective-C

1. getClient を呼び出すときのタイムアウトを設定します。

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

2. 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);
     }];
   

API リファレンス

iOS 用の reCAPTCHA API の詳細なリファレンスについては、RecaptchaEnterprise をご覧ください。

次のステップ

• reCAPTCHA の応答トークンを評価するため、評価を作成する。

  注: reCAPTCHA レスポンス トークンは、モバイル デバイスからではなく、バックエンド サーバーから評価され、アノテーションが付けられます。