Esta página foi traduzida pela API Cloud Translation.

Integrar o reCAPTCHA a 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 da tela, desempenho e IUs dos apps, o teste visual do reCAPTCHA (Não sou um robô) não está disponível para apps para dispositivos móveis iOS. Em vez disso, implemente sua própria estratégia de aplicação em camadas, como um fluxo de MFA para fornecer um caminho alternativo de resgate para tráfego suspeito.

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 é restrito a uma lista cuidadosamente controlada.

Antes de começar

Defina o SDK mínimo do app como iOS 12 ou crie um novo app para dispositivos móveis.
Prepare seu ambiente para o reCAPTCHA.
Crie uma chave de reCAPTCHA para a plataforma de app iOS.

Como alternativa, é possível copiar o ID de uma chave reCAPTCHA para iOS executando uma das seguintes etapas:
- Para copiar o ID de uma chave existente no 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 do mouse sobre a chave que você quer copiar e clique em .
- Para copiar o ID de uma chave usando a API REST, use o método projects.keys.list.
- Para copiar o ID de uma chave usando a CLI gcloud, use o comando gcloud recaptcha keys list.
Ter uma conta do GitHub.
Leia os detalhes de privacidade da Apple.

Preparar o ambiente do iOS

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

Faça o download e instale a versão mais recente do Xcode e crie um novo aplicativo de visualização única para iOS em branco.
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.6.0" ... 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 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. 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.

ReactNative
Para instruções detalhadas sobre como usar o reCAPTCHA no React Native, consulte a documentação do React Native.
Download direto
1. Se você 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 programar seus apps em Swift ou Objective-C.

Para configurar o app, adicione os seguintes arquivos:

Swift

Se o app estiver escrito em Swift, inclua a seguinte importação:
```
 import RecaptchaEnterprise
```

Objective-C

Se o app estiver escrito em Objective-C, crie um arquivo Swift fictício e inclua a importação abaixo para garantir que o Xcode possa encontrar e vincular as bibliotecas Swift.
```
import Foundation
```
Para garantir que o código Swift seja vinculado corretamente, acesse Target > Build Settings > Always Embed Swift Standard Libraries 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:

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

Swift com storyboard

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

Se a versão mínima do SO do seu aplicativo for inferior a 13, use uma fechadura final:

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

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

Se a versão mínima do SO do seu aplicativo for inferior a 13, use uma fechadura final:

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

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

Atualize ViewController.h.

#import <RecaptchaEnterprise/RecaptchaEnterprise.h>

@interface ViewController : UIViewController
@property (strong, atomic) RecaptchaClient *recaptchaClient;
@end

Atualize 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

A inicialização do SDK pode levar vários segundos para ser concluída. Para reduzir essa latência, inicialize o cliente o mais cedo possível, por exemplo, durante a chamada onCreate() de uma classe Application personalizada. Não bloqueie elementos da interface no SDK do reCAPTCHA.

Crie um botão para chamar o reCAPTCHA e acionar execute().

Swift com storyboard

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

Chame o método execute() transmitindo uma ação Login para retornar um token 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 seu aplicativo for inferior a 13, use uma fechadura 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

Atualize 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 seu aplicativo for inferior a 13, use uma fechadura 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)
  }
}

Atualize 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

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

Chame o método execute() transmitindo uma ação Login para retornar um 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);
}];

A API execute do cliente pode levar vários segundos para ser concluída, como em condições de rede lenta ou se estiver aguardando a inicialização em segundo plano ser concluída. Verifique se as chamadas execute() não bloqueiam um evento da UI, como pressionar um botão.

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 o ambiente de build do Xcode, no menu Produto, clique em Limpar pasta de build.
3. Para executar o aplicativo, no menu Produto, clique em Executar.
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.

Migrar da API de método para o método fetchClient

O método fetchClient retorna um RecaptchaClient que tenta a inicialização novamente em falhas de rede. Se o app não tiver acesso à rede quando o cliente for criado, o cliente vai continuar tentando e será inicializado quando uma rede for adquirida.

Se você chamar execute(timeout) e o cliente ainda não estiver pronto, ele tentará ser inicializado antes de retornar um token ou um RecaptchaErrorCode.

O exemplo a seguir mostra como migrar de getClient para fetchClient.

Swift com 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)).")
    }
  }
}

Se a versão mínima do SO do seu aplicativo for inferior a 13, use uma fechadura final:

// 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 com 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)).")
    }
  }
}

Se a versão mínima do SO do seu aplicativo for inferior a 13, use uma fechadura final:

// 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

Definir um tempo limite para chamadas de API

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

Swift

Define 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 inferior a 13, use uma fechamento pendente:

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

Objective-C

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

Tratar erros

Se o app não conseguir se comunicar com o serviço reCAPTCHA, talvez seja porque a API encontrou um erro. É necessário adicionar lógica ao app para processar esses erros.

Para mais detalhes sobre mitigações de erros comuns de API, consulte RecaptchaErrorCode.

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 reCAPTCHA são avaliados e anotados no seu servidor de back-end, não no dispositivo móvel.

Integrar o reCAPTCHA a apps iOS

Antes de começar

Preparar o ambiente do iOS

CocoaPods

Gerenciador de pacotes do Swift

Flutter

ReactNative

Download direto

Configure o app

Swift

Objective-C

Integrar o reCAPTCHA ao seu app iOS

Swift com storyboard

Swift com SwiftUI

Objective-C

Swift com storyboard

Swift com SwiftUI

Objective-C

Migrar da API de método para o método fetchClient

Swift com storyboard

Swift com SwiftUI

Objective-C

Definir um tempo limite para chamadas de API

Swift

Objective-C

Tratar erros

Referência da API

A seguir