Integrar o reCAPTCHA aos apps iOS

Esta página explica como integrar o reCAPTCHA ao seu app iOS.

Devido à variação nos dispositivos móveis em termos de tamanho de tela, desempenho e interfaces dos apps, o desafio reCAPTCHA da caixa de seleção visual (Não sou um robô) não está disponível para apps iOS. Em vez disso, implemente sua própria estratégia de aplicação em níveis, como um fluxo de MFA, para fornecer um caminho de resgate alternativo para tráfego suspeito.

Observação :o SDK usa reflexão e código dinâmico para permitir a atualização e o refinamento do sistema de detecção em aplicativos ou SDKs já implantados. Para evitar interferências no aplicativo, o conjunto de classes disponíveis no sistema fica restrito a uma lista cuidadosamente controlada.

Antes de começar

1. Defina o SDK mínimo do app como iOS 11 ou crie um novo app para dispositivos móveis.

2. Prepare seu ambiente para o reCAPTCHA.

3. Crie uma chave reCAPTCHA para a plataforma de apps iOS.

   Como alternativa, é possível copiar o ID de uma chave reCAPTCHA existente para iOS executando uma das seguintes etapas:

   • Para copiar o ID de uma chave atual do console do Google Cloud, faça o seguinte:

     1. Acesse a página do reCAPTCHA.

        Acessar o reCAPTCHA

     2. Na lista de chaves reCAPTCHA, mantenha o ponteiro sobre a chave que você quer copiar e clique em .
   • Para copiar o ID de uma chave atual com a API REST, use o método projects.keys.list.
   • Para copiar o ID de uma chave atual usando a gcloud CLI, use o comando gcloud recaptcha keys list.

4. Ter uma conta do GitHub.

5. Leia os detalhes de privacidade da Apple.

Preparar o ambiente do iOS

Para preparar o ambiente de desenvolvimento, faça o seguinte:

1. Faça o download e instale a versão mais recente do Xcode e crie um novo app de visualização única para iOS em branco.

2. Faça o download do SDK usando uma das seguintes opções:

   CocoaPods

   1. Faça o download e instale o CocoaPods.

   2. Crie um Podfile e adicione as seguintes linhas:

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

   3. Instale as dependências necessárias executando pod update.

      Observação: a execução de pod clone não instala as dependências necessárias.

   Gerenciador de pacotes do Swift

   1. No XCode, selecione File > Add Packages e insira o seguinte URL no campo Search ou Enter Package URL: https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk

   2. Na caixa de diálogo do XCode, insira os seguintes detalhes:

      • Nome de usuário do GitHub.
      • Um token de acesso pessoal que você criou usando as instruções do GitHub (em inglês). O token de acesso pessoal precisa ter os escopos listados na caixa de diálogo XCode Sign In.

      O Xcode instala o SDK e as dependências necessárias.

   Flutter

   Para instruções detalhadas sobre como usar o reCAPTCHA no Flutter, consulte a documentação do Flutter (link em inglês).

   ReactNative

   Para instruções detalhadas sobre como usar o reCAPTCHA com o React Native, consulte a documentação do React Native.

   Download direto

   1. Se quiser fazer o download do SDK e das dependências dele como xcframeworks, faça o download do cliente.

      Observação: adicione todos os binários como xcframeworks estáticos.

Configure o app

Você pode escrever seus aplicativos em Swift ou Objective-C.

Para configurar o app, adicione os seguintes arquivos a ele:

Swift

1. Se seu aplicativo for escrito em Swift, inclua a seguinte importação:

   #import RecaptchaEnterprise
   

Objective-C

1. Se o app for escrito em Objective-C, crie um arquivo Swift fictício e inclua a importação a seguir para garantir que o Xcode possa encontrar e vincular as bibliotecas do Swift.

   import Foundation
   

2. Para garantir que o código Swift esteja vinculado corretamente, acesse Destino > Configurações do build > Sempre incorporar bibliotecas padrão do Swift e verifique se a opção está definida como Yes.

Integrar o reCAPTCHA ao seu app iOS

Para integrar o reCAPTCHA ao seu app iOS, siga estas etapas no Xcode:

Observação: a latência do SDK reCAPTCHA pode ser alta, por isso é recomendado chamar Recaptcha.getClient(siteKey:) e execute() o quanto antes, por exemplo, quando o app é carregado. Não faça com que elementos da UI sejam bloqueados no SDK reCAPTCHA.

1. Para instanciar o SDK com a chave reCAPTCHA (KEY_ID) que você criou, atualize o app com o seguinte código:

   Swift com storyboard

   1. Atualize o 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)).")
            }
          }
        }
      }
      

      Se a versão mínima do SO do aplicativo for anterior à 13, use um encerramento final:

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

   1. Crie uma classe 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)).")
            }
          }
        }
      }
      

      Se a versão mínima do SO do aplicativo for anterior à 13, use um encerramento final:

      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. Instancie ViewModel em 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. Atualize o ViewController.h.

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

   2. Atualize o 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. Crie um botão para chamar o reCAPTCHA e acionar execute().

   Swift com storyboard

   1. No storyboard, crie um botão.
   2. Crie uma ação em ViewController vinculada ao botão que você criou.

   3. Chame o método execute() transmitindo uma ação Login para retornar um token de reCAPTCHA usando o snippet de código abaixo:

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

      Se a versão mínima do SO do aplicativo for anterior à 13, use um encerramento final:

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

   1. Atualize o ViewModel.swift com o código de execução:

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

      Se a versão mínima do SO do aplicativo for anterior à 13, use um encerramento final:

      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. Atualize o 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. No storyboard, crie um botão.
   2. Crie uma ação em ViewController vinculada ao botão que você criou.

   3. Chame o método execute() transmitindo uma ação Login para retornar um token de reCAPTCHA usando o snippet de código abaixo:

      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. Teste o aplicativo:

   1. O reCAPTCHA usa o AppAttest da Apple como parte do mecanismo de detecção. Se você não planeja usar uma chave de teste com uma pontuação fixa para desenvolvimento local, faça o seguinte:

      1. No Xcode, adicione o recurso App Attest ao app.

      2. No arquivo .entitlements do projeto, defina o ambiente do App Attest como production.

   2. Para limpar seu ambiente de build do Xcode, no menu Produto, clique em Limpar pasta de build.

   3. Para executar o aplicativo, clique em Executar no menu Produto.

   4. No aplicativo carregado, clique no botão criado anteriormente.

   5. A janela de saída de depuração deve retornar um token de reCAPTCHA (string alfanumérica) se a integração for bem-sucedida.

Definir um tempo limite para chamadas de API

É possível especificar um valor de tempo limite para as APIs getClient e execute usando a propriedade withTimeout de cada API.

Observação: um tempo limite padrão de 10 segundos é usado nas APIs getClient e execute para fins de consistência.

Swift

1. Defina o tempo limite ao chamar 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)).")
         }
       }
   

   Se a versão mínima do SO do seu aplicativo for anterior à 13, use um fechamento final:

     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. Defina o tempo limite ao chamar execute.

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

   Se a versão mínima do SO do seu aplicativo for anterior à 13, use um fechamento final:

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

Objective-C

1. Defina o tempo limite ao chamar 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. Defina o tempo limite ao chamar 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);
     }];
   

Referência da API

Para uma referência completa da API reCAPTCHA para iOS, consulte RecaptchaEnterprise.

A seguir

• Para avaliar o token de resposta reCAPTCHA, crie uma avaliação.

  Observação :os tokens de resposta do reCAPTCHA são avaliados e anotados pelo servidor de back-end, não pelo dispositivo móvel.