**Apresentando uma nova experiência de console para AWS WAF**

Agora você pode usar a experiência atualizada para acessar a AWS WAF funcionalidade em qualquer lugar do console. Para obter mais detalhes, consulte [Trabalhando com o console](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). 

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Integrações de aplicativos clientes em AWS WAF
<a name="waf-application-integration"></a>

Esta seção explica como usar a integração inteligente de ameaças APIs e a API de integração JavaScript CAPTCHA com seus AWS WAF recursos. 

Use APIs a integração AWS WAF do aplicativo cliente para unir as proteções do lado do cliente às proteções do pacote AWS de proteção do lado do servidor (Web ACL), para ajudar a verificar se os aplicativos cliente que enviam solicitações da Web aos recursos protegidos são os clientes pretendidos e se os usuários finais são seres humanos. 

Use as integrações do cliente para gerenciar desafios silenciosos do navegador e quebra-cabeças CAPTCHA, obter tokens com provas de respostas bem-sucedidas do navegador e do usuário final e incluir esses tokens nas solicitações aos seus endpoints protegidos. Para obter informações gerais sobre AWS WAF tokens, consulte[Uso de tokens na mitigação AWS WAF inteligente de ameaças](waf-tokens.md). 

Combine suas integrações de clientes com as proteções do pacote de proteção (ACL da Web) que exigem tokens válidos para acesso aos seus recursos. Você pode usar grupos de regras que verificam e monitoram os tokens de desafio, como os listados na próxima seção, em [Integração inteligente de ameaças e regras AWS gerenciadas](waf-application-integration-with-AMRs.md), e você pode usar as ações de regras CAPTCHA e Challenge para verificar, conforme descrito em [CAPTCHAe Challenge em AWS WAF](waf-captcha-and-challenge.md). 

AWS WAF fornece dois níveis de integração para JavaScript aplicativos e um para aplicativos móveis: 
+ **Integração inteligente de ameaças** — verifique o aplicativo do cliente e forneça aquisição e gerenciamento de AWS tokens. Isso é semelhante à funcionalidade fornecida pela ação da AWS WAF Challenge regra. Essa funcionalidade integra totalmente seu aplicativo cliente ao grupo de regras gerenciadas `AWSManagedRulesACFPRuleSet`, ao grupo de regras gerenciadas `AWSManagedRulesATPRuleSet` e ao nível de proteção direcionada do grupo de regras gerenciadas `AWSManagedRulesBotControlRuleSet`. 

  A integração inteligente de ameaças APIs usa o desafio do navegador AWS WAF silencioso para ajudar a garantir que as tentativas de login e outras chamadas para seu recurso protegido sejam permitidas somente após o cliente adquirir um token válido. APIs Gerencie a autorização do token para as sessões do aplicativo cliente e reúna informações sobre o cliente para ajudar a determinar se ele está sendo operado por um bot ou por um ser humano. 
**nota**  
Isso está disponível para JavaScript e para aplicativos móveis Android e iOS. 
+ **Integração com CAPTCHA**: verifique os usuários finais com o quebra-cabeça CAPTCHA personalizado que você gerencia em seu aplicativo. Isso é semelhante à funcionalidade fornecida pela ação da AWS WAF CAPTCHA regra, mas com controle adicional sobre o posicionamento e o comportamento do quebra-cabeça. 

  Essa integração aproveita a integração JavaScript inteligente de ameaças para executar desafios silenciosos e fornecer AWS WAF tokens para a página do cliente. 
**nota**  
Isso está disponível para JavaScript aplicativos. 

**Topics**
+ [Integração inteligente de ameaças e regras AWS gerenciadas](waf-application-integration-with-AMRs.md)
+ [Acessando a integração AWS WAF do aplicativo cliente APIs](waf-application-integration-location-in-console.md)
+ [AWS WAF JavaScript integrações](waf-javascript-api.md)
+ [AWS WAF integração de aplicativos móveis](waf-mobile-sdk.md)

# Integração inteligente de ameaças e regras AWS gerenciadas
<a name="waf-application-integration-with-AMRs"></a>

Esta seção explica como a integração inteligente de ameaças APIs funciona com os grupos de regras de regras AWS gerenciadas.

A integração inteligente de ameaças APIs funciona com pacotes de proteção (web ACLs) que usam os grupos inteligentes de regras de ameaças para permitir a funcionalidade completa desses grupos avançados de regras gerenciadas. 
+ AWS WAF Grupo de regras gerenciadas para prevenção de fraudes (ACFP) para criação de contas de controle de fraudes. `AWSManagedRulesACFPRuleSet` 

  A fraude na criação de conta é uma atividade online ilegal na qual um invasor cria contas inválidas em seu aplicativo para fins como receber bônus de inscrição ou se passar por alguém. O grupo de regras gerenciadas do ACFP fornece regras para bloquear, rotular e gerenciar solicitações que podem fazer parte de tentativas fraudulentas de criação de conta. Eles APIs permitem a verificação refinada do navegador do cliente e as informações de interatividade humana que as regras do ACFP usam para separar o tráfego válido do cliente do tráfego malicioso.

  Para obter mais informações, consulte [AWS WAF Grupo de regras de prevenção de fraudes (ACFP) para criação de contas de controle de fraudes](aws-managed-rule-groups-acfp.md) e [AWS WAF Controle de fraudes na criação de contas e prevenção de fraudes (ACFP)](waf-acfp.md).
+ AWS WAF Grupo de regras gerenciadas para prevenção de aquisição de contas (ATP) para controle de fraudes. `AWSManagedRulesATPRuleSet` 

  A apropriação de conta é uma atividade ilegal online na qual um invasor obtém acesso não autorizado à conta de uma pessoa. O grupo de regras gerenciadas do ATP fornece regras para bloquear, rotular e gerenciar solicitações que podem fazer parte de tentativas maliciosas de apropriação de contas. Eles APIs permitem a verificação refinada do cliente e a agregação de comportamento que as regras do ATP usam para separar o tráfego válido do cliente do tráfego malicioso.

  Para obter mais informações, consulte [AWS WAF Grupo de regras de prevenção de aquisição de contas (ATP) de controle de fraudes](aws-managed-rule-groups-atp.md) e [AWS WAF Controle de fraudes e prevenção de aquisição de contas (ATP)](waf-atp.md).
+ Nível de proteção direcionado do grupo de regras gerenciadas do AWS WAF Bot Control`AWSManagedRulesBotControlRuleSet`. 

  Os bots vão desde os que se identificam automaticamente e são úteis, como a maioria dos mecanismos de pesquisa e crawlers, até bots maliciosos que operam contra seu site e não se identificam. O grupo de regras gerenciadas do Controle de Bots fornece regras para monitorar, rotular e gerenciar a atividade de bots em seu tráfego da web. Quando você usa o nível de proteção direcionado desse grupo de regras, as regras direcionadas usam as informações da sessão do cliente que APIs fornecem para detectar melhor os bots mal-intencionados. 

  Para obter mais informações, consulte [AWS WAF Grupo de regras do Bot Control](aws-managed-rule-groups-bot.md) e [AWS WAF Controle de bots](waf-bot-control.md).

Para adicionar um desses grupos de regras gerenciadas ao pacote de proteção (ACL da Web), consulte os procedimentos [Adicionando o grupo de regras gerenciadas do ACFP à sua web ACL](waf-acfp-rg-using.md), [Adicionar grupos de regras gerenciadas ao pacote de proteção (ACL da Web)](waf-atp-rg-using.md) e [Adicionar o grupo de regras gerenciadas do AWS WAF Bot Control à sua ACL da web](waf-bot-control-rg-using.md).

**nota**  
Atualmente, os grupos de regras gerenciadas não bloqueiam solicitações sem tokens. Para bloquear solicitações sem tokens, depois de implementar a integração do aplicativo APIs, siga as orientações em[Bloqueio de solicitações que não têm um AWS WAF token válido](waf-tokens-block-missing-tokens.md). 

# Acessando a integração AWS WAF do aplicativo cliente APIs
<a name="waf-application-integration-location-in-console"></a>

Esta seção explica onde encontrar a integração de aplicativos APIs no AWS WAF console.

As JavaScript integrações APIs estão geralmente disponíveis e você pode usá-las em seus navegadores e outros dispositivos que são executados JavaScript. 

AWS WAF oferece integração inteligente personalizada de ameaças SDKs para aplicativos móveis Android e iOS. 
+ Para aplicativos Android para celular e TV, o SDKs Work for Android API versão 23 (Android versão 6) e versões posteriores. Para obter informações sobre as versões do Android, consulte as [Notas de lançamento da plataforma de SDK](https://developer.android.com/tools/releases/platforms).
+ Para aplicativos móveis iOS, eles SDKs funcionam para iOS versão 13 e posterior. Para obter informações sobre as versões do iOS, consulte as [Notas de versão do iOS e iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Para aplicativos da Apple TV, eles SDKs funcionam para tvOS versão 14 ou posterior. Para obter informações sobre as versões do tvOS, consulte [tvOS Release Notes](https://developer.apple.com/documentation/tvos-release-notes).

**Para acessar a integração APIs por meio do console**

1. Faça login no Console de gerenciamento da AWS e abra o AWS WAF console em [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Escolha **Integração de aplicativos** no painel de navegação e, em seguida, escolha a guia na qual você está interessado.
   + A **integração inteligente de ameaças** está disponível para JavaScript aplicativos móveis. 

     A guia contém o seguinte:
     + Uma lista dos pacotes de proteção (web ACLs) que estão habilitados para a integração inteligente de aplicativos contra ameaças. A lista inclui todo pacote de proteção (ACL da Web) que usa o grupo de regras gerenciadas `AWSManagedRulesACFPRuleSet`, o grupo de regras gerenciadas `AWSManagedRulesATPRuleSet` ou o nível de proteção visado do grupo de regras gerenciadas `AWSManagedRulesBotControlRuleSet`. Ao implementar a ameaça inteligente APIs, você usa a URL de integração do pacote de proteção (Web ACL) com o qual deseja se integrar.
     +  APIs Aquele ao qual você tem acesso. Eles JavaScript APIs estão sempre disponíveis. Para acessar o celular SDKs, entre em contato com o suporte em [Contato AWS](https://aws.amazon.com/contact-us).
   + A **integração CAPTCHA** está disponível para JavaScript aplicativos. 

     A guia contém o seguinte: 
     + O URL de integração para uso em sua integração. 
     + As chaves de API que você criou para os domínios do seu aplicativo cliente. Seu uso da API CAPTCHA requer uma chave de API criptografada que dê aos clientes o direito de acessar o AWS WAF CAPTCHA a partir de seus domínios. Para cada cliente com o qual você se integra, use uma chave de API que contenha o domínio do cliente. Para saber mais sobre esses requisitos e sobre o gerenciamento dessas chaves, consulte [Como gerenciar chaves de API para a API JS CAPTCHA](waf-js-captcha-api-key.md).

# AWS WAF JavaScript integrações
<a name="waf-javascript-api"></a>

Esta seção explica como usar as AWS WAF JavaScript integrações.

Você pode usar a JavaScript integração APIs para implementar integrações de AWS WAF aplicativos em seus navegadores e outros dispositivos que são JavaScript executados. 

Os códigos CAPTCHA e os desafios silenciosos só podem ser executados quando os navegadores estão acessando endpoints HTTPS. Os clientes do navegador devem estar sendo executados em contextos seguros para adquirir tokens. 
+ A ameaça inteligente APIs permite que você gerencie a autorização de tokens por meio de um desafio silencioso do navegador do lado do cliente e inclua os tokens nas solicitações que você envia aos seus recursos protegidos. 
+ A API de integração do CAPTCHA aumenta a ameaça APIs inteligente e permite que você personalize o posicionamento e as características do quebra-cabeça do CAPTCHA em seus aplicativos clientes. Essa API aproveita a ameaça inteligente APIs para adquirir AWS WAF tokens para uso na página após o usuário final concluir com êxito o quebra-cabeça do CAPTCHA. 

Ao usar essas integrações, você garante que as chamadas de procedimento remoto feitas pelo seu cliente contenham um token válido. Quando essas integrações APIs estão implementadas nas páginas do seu aplicativo, você pode implementar regras atenuantes em seu pacote de proteção (web ACL), como bloquear solicitações que não contêm um token válido. Você também pode implementar regras que imponham o uso dos tokens que seus aplicativos clientes obtêm, usando as ações Challenge ou CAPTCHA em suas regras. 

**Exemplo de implementação de ameaça inteligente APIs**  
A lista a seguir mostra os componentes básicos de uma implementação típica da ameaça inteligente APIs em uma página de aplicativo web. 

```
<head>
<script type="text/javascript" src="protection pack (web ACL) integration URL/challenge.js" defer></script>
</head>
<script>
const login_response = await AwsWafIntegration.fetch(login_url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: login_body
  });
</script>
```

**Exemplo de implementação da API CAPTCHA JavaScript**  
A API de integração CAPTCHA permite que você personalize a experiência de quebra-cabeça CAPTCHA de seus usuários finais. A integração CAPTCHA aproveita a integração JavaScript inteligente de ameaças, para verificação do navegador e gerenciamento de tokens, além de adicionar uma função para configurar e renderizar o quebra-cabeça do CAPTCHA. 

A lista a seguir mostra os componentes básicos de uma implementação típica da JavaScript API CAPTCHA em uma página de aplicativo web. 

```
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>

<script type="text/javascript">
    function showMyCaptcha() {
        var container = document.querySelector("#my-captcha-container");
        
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            ...other configuration parameters as needed...
        });
    }
    
    function captchaExampleSuccessFunction(wafToken) {
        // Use WAF token to access protected resources
        AwsWafIntegration.fetch("...WAF-protected URL...", {
            method: "POST",
            ...
        });
    }
    
    function captchaExampleErrorFunction(error) {
        /* Do something with the error */
    }
</script>

<div id="my-captcha-container">
    <!-- The contents of this container will be replaced by the captcha widget -->
</div>
```

**Topics**
+ [Fornecimento de domínios para uso nos tokens](waf-js-challenge-api-set-token-domain.md)
+ [Usando a JavaScript API com políticas de segurança de conteúdo](waf-javascript-api-csp.md)
+ [Usando a JavaScript API de ameaças inteligentes](waf-js-challenge-api.md)
+ [Usando a API CAPTCHA JavaScript](waf-js-captcha-api.md)

# Fornecimento de domínios para uso nos tokens
<a name="waf-js-challenge-api-set-token-domain"></a>

Esta seção explica como fornecer domínios adicionais para tokens.

Por padrão, ao AWS WAF criar um token, ele usa o domínio host do recurso associado ao pacote de proteção (Web ACL). Você pode fornecer domínios adicionais para os tokens AWS WAF criados para o. JavaScript APIs Para fazer isso, configure a variável global `window.awsWafCookieDomainList`, com um ou mais domínios de token. 

Ao AWS WAF criar um token, ele usa o domínio mais adequado e mais curto dentre a combinação dos domínios `window.awsWafCookieDomainList` e do domínio do host do recurso associado ao pacote de proteção (Web ACL). 

Exemplo de configurações: 

```
window.awsWafCookieDomainList = ['.aws.amazon.com']
```

```
window.awsWafCookieDomainList = ['.aws.amazon.com', 'abc.aws.amazon.com']
```

Você não pode usar sufixos públicos nessa lista. Por exemplo, você não pode usar `gov.au` ou `co.uk` como domínios de token na lista.

Os domínios que você especifica nessa lista devem ser compatíveis com seus outros domínios e configurações de domínio: 
+ Os domínios devem ser aqueles que AWS WAF aceitarão, com base no domínio do host protegido e na lista de domínios do token configurada para o pacote de proteção (Web ACL). Para obter mais informações, consulte [AWS WAF configuração da lista de domínios de token do pacote de proteção (web ACL)](waf-tokens-domains.md#waf-tokens-domain-lists). 
+ Se você usa a API JavaScript CAPTCHA, pelo menos um domínio em sua chave de API CAPTCHA deve corresponder exatamente a um dos domínios de token `window.awsWafCookieDomainList` ou deve ser o domínio ápice de um desses domínios de token. 

  Por exemplo, para o domínio do token `mySubdomain.myApex.com`, a chave de API `mySubdomain.myApex.com` é uma correspondência exata e a chave de API `myApex.com` é o domínio apex. Qualquer chave corresponde ao domínio do token. 

  Para saber mais sobre as chaves de API, consulte [Como gerenciar chaves de API para a API JS CAPTCHA](waf-js-captcha-api-key.md). 

Se você usar o grupo de regras gerenciadas `AWSManagedRulesACFPRuleSet`, poderá configurar um domínio que corresponda ao do caminho de criação da conta que você forneceu para a configuração do grupo de regras. Para saber mais sobre essa configuração, consulte [Adicionando o grupo de regras gerenciadas do ACFP à sua web ACL](waf-acfp-rg-using.md).

Se você usar o grupo de regras gerenciadas `AWSManagedRulesATPRuleSet`, poderá configurar um domínio que corresponda ao do caminho de login que você forneceu para a configuração do grupo de regras. Para saber mais sobre essa configuração, consulte [Adicionar grupos de regras gerenciadas ao pacote de proteção (ACL da Web)](waf-atp-rg-using.md).

# Usando a JavaScript API com políticas de segurança de conteúdo
<a name="waf-javascript-api-csp"></a>

Esta seção fornece um exemplo de configuração para permitir o domínio AWS WAF apex na lista de permissões.

Se você aplicar políticas de segurança de conteúdo (CSP) aos seus recursos, para que sua JavaScript implementação funcione, você precisa colocar o domínio AWS WAF apex na lista de permissões. `awswaf.com` Eles JavaScript SDKs fazem chamadas para AWS WAF endpoints diferentes, portanto, a lista de permissões desse domínio fornece as permissões SDKs necessárias para operar.

Veja a seguir um exemplo de configuração para permitir o domínio AWS WAF apex na lista de permissões: 

```
connect-src 'self' https://*.awswaf.com;
script-src 'self' https://*.awswaf.com;
script-src-elem 'self' https://*.awswaf.com;
```

Se você tentar usar o JavaScript SDKs com recursos que usam CSP e não tiver permitido o AWS WAF domínio, você receberá erros como os seguintes: 

```
Refused to load the script ...awswaf.com/<> because it violates the following Content Security Policy directive: “script-src ‘self’
```

# Usando a JavaScript API de ameaças inteligentes
<a name="waf-js-challenge-api"></a>

Esta seção fornece instruções para usar a JavaScript API de ameaças inteligentes em seu aplicativo cliente.

A ameaça inteligente APIs fornece operações para executar desafios silenciosos no navegador do usuário e para lidar com os AWS WAF tokens que comprovam o sucesso do desafio e das respostas CAPTCHA. 

Implemente a JavaScript integração primeiro em um ambiente de teste e depois na produção. Para obter orientações adicionais sobre codificação, consulte as seções a seguir. 

 

**Para usar a ameaça inteligente APIs**

1. **Instale o APIs** 

   Se você usar a API CAPTCHA, você poderá ignorar esta etapa. Quando você instala a API CAPTCHA, o script instala automaticamente a ameaça inteligente. APIs

   1. Faça login no Console de gerenciamento da AWS e abra o AWS WAF console em [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. No painel de navegação, escolha **Integração de aplicativos**. Na página **Integração de aplicativos**, você pode ver as opções com guias. 

   1. Selecione **Integração de ameaças inteligentes**

   1. Na guia, selecione o pacote de proteção (ACL da Web) com o qual você deseja fazer a integração. A lista de pacotes de proteção (web ACL) inclui somente pacotes de proteção (web ACLs) que usam o grupo de regras `AWSManagedRulesACFPRuleSet` gerenciadas, o grupo de regras `AWSManagedRulesATPRuleSet` gerenciadas ou o nível de proteção desejado do grupo de regras `AWSManagedRulesBotControlRuleSet` gerenciadas. 

   1. Abra o painel **JavaScript SDK** e copie a tag do script para usar em sua integração. 

   1. No código da página da aplicação, na seção `<head>`, insira a tag de script que você copiou para o pacote de proteção (ACL da Web). Essa inclusão faz com que seu aplicativo cliente recupere automaticamente um token em segundo plano no carregamento da página. 

      ```
      <head>
          <script type="text/javascript" src="protection pack (web ACL) integration URL/challenge.js” defer></script>
      <head>
      ```

      Essa lista `<script>` é configurada com o recurso `defer`, mas você pode alterar a configuração para `async` se quiser um comportamento diferente para sua página. 

1. **(Opcional) Adicionar configuração de domínio para os tokens do cliente** — Por padrão, ao AWS WAF criar um token, ele usa o domínio host do recurso associado ao pacote de proteção (Web ACL). Para fornecer domínios adicionais para o JavaScript APIs, siga as orientações em[Fornecimento de domínios para uso nos tokens](waf-js-challenge-api-set-token-domain.md). 

1. **Codificar sua integração de ameaças inteligentes**: escreva seu código para garantir que a recuperação do token seja concluída antes que o cliente envie suas solicitações para os endpoints protegidos. Se você já estiver usando a API `fetch` para fazer sua chamada, poderá substituir o wrapper de integração `fetch` do AWS WAF . Se você não usa a `fetch` API, pode usar a `getToken` operação de AWS WAF integração em vez disso. Para ver orientações de codificação, consulte as seções a seguir. 

1. **Adicionar verificação de token no pacote de proteção (ACL da Web)**: adicione pelo menos uma regra ao pacote de proteção (ACL da Web) que verifique se há um token de desafio válido nas solicitações da Web enviadas pelo seu cliente. Você pode usar grupos de regras que verificam e monitoram tokens de desafio, como o nível direcionado do grupo de regras gerenciadas do Controle de Bots, e você pode usar a ação de regra Challenge para verificar, conforme descrito em [CAPTCHAe Challenge em AWS WAF](waf-captcha-and-challenge.md). 

   As adições do pacote de proteção (ACL da Web) verificam se as solicitações aos endpoints protegidos incluem o token que você adquiriu na integração com o cliente. Solicitações que incluem um token válido e não expirado passam pela inspeção Challenge e não enviam outro desafio silencioso ao seu cliente. 

1. **(Opcional) Bloqueie solicitações sem tokens** — Se você usar o APIs com o grupo de regras gerenciadas do ACFP, o grupo de regras gerenciadas pelo ATP ou as regras específicas do grupo de regras do Bot Control, essas regras não bloquearão solicitações sem tokens. Para bloquear solicitações sem tokens, siga as orientações em [Bloqueio de solicitações que não têm um AWS WAF token válido](waf-tokens-block-missing-tokens.md). 

**Topics**
+ [Especificação da API de ameaças inteligentes](waf-js-challenge-api-specification.md)
+ [Como usar o wrapper de integração `fetch`](waf-js-challenge-api-fetch-wrapper.md)
+ [Como usar a integração `getToken`](waf-js-challenge-api-get-token.md)

# Especificação da API de ameaças inteligentes
<a name="waf-js-challenge-api-specification"></a>

Esta seção lista a especificação dos métodos e propriedades da mitigação JavaScript APIs inteligente de ameaças. Use-os APIs para integrações inteligentes de ameaças e CAPTCHA.

**`AwsWafIntegration.fetch()`**  
Envia a `fetch` solicitação HTTP para o servidor usando a implementação da AWS WAF integração. 

**`AwsWafIntegration.getToken()`**  
Recupera o AWS WAF token armazenado e o armazena em um cookie na página atual com o nome `aws-waf-token` e o valor definido como o valor do token. 

**`AwsWafIntegration.hasToken()`**  
Retorna um booleano indicando se o cookie `aws-waf-token` atualmente contém um token não expirado. 

Se você também estiver usando a integração CAPTCHA, consulte a especificação para isso em [Especificação da API CAPTCHA JavaScript](waf-js-captcha-api-specification.md).

# Como usar o wrapper de integração `fetch`
<a name="waf-js-challenge-api-fetch-wrapper"></a>

Esta seção fornece instruções para usar o wrapper de integração `fetch`.

Você pode usar o AWS WAF `fetch` wrapper alterando suas `fetch` chamadas normais para a `fetch` API no `AwsWafIntegration` namespace. O AWS WAF wrapper suporta todas as mesmas opções da chamada de JavaScript `fetch` API padrão e adiciona o tratamento de tokens para a integração. Essa abordagem geralmente é a maneira mais simples de integrar seu aplicativo. 

**Antes da implementação do wrapper**  
A lista de exemplo a seguir mostra o código padrão antes de implementar o wrapper `fetch` de `AwsWafIntegration`.

```
const login_response = await fetch(login_url, {
	    method: 'POST',
	    headers: {
	      'Content-Type': 'application/json'
	    },
	    body: login_body
	  });
```

**Após a implementação do wrapper**  
A lista a seguir mostra o mesmo código com a implementação do wrapper `fetch` de `AwsWafIntegration`.

```
const login_response = await AwsWafIntegration.fetch(login_url, {
	    method: 'POST',
	    headers: {
	      'Content-Type': 'application/json'
	    },
	    body: login_body
	  });
```

# Como usar a integração `getToken`
<a name="waf-js-challenge-api-get-token"></a>

Esta seção explica como usar a operação `getToken`.

AWS WAF exige que suas solicitações para endpoints protegidos incluam o cookie nomeado `aws-waf-token` com o valor do seu token atual. 

A operação `getToken` é uma chamada de API assíncrona que recupera o token do AWS WAF e o armazena em um cookie na página atual com o nome `aws-waf-token` e o valor definido como o valor do token. Você pode usar esse cookie de token conforme necessário em sua página. 

Quando você chama `getToken`, ele faz o seguinte: 
+ Se um token não expirado já estiver disponível, a chamada o retornará imediatamente.
+ Caso contrário, a chamada recuperará um novo token do provedor do token, aguardando até 2 segundos para que o fluxo de trabalho de aquisição do token seja concluído antes do tempo limite. Se a operação atingir o tempo limite, ela gerará um erro, que seu código de chamada deve processar. 

A operação `getToken` tem uma operação `hasToken` complementar, que indica se o cookie `aws-waf-token` atualmente contém um token não expirado. 

`AwsWafIntegration.getToken()` recupera um token válido e o armazena como um cookie. A maioria das chamadas de clientes anexa automaticamente esse cookie, mas algumas não. Por exemplo, chamadas feitas em domínios de host não anexam o cookie. Nos detalhes de implementação a seguir, mostramos como trabalhar com os dois tipos de chamadas de clientes. 

**Implementação básica de `getToken`, para chamadas que anexam o cookie `aws-waf-token`**  
A lista de exemplo a seguir mostra o código padrão para implementar a operação `getToken` com uma solicitação de login.

```
const login_response = await AwsWafIntegration.getToken()
	    .catch(e => {
	        // Implement error handling logic for your use case
	    })
	    // The getToken call returns the token, and doesn't typically require special handling
	    .then(token => {
	        return loginToMyPage()
	    })
	
	async function loginToMyPage() {
	    // Your existing login code
	}
```

**Envie o formulário somente após o token estar disponível em `getToken`**  
A lista a seguir mostra como registrar um receptor de eventos para interceptar envios de formulários até que um token válido esteja disponível para uso. 

```
<body>
	  <h1>Login</h1>
	  <p></p>
	  <form id="login-form" action="/web/login" method="POST" enctype="application/x-www-form-urlencoded">
	    <label for="input_username">USERNAME</label>
	    <input type="text" name="input_username" id="input_username"><br>
	    <label for="input_password">PASSWORD</label>
	    <input type="password" name="input_password" id="input_password"><br>
	    <button type="submit">Submit<button>
	  </form>
	
	<script>
	  const form = document.querySelector("#login-form");
	
	  // Register an event listener to intercept form submissions
	  form.addEventListener("submit", (e) => {
	      // Submit the form only after a token is available 
	      if (!AwsWafIntegration.hasToken()) {
	          e.preventDefault();
	          AwsWafIntegration.getToken().then(() => {
	              e.target.submit();
	          }, (reason) => { console.log("Error:"+reason) });
	        }
	    });
	</script>
	</body>
```

**Como anexar o token quando seu cliente não anexa o cookie `aws-waf-token` por padrão**  
`AwsWafIntegration.getToken()` recupera um token válido e o armazena como um cookie, mas nem todas as chamadas de clientes anexam esse cookie por padrão. Por exemplo, chamadas feitas em domínios de host não anexam o cookie. 

O `fetch` wrapper trata esses casos automaticamente, mas se você não conseguir usar o `fetch` wrapper, poderá lidar com isso usando um cabeçalho personalizado`x-aws-waf-token`. AWS WAF lê os tokens desse cabeçalho, além de lê-los do `aws-waf-token` cookie. O código a seguir mostra um exemplo de configuração do cabeçalho. 

```
const token = await AwsWafIntegration.getToken();
const result = await fetch('/url', {
    headers: {
        'x-aws-waf-token': token,
    },
});
```

Por padrão, AWS WAF só aceita tokens que contenham o mesmo domínio do domínio host solicitado. Todos os tokens entre domínios exigem entradas correspondentes no pacote de proteção (ACL da Web) da lista de domínios do token. Para obter mais informações, consulte [AWS WAF configuração da lista de domínios de token do pacote de proteção (web ACL)](waf-tokens-domains.md#waf-tokens-domain-lists). 

Para obter informações adicionais sobre o uso de tokens entre domínios, consulte [aws-waf-bot-controlaws-samples/](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha) -. api-protection-with-captcha

# Usando a API CAPTCHA JavaScript
<a name="waf-js-captcha-api"></a>

Esta seção fornece instruções para usar a API de integração CAPTCHA.

A JavaScript API CAPTCHA permite que você configure o quebra-cabeça CAPTCHA e o coloque onde quiser em seu aplicativo cliente. Essa API aproveita os recursos da ameaça inteligente JavaScript APIs para adquirir e usar AWS WAF tokens depois que um usuário final conclui com sucesso um quebra-cabeça de CAPTCHA. 

Implemente a JavaScript integração primeiro em um ambiente de teste e depois na produção. Para obter orientações adicionais sobre codificação, consulte as seções a seguir. 

**Para usar a API de integração CAPTCHA**

1. **Instale a API**

   1. Faça login no Console de gerenciamento da AWS e abra o AWS WAF console em [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. No painel de navegação, escolha **Integração de aplicativos**. Na página **Integração de aplicativos**, você pode ver as opções com guias. 

   1. Selecione **Integração CAPTCHA**.

   1. Copie a tag do script de JavaScript integração listada para uso em sua integração.

   1. No código da página do aplicativo, na seção `<head>`, insira a tag de script que você copiou. Essa inclusão torna o quebra-cabeça CAPTCHA disponível para configuração e uso. 

      ```
      <head>
          <script type="text/javascript" src="integrationURL/jsapi.js" defer></script>
      </head>
      ```

      Essa lista `<script>` é configurada com o recurso `defer`, mas você pode alterar a configuração para `async` se quiser um comportamento diferente para sua página. 

      O script do CAPTCHA também carrega automaticamente o script de integração de ameaças inteligentes, caso ele ainda não esteja presente. O script de integração de ameaças inteligentes faz com que seu aplicativo cliente recupere automaticamente um token em segundo plano no carregamento da página e fornece outras funcionalidades de gerenciamento de tokens necessárias para o uso da API CAPTCHA. 

1. **(Opcional) Adicionar configuração de domínio para os tokens do cliente** — Por padrão, ao AWS WAF criar um token, ele usa o domínio host do recurso associado ao pacote de proteção (Web ACL). Para fornecer domínios adicionais para o JavaScript APIs, siga as orientações em[Fornecimento de domínios para uso nos tokens](waf-js-challenge-api-set-token-domain.md). 

1. **Obtenha a chave de API criptografada para o cliente** — A API CAPTCHA requer uma chave de API criptografada que contenha uma lista de domínios de clientes válidos. AWS WAF usa essa chave para verificar se o domínio do cliente que você está usando com a integração foi aprovado para usar AWS WAF CAPTCHA. Para gerar sua chave de API, siga as orientações em [Como gerenciar chaves de API para a API JS CAPTCHA](waf-js-captcha-api-key.md).

1. **Codificar a implementação do widget CAPTCHA**: implemente a chamada de API `renderCaptcha()` em sua página, no local em que você deseja usá-la. Para obter informações sobre como configurar e usar essa função, consulte as seguintes seções, [Especificação da API CAPTCHA JavaScript](waf-js-captcha-api-specification.md) e [Como renderizar o quebra-cabeça CAPTCHA](waf-js-captcha-api-render.md). 

   A implementação do CAPTCHA se integra à integração inteligente de ameaças APIs para gerenciamento de tokens e para executar chamadas de busca que usam os tokens. AWS WAF Para obter orientação sobre como usá-los APIs, consulte[Usando a JavaScript API de ameaças inteligentes](waf-js-challenge-api.md).

1. **Adicionar verificação de token ao pacote de proteção (ACL da Web)**: adicione pelo menos uma regra ao pacote de proteção (ACL da Web) que verifique se há um token de CAPTCHA válido nas solicitações da Web enviadas pelo cliente. Você pode usar a ação de regra CAPTCHA para verificar, conforme descrito em [CAPTCHAe Challenge em AWS WAF](waf-captcha-and-challenge.md). 

   As adições ao pacote de proteção (ACL da Web) verificam se as solicitações dirigidas aos endpoints protegidos incluem o token que você adquiriu na integração de cliente. Solicitações que incluem um token de CAPTCHA válido e não expirado passam pela inspeção de ação de regra CAPTCHA e não apresentam ao usuário final outro quebra-cabeça CAPTCHA. 

Depois de implementar a JavaScript API, você pode revisar as CloudWatch métricas das tentativas e soluções de quebra-cabeças do CAPTCHA. Para obter detalhes sobre métricas e dimensões, consulte [Métricas e dimensões da conta](waf-metrics.md#waf-metrics-account).

**Topics**
+ [Especificação da API CAPTCHA JavaScript](waf-js-captcha-api-specification.md)
+ [Como renderizar o quebra-cabeça CAPTCHA](waf-js-captcha-api-render.md)
+ [Manipulando uma resposta CAPTCHA de AWS WAF](waf-js-captcha-api-conditional.md)
+ [Como gerenciar chaves de API para a API JS CAPTCHA](waf-js-captcha-api-key.md)

# Especificação da API CAPTCHA JavaScript
<a name="waf-js-captcha-api-specification"></a>

Esta seção lista a especificação dos métodos e propriedades do CAPTCHA JavaScript APIs. Use o CAPTCHA JavaScript APIs para executar quebra-cabeças CAPTCHA personalizados em seus aplicativos cliente. 

Essa API se baseia na ameaça inteligente APIs, que você usa para configurar e gerenciar a aquisição e o uso de AWS WAF tokens. Consulte [Especificação da API de ameaças inteligentes](waf-js-challenge-api-specification.md).

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
Apresenta um quebra-cabeça de AWS WAF CAPTCHA para o usuário final e, em caso de sucesso, atualiza o token do cliente com a validação do CAPTCHA. Ele está disponível apenas com a integração CAPTCHA. Use essa chamada junto com a ameaça inteligente APIs para gerenciar a recuperação do token e fornecer o token em suas `fetch` chamadas. Veja a ameaça inteligente APIs em[Especificação da API de ameaças inteligentes](waf-js-challenge-api-specification.md).  
Ao contrário do intersticial CAPTCHA que AWS WAF envia, o quebra-cabeça CAPTCHA renderizado por esse método exibe o quebra-cabeça imediatamente, sem uma tela de título inicial.     
**`container`**  
O objeto `Element` do elemento do contêiner de destino na página. Isso geralmente é recuperado chamando `document.getElementById()` ou `document.querySelector()`.  
Obrigatório: sim  
Tipo: `Element`  
**configuração**  
Um objeto contendo as configurações do CAPTCHA, da seguinte forma****:    
**`apiKey`**   
A chave de API criptografada que habilita permissões para o domínio do cliente. Use o console do AWS WAF para gerar suas chaves de API para seus domínios de clientes. Você pode usar uma chave para até cinco domínios. Para mais informações, consulte [Como gerenciar chaves de API para a API JS CAPTCHA](waf-js-captcha-api-key.md).   
Obrigatório: Sim  
Tipo: `string`  
**`onSuccess: (wafToken: string) => void;`**   
Chamado com um AWS WAF token válido quando o usuário final conclui com sucesso um quebra-cabeça de CAPTCHA. Use o token nas solicitações que você envia aos endpoints que você protege com um pacote de AWS WAF proteção (web ACL). O token fornece a prova e o timestamp da conclusão bem-sucedida do último quebra-cabeça.   
Obrigatório: Sim  
**`onError?: (error: CaptchaError) => void;`**   
Chamado com um objeto de erro quando ocorre um erro durante a operação CAPTCHA.   
Obrigatório: não  
**Definição de classe `CaptchaError`**: o manipulador `onError` fornece um tipo de erro com a seguinte definição de classe.   

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind`: o tipo de erro retornado. 
+ `statusCode`: o código de status do HTTP, se disponível. Isso é usado por `network_error` se o erro for devido a um erro no HTTP.  
**`onLoad?: () => void;`**   
Chamado quando um novo quebra-cabeça CAPTCHA é carregado.  
Obrigatório: não  
**`onPuzzleTimeout?: () => void;`**   
Chamado quando um quebra-cabeça CAPTCHA não é concluído antes de expirar.  
Obrigatório: não  
**`onPuzzleCorrect?: () => void;`**   
Chamado quando uma resposta correta é fornecida a um quebra-cabeça CAPTCHA.  
Obrigatório: não  
**`onPuzzleIncorrect?: () => void;`**   
Chamado quando uma resposta incorreta é fornecida a um quebra-cabeça CAPTCHA.  
Obrigatório: não  
**`defaultLocale`**   
A localidade padrão a ser usada para o quebra-cabeça CAPTCHA. As instruções escritas para quebra-cabeças CAPTCHA estão disponíveis em árabe (ar-SA), chinês simplificado (zh-CN), holandês (nl-NL), inglês (en-US), francês (fr-FR), alemão (de-DE), italiano (it-IT), japonês (ja-JP), português do Brasil (pt-BR), espanhol (es-ES) e turco (tr-TR). As instruções de áudio estão disponíveis para todos os idiomas escritos, exceto chinês e japonês, cujos padrões são o inglês. Para alterar o idioma padrão, forneça o idioma e o código de localidade internacionais, por exemplo, `ar-SA`.  
Padrão: o idioma atualmente em uso no navegador do usuário final  
Obrigatório: não  
Tipo: `string`  
**`disableLanguageSelector`**   
Se definido como `true`, o quebra-cabeça CAPTCHA oculta o seletor de idioma.   
Padrão: `false`  
Exigido: Não  
Tipo: `boolean`  
**`dynamicWidth`**   
Se definido como `true`, o quebra-cabeça CAPTCHA muda de largura para compatibilidade com a largura da janela do navegador.   
Padrão: `false`  
Exigido: Não  
Tipo: `boolean`  
**`skipTitle`**   
Se definido como `true`, o quebra-cabeça CAPTCHA não exibirá o título do quebra-cabeça **Resolva o quebra-cabeça**.   
Padrão: `false`  
Exigido: Não  
Tipo: `boolean`

# Como renderizar o quebra-cabeça CAPTCHA
<a name="waf-js-captcha-api-render"></a>

Esta seção fornece um exemplo de implementação `renderCaptcha`.

Você pode usar a AWS WAF `renderCaptcha` chamada onde quiser na interface do cliente. A chamada recupera um quebra-cabeça de CAPTCHA AWS WAF, o renderiza e envia os resultados para verificação. AWS WAF Ao fazer a chamada, você fornece a configuração de renderização do quebra-cabeça e os retornos de chamada que deseja executar quando os usuários finais concluírem o quebra-cabeça. Consulte a seção anterior, [Especificação da API CAPTCHA JavaScript](waf-js-captcha-api-specification.md), para detalhes sobre as opções.

Use essa chamada em conjunto com a funcionalidade de gerenciamento de tokens da integração APIs inteligente de ameaças. Essa chamada fornece ao seu cliente um token que verifica a conclusão bem-sucedida do quebra-cabeça CAPTCHA. Use a integração inteligente de ameaças APIs para gerenciar o token e fornecer o token nas chamadas do seu cliente para os endpoints protegidos com pacotes de AWS WAF proteção (web ACLs). Para obter informações sobre a ameaça inteligente APIs, consulte[Usando a JavaScript API de ameaças inteligentes](waf-js-challenge-api.md).

**Exemplos de implementação**  
A lista de exemplos a seguir mostra uma implementação padrão de CAPTCHA, incluindo o posicionamento da URL de AWS WAF integração na `<head>` seção. 

Essa listagem configura a `renderCaptcha` função com um retorno de chamada bem-sucedido que usa o `AwsWafIntegration.fetch` invólucro da integração inteligente de ameaças. APIs Para ter mais informações sobre essa função, consulte [Como usar o wrapper de integração `fetch`](waf-js-challenge-api-fetch-wrapper.md).

```
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>

<script type="text/javascript">
    function showMyCaptcha() {
        var container = document.querySelector("#my-captcha-container");
        
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            ...other configuration parameters as needed...
        });
    }
    
    function captchaExampleSuccessFunction(wafToken) {
        // Captcha completed. wafToken contains a valid WAF token. Store it for
        // use later or call AwsWafIntegration.fetch() to use it easily.
        // It will expire after a time, so calling AwsWafIntegration.getToken()
        // again is advised if the token is needed later on, outside of using the
        // fetch wrapper.
        
        // Use WAF token to access protected resources
        AwsWafIntegration.fetch("...WAF-protected URL...", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
            },
            body: "{ ... }" /* body content */
        });
    }
    
    function captchaExampleErrorFunction(error) {
        /* Do something with the error */
    }
</script>

<div id="my-captcha-container">
    <!-- The contents of this container will be replaced by the captcha widget -->
</div>
```

**Exemplo de definições de configuração**  
A lista de exemplo a seguir mostra o `renderCaptcha` com configurações não padrão para as opções de largura e o título. 

```
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            dynamicWidth: true, 
            skipTitle: true
        });
```

Para obter informações completas sobre as opções de configuração, consulte [Especificação da API CAPTCHA JavaScript](waf-js-captcha-api-specification.md).

# Manipulando uma resposta CAPTCHA de AWS WAF
<a name="waf-js-captcha-api-conditional"></a>

Esta seção fornece um exemplo de como lidar com uma resposta CAPTCHA.

Uma AWS WAF regra com uma CAPTCHA ação encerra a avaliação de uma solicitação da web correspondente se a solicitação não tiver um token com um carimbo de data/hora CAPTCHA válido. Se a solicitação for uma `GET` text/html chamada, a CAPTCHA ação então serve ao cliente um intersticial com um quebra-cabeça de CAPTCHA. Quando você não integra a JavaScript API CAPTCHA, o intersticial executa o quebra-cabeça e, se o usuário final o resolver com sucesso, reenvia automaticamente a solicitação. 

Ao integrar a JavaScript API CAPTCHA e personalizar o tratamento do CAPTCHA, você precisa detectar a resposta de encerramento do CAPTCHA, fornecer seu CAPTCHA personalizado e, se o usuário final resolver o quebra-cabeça com sucesso, reenviar a solicitação web do cliente. 

O exemplo de código a seguir mostra como fazer isso. 

**nota**  
A resposta da AWS WAF CAPTCHA ação tem um código de status HTTP 405, que usamos para reconhecer a CAPTCHA resposta nesse código. Se seu endpoint protegido usa um código de status HTTP 405 para comunicar qualquer outro tipo de resposta para a mesma chamada, esse código de exemplo também renderizará um quebra-cabeça CAPTCHA para essas respostas. 

```
<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>
<body>
    <div id="my-captcha-box"></div>
    <div id="my-output-box"></div>

    <script type="text/javascript">
    async function loadData() {
        // Attempt to fetch a resource that's configured to trigger a CAPTCHA
        // action if the rule matches. The CAPTCHA response has status=HTTP 405.
        const result = await AwsWafIntegration.fetch("/protected-resource");

        // If the action was CAPTCHA, render the CAPTCHA and return

        // NOTE: If the endpoint you're calling in the fetch call responds with HTTP 405
        // as an expected response status code, then this check won't be able to tell the
        // difference between that and the CAPTCHA rule action response.

        if (result.status === 405) {
            const container = document.querySelector("#my-captcha-box");
            AwsWafCaptcha.renderCaptcha(container, {
                apiKey: "...API key goes here...",
                onSuccess() {
                    // Try loading again, now that there is a valid CAPTCHA token
                    loadData();
                },
            });
            return;
        }

        const container = document.querySelector("#my-output-box");
        const response = await result.text();
        container.innerHTML = response;
    }

    window.addEventListener("load", () => {
        loadData();
    });
    </script>
</body>
</html>
```

# Como gerenciar chaves de API para a API JS CAPTCHA
<a name="waf-js-captcha-api-key"></a>

Esta seção fornece instruções para gerar e excluir chaves de API.

Para integrar o AWS WAF CAPTCHA em um aplicativo cliente com a JavaScript API, você precisa da tag de integração da JavaScript API e da chave de API criptografada para o domínio do cliente em que deseja executar o quebra-cabeça do CAPTCHA. 

A integração do aplicativo CAPTCHA JavaScript usa as chaves de API criptografadas para verificar se o domínio do aplicativo cliente tem permissão para usar a API AWS WAF CAPTCHA. Ao chamar a API CAPTCHA do seu JavaScript cliente, você fornece uma chave de API com uma lista de domínios que inclui um domínio para o cliente atual. Você pode listar até 5 domínios em uma única chave criptografada. 

**Requisitos de chaves de API**  
A chave de API que você usa na integração do CAPTCHA deve conter um domínio que se aplique ao cliente em que você usa a chave. 
+ Se você especificar um `window.awsWafCookieDomainList` na integração de ameaças inteligentes do seu cliente, pelo menos um domínio em sua chave de API deverá corresponder exatamente a um dos domínios de token em `window.awsWafCookieDomainList` ou deverá ser o domínio apex de um desses domínios de token. 

  Por exemplo, para o domínio do token `mySubdomain.myApex.com`, a chave de API `mySubdomain.myApex.com` é uma correspondência exata e a chave de API `myApex.com` é o domínio apex. Qualquer chave corresponde ao domínio do token. 

  Para obter informações sobre a configuração da lista de domínios de tokens, consulte [Fornecimento de domínios para uso nos tokens](waf-js-challenge-api-set-token-domain.md).
+ Caso contrário, o domínio atual deverá estar contido na chave da API. O domínio atual é o domínio que você pode ver na barra de endereço do navegador. 

Os domínios que você usa devem ser aqueles que AWS WAF serão aceitos, com base no domínio de host protegido e na lista de domínios de token configurada para a Web ACL. Para obter mais informações, consulte [AWS WAF configuração da lista de domínios de token do pacote de proteção (web ACL)](waf-tokens-domains.md#waf-tokens-domain-lists).

**Como escolher a região da sua chave de API**  
AWS WAF pode gerar chaves de API CAPTCHA em qualquer região em que AWS WAF esteja disponível. 

Como regra geral, você deve usar a mesma região para a chave de API de CAPTCHA que usa para o pacote de proteção (ACL da Web). No entanto, se você espera um público global para um pacote de proteção regional (Web ACL), você pode obter uma tag de JavaScript integração CAPTCHA com escopo CloudFront e uma chave de API com escopo e usá-las com um pacote de proteção regional (Web ACL). CloudFront Essa abordagem permite que os clientes carreguem um código CAPTCHA da região mais próxima a eles, o que reduz a latência. 

As chaves da API CAPTCHA que têm como escopo regiões diferentes das CloudFront quais não são suportadas para uso em várias regiões. Elas só podem ser usadas na região para a qual estão previstas. 

**Para gerar uma chave de API para seus domínios de clientes**  
Para obter a URL de integração e gerar e recuperar as chaves de API por meio do console. 

1. Faça login no Console de gerenciamento da AWS e abra o AWS WAF console em [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. No painel de navegação, escolha **Integração de aplicativos**. 

1. No painel, **pacotes de proteção (web ACLs) que estão habilitados para integração de aplicativos**, selecione a região que você deseja usar para sua chave de API. Você também pode selecionar a região no painel de **Chaves de API** da guia de **Integração do CAPTCHA**.

1. Escolha a guia **Integração de CAPTCHA**. Essa guia fornece a tag de JavaScript integração CAPTCHA, que você pode usar em sua integração, e a lista de chaves de API. Ambos têm como escopo a região selecionada.

1. No painel **Chaves de API**, escolha **Gerar chave**. A caixa de diálogo de geração de chaves é exibida. 

1. Insira os domínios de cliente que você deseja incluir na chave. Você pode inserir até 5. Quando terminar, escolha **Gerar chave**. A interface retorna à guia de integração do CAPTCHA, onde sua nova chave está listada. 

   Depois de criada, uma chave de API é imutável. Se você precisar fazer alterações em uma chave, gere uma nova chave e use-a em vez disso. 

1. (Opcional) Copie a chave recém-gerada para uso em sua integração. 

Você também pode usar o REST APIs ou um idioma específico AWS SDKs para esse trabalho. As chamadas da API REST são [Criar APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) e [Listar APIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html). 

**Para excluir uma chave de API**  
Para excluir uma chave de API, você deve usar a API REST ou uma linguagem específica AWS SDKs. A chamada da API REST é [Delete APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html). Você não pode usar o console para excluir uma chave. 

Depois de excluir uma chave, pode levar até 24 horas para AWS WAF proibir o uso da chave em todas as regiões. 

# AWS WAF integração de aplicativos móveis
<a name="waf-mobile-sdk"></a>

Esta seção apresenta o tópico do uso do AWS WAF celular SDKs para implementar a integração AWS WAF inteligente de ameaças SDKs para aplicativos móveis e de TV para Android e iOS. Para aplicativos de TV, SDKs eles são compatíveis com as principais plataformas de smart TV, incluindo Android TV e Apple TV.
+ Para aplicativos Android para celular e TV, o SDKs Work for Android API versão 23 (Android versão 6) e versões posteriores. Para obter informações sobre as versões do Android, consulte as [Notas de lançamento da plataforma de SDK](https://developer.android.com/tools/releases/platforms).
+ Para aplicativos móveis iOS, eles SDKs funcionam para iOS versão 13 e posterior. Para obter informações sobre as versões do iOS, consulte as [Notas de versão do iOS e iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Para aplicativos da Apple TV, eles SDKs funcionam para tvOS versão 14 ou posterior. Para obter informações sobre as versões do tvOS, consulte [tvOS Release Notes](https://developer.apple.com/documentation/tvos-release-notes).

Com o AWS WAF SDK móvel, você pode gerenciar a autorização de tokens e incluir os tokens nas solicitações que você envia aos seus recursos protegidos. Ao usar o SDKs, você garante que essas chamadas de procedimento remoto feitas pelo seu cliente contenham um token válido. Além disso, quando essa integração está implementada nas páginas da aplicação, você pode implementar regras de mitigação no pacote de proteção (ACL da Web), como bloquear solicitações que não contenham um token válido.

Para acessar o celular SDKs, entre em contato com o suporte em [Contato AWS](https://aws.amazon.com/contact-us).

**nota**  
O AWS WAF celular SDKs não está disponível para personalização de CAPTCHA.

A abordagem básica para usar o SDK é criar um provedor de token usando um objeto de configuração e, em seguida, usar o provedor de token para recuperar tokens. AWS WAF Por padrão, o provedor de token inclui os tokens recuperados em suas solicitações da web para seu recurso protegido. 

Veja a seguir uma lista parcial de uma implementação de SDK, que mostra os principais componentes. Para obter mais exemplos detalhados, consulte [Exemplos de código para o SDK AWS WAF móvel](waf-mobile-sdk-coding-examples.md).

------
#### [ iOS ]

```
let url: URL = URL(string: "protection pack (web ACL) integration URL")!
	let configuration = WAFConfiguration(applicationIntegrationUrl: url, domainName: "Domain name")
	let tokenProvider = WAFTokenProvider(configuration)
	let token = tokenProvider.getToken()
```

------
#### [ Android ]

```
URL applicationIntegrationURL = new URL("protection pack (web ACL) integration URL");
	String domainName = "Domain name";
	WAFConfiguration configuration = WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL).domainName(domainName).build();
	WAFTokenProvider tokenProvider = new WAFTokenProvider(Application context, configuration);
	WAFToken token = tokenProvider.getToken();
```

------

# Instalando o SDK AWS WAF móvel
<a name="waf-mobile-sdk-installing"></a>

Esta seção fornece instruções para instalar o SDK AWS WAF móvel.

Para acessar o celular SDKs, entre em contato com o suporte em [Contato AWS](https://aws.amazon.com/contact-us).

Implemente a integração com SDK móvel primeiro em um ambiente de teste e depois na produção.

**Para instalar o SDK AWS WAF móvel**

1. Faça login no Console de gerenciamento da AWS e abra o AWS WAF console em [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. No painel de navegação, escolha **Integração de aplicativos**. 

1. Na guia **Integrações de ameaças inteligentes**, faça o seguinte: 

   1. No painel **pacotes de proteção (web ACLs) que estão habilitados para integração de aplicativos**, localize o pacote de proteção (web ACL) com o qual você está se integrando. Copie e salve a URL da integração do pacote de proteção (ACL da Web) para uso em sua implementação. Você também pode obter esse URL por meio da chamada da API `GetWebACL`.

   1. Escolha o tipo e a versão do dispositivo móvel e, em seguida, escolha **Baixar**. Você pode escolher qualquer versão que desejar, mas recomendamos usar a versão mais recente. AWS WAF baixa o `zip` arquivo do seu dispositivo em seu local de download padrão.

1. Em seu ambiente de desenvolvimento de aplicativos, descompacte o arquivo em um local de trabalho de sua escolha. No diretório de nível superior do arquivo zip, localize e abra o `README`. Siga as instruções no `README` arquivo para instalar o SDK AWS WAF móvel para uso no código do seu aplicativo móvel. 

1. Programe seu aplicativo de acordo com as orientações nas seções a seguir.

# AWS WAF especificação de SDK móvel
<a name="waf-mobile-sdk-specification"></a>

Esta seção lista os objetos, as operações e as configurações de SDK para a versão mais recente disponível do SDK móvel do AWS WAF . Para obter informações detalhadas sobre como o provedor de token e as operações funcionam para as várias combinações de configurações, consulte [Como o SDK AWS WAF móvel funciona](waf-mobile-sdk-how-it-works.md). 

**`WAFToken`**  
Guarda uma AWS WAF ficha.    
**`getValue()`**  
Recupera a representação `String` de `WAFToken`. 

**`WAFTokenProvider`**  
Gerencia tokens em seu aplicativo móvel. Implemente isso usando um objeto `WAFConfiguration`.    
**`getToken()`**  
Se a atualização em segundo plano estiver ativada, isso retornará o token em cache. Se a atualização em segundo plano estiver desativada, isso fará uma chamada síncrona e bloqueadora AWS WAF para recuperar um novo token.   
**`loadTokenIntoProvider(WAFToken)`**  
Carrega o token especificado no `WAFTokenProvider`, substituindo qualquer token que o provedor estava gerenciando. O provedor do tokens assume a propriedade do novo token e se encarrega de atualizá-lo daqui para frente. Essa operação também atualiza o token no armazenamento de cookies, se `setTokenCookie` estiver habilitada no`WAFConfiguration`.  
**`onTokenReady(WAFTokenResultCallback)`**  
Instrui o provedor de token a atualizar o token e invocar o retorno de chamada fornecido quando um token ativo estiver pronto. O provedor do token invocará seu retorno de chamada em um thread em segundo plano quando o token estiver armazenado em cache e pronto. Chame isso quando seu aplicativo for carregado pela primeira vez e também quando ele voltar ao estado ativo. Para saber mais sobre como retornar a um estado ativo, consulte [Recuperação de um token após a inatividade do aplicativo](waf-mobile-sdk-how-it-works.md#waf-mobile-sdk-how-back-from-inactive).   
Para aplicativos Android ou iOS, você pode definir `WAFTokenResultCallback` para a operação que deseja que o provedor de token invoque quando um token solicitado estiver pronto. Sua implementação do `WAFTokenResultCallback` deve seguir os parâmetros `WAFToken`, `SdkError`. Para aplicativos iOS, você pode criar alternadamente uma função embutida.   
**`storeTokenInCookieStorage(WAFToken)`**  
Instrui o `WAFTokenProvider` a armazenar o AWS WAF token especificado no gerenciador de cookies do SDK. Por padrão, o token só é adicionado ao armazenamento de cookies quando é adquirido pela primeira vez e quando é atualizado. Se o aplicativo limpar o armazenamento de cookies compartilhado por qualquer motivo, o SDK não adicionará automaticamente o AWS WAF token de volta até a próxima atualização. 

**`WAFConfiguration`**  
Mantém a configuração para a implementação do `WAFTokenProvider`. Ao implementar isso, você fornece a URL de integração do pacote de proteção (ACL da Web), o nome de domínio a ser usado no token e todas as configurações não padrão que você deseja que o provedor de token use.   
A lista a seguir especifica as configurações que você pode gerenciar no objeto `WAFConfiguration`.    
**`applicationIntegrationUrl`**   
O URL de integração do aplicativo. Obtenha isso no AWS WAF console ou por meio da chamada de `getWebACL` API.  
Obrigatório: Sim  
Tipo: URL específico do aplicativo. Para iOS, consulte o [URL do iOS](https://developer.apple.com/documentation/foundation/url). Para Android, consulte o [URL do java.net](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html).   
**`backgroundRefreshEnabled`**   
Indica se você deseja que o provedor de token atualize o token em segundo plano. Se você definir isso, o provedor de token atualizará seus tokens em segundo plano de acordo com as configurações que regem as atividades de atualização automática de tokens.   
Obrigatório: não  
Tipo: `Boolean`  
Valor padrão: `TRUE`  
**`domainName`**   
O domínio a ser usado no token, que é usado na aquisição e armazenamento de cookies. Por exemplo, `example.com` ou `aws.amazon.com`. Geralmente, esse é o domínio do host do seu recurso associado ao pacote de proteção (ACL da Web), para onde você enviará solicitações da Web. Para o grupo de regras gerenciadas do ACFP, `AWSManagedRulesACFPRuleSet`, geralmente será um único domínio que corresponde ao domínio no caminho de criação da conta que você forneceu na configuração do grupo de regras. Para o grupo de regras gerenciadas do ATP, `AWSManagedRulesATPRuleSet`, geralmente será um único domínio que corresponde ao domínio no caminho de login fornecido na configuração do grupo de regras.   
Não são permitidos sufixos públicos. Por exemplo, você não pode usar `gov.au` ou `co.uk` como domínio do token.  
O domínio deve ser aceito, com base no domínio do host protegido e na lista de domínios de tokens do pacote de proteção (web ACL). AWS WAF Para obter mais informações, consulte [AWS WAF configuração da lista de domínios de token do pacote de proteção (web ACL)](waf-tokens-domains.md#waf-tokens-domain-lists).  
Obrigatório: Sim  
Tipo: `String`   
**`maxErrorTokenRefreshDelayMsec`**   
O tempo máximo em milissegundos a se esperar antes de repetir uma atualização de token após uma tentativa malsucedida. Para cada repetição automática de uma tentativa malsucedida, ele adicionará um recuo exponencial até o tempo de atraso de entrada determinado. Esse valor é usado depois que a recuperação do token falhou e foi repetida `maxRetryCount` vezes.   
Obrigatório: não  
Tipo: `Integer`  
Valor padrão: `5000` (5 segundos)  
Valor mínimo permitido: `1` (1 milissegundo)  
Valor máximo permitido: `30000` (30 segundos)  
**`maxRetryCount`**   
O número máximo de novas tentativas a serem executadas com recuo exponencial quando um token é solicitado.   
Obrigatório: não  
Tipo: `Integer`  
Valor padrão: `Infinity`  
Valor mínimo permitido: `0`  
Valor máximo permitido: `100`  
**`setTokenCookie`**   
Indica se você deseja que o gerenciador de cookies do SDK adicione um cookie de token às suas solicitações.   
Com um valor `TRUE`:   
+ O gerenciador de cookies adiciona um cookie de token a qualquer solicitação cujo caminho esteja abaixo do caminho especificado em `tokenCookiePath`. 
+ A operação do `WAFTokenProvider` `loadTokenIntoProvider()` atualiza o token no armazenamento de cookies, além de carregá-lo no provedor do tokens.
Obrigatório: não  
Tipo: `Boolean`  
Valor padrão: `TRUE`  
**`tokenCookiePath`**   
Usado quando `setTokenCookie` é `TRUE`. Indica o caminho de nível superior em que você deseja que o gerenciador de cookies do SDK adicione um cookie de token. O gerente adiciona um cookie de token a todas as solicitações que você envia para esse caminho e para todos os caminhos secundários.   
Por exemplo, se você definir isso como `/web/login`, o gerenciador incluirá o cookie de token para tudo o que é enviado para `/web/login` e para qualquer um de seus caminhos secundários, como `/web/login/help`. Ele não inclui o token para solicitações enviadas para outros caminhos, como `/`, `/web` ou `/web/order`.   
Obrigatório: não  
Tipo: `String`  
Valor padrão: `/`  
**`tokenRefreshDelaySec`**   
Usado para atualização em segundo plano. O tempo máximo em segundos entre as atualizações do token em segundo plano.  
Obrigatório: não  
Tipo: `Integer`  
Valor padrão: `88`  
Valor mínimo permitido: `88`  
Valor máximo permitido: `300` (5 minutos)

## AWS WAF erros do SDK móvel
<a name="waf-mobile-sdk-errors"></a>

Esta seção lista os possíveis erros da versão atual do SDK AWS WAF móvel.

**`SdkError`**  
O tipo de erro retornado quando há falha na recuperação de um token. O SDK para Android e iOS têm os mesmos tipos de erro.  
O SDK AWS WAF móvel tem os seguintes tipos de erro:    
**`invalidChallenge`**  
Esse erro é retornado quando o servidor de tokens retorna dados de desafio inválidos ou o blob de resposta é alterado por um invasor.  
**`errorInvokingGetChallengeEndpoint`**  
Esse erro é retornado quando o servidor de token envia um código de resposta sem sucesso de volta ao cliente ou quando ocorre um erro de rede.  
**`invalidVerifyChallengeResponse`**  
Esse erro é retornado quando há um erro ao recuperar a resposta `aws-waf-token` de verificação do AWS WAF servidor ou quando a resposta do servidor foi adulterada.  
**`errorInvokingVerifyEndpoint`**  
Esse erro é retornado quando o cliente recebe uma resposta incorreta do AWS WAF servidor ou erro de rede ao verificar o desafio resolvido.  
**`internalError`**  
Esse erro é retornado em todos os outros erros que podem ocorrer no próprio SDK.

**`socketTimeoutException`**  
Esse erro geralmente é retornado ao encontrar erros de rede durante a recuperação do token.  
Isso pode ser causado por uma das seguintes situações:  
+ Baixa largura de banda da rede: confirme as configurações de conectividade de rede
+ URL de integração de aplicativos modificada: confirme se a URL de integração não foi modificada em relação ao que aparece no console AWS WAF 

# Como o SDK AWS WAF móvel funciona
<a name="waf-mobile-sdk-how-it-works"></a>

Esta seção explica como as classes, propriedades e operações do SDK AWS WAF móvel funcionam juntas.

O celular SDKs fornece um provedor de token configurável que você pode usar para recuperação e uso de tokens. O provedor do token verifica se as solicitações que você permite são de clientes legítimos. Ao enviar solicitações para os AWS recursos com os quais você protege AWS WAF, você inclui o token em um cookie para validar a solicitação. Você pode manipular o cookie do token manualmente ou fazer com que o provedor do token faça isso por você.

Esta seção aborda as interações entre as classes, propriedades e métodos incluídos no SDK móvel. Para obter a especificação do SDK, consulte [AWS WAF especificação de SDK móvel](waf-mobile-sdk-specification.md). 

## Recuperação e armazenamento em cache de tokens
<a name="waf-mobile-sdk-how-token-basics"></a>

Ao criar a instância do provedor de token em seu aplicativo móvel, você configura como deseja que ela gerencie os tokens e a recuperação de tokens. Sua principal opção é como manter tokens válidos e não expirados para uso nas solicitações da web do seu aplicativo:
+ **Atualização em segundo plano ativada**: esse é o padrão. O provedor de token atualiza automaticamente o token em segundo plano e o armazena em cache. Com a atualização em segundo plano ativada, quando você chama `getToken()`, a operação recupera o token em cache. 

  O provedor de token executa a atualização do token em intervalos configuráveis, para que um token não expirado esteja sempre disponível no cache enquanto o aplicativo estiver ativo. A atualização em segundo plano é pausada enquanto seu aplicativo está em um estado inativo. Para obter mais informações sobre isso, consulte [Recuperação de um token após a inatividade do aplicativo](#waf-mobile-sdk-how-back-from-inactive).
+ **Atualização em segundo plano desativada**: você pode desativar a atualização de tokens em segundo plano e, em seguida, recuperar tokens somente sob demanda. Os tokens recuperados sob demanda não são armazenados em cache e você pode recuperar mais de um, se quiser. Cada token é independente de qualquer outro que você recupere e cada um tem seu próprio timestamp que é usado para calcular a expiração.

  Você tem as seguintes opções para recuperação de token quando a atualização em segundo plano está desativada: 
  + **`getToken()`**— Quando você liga `getToken()` com a atualização em segundo plano desativada, a chamada recupera de forma síncrona um novo token de. AWS WAF Essa é uma chamada potencialmente bloqueadora que pode afetar a capacidade de resposta da aplicação se você a invocar no thread principal. 
  + **`onTokenReady(WAFTokenResultCallback)`**: essa chamada recupera de forma assíncrona um novo token e, em seguida, invoca o retorno de chamada do resultado fornecido em um thread em segundo plano quando um token está pronto. 

### Como o provedor de token tenta novamente recuperações de tokens com falha
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

O provedor de token repete automaticamente a recuperação do token quando a recuperação falha. As novas tentativas são executadas inicialmente usando o recuo exponencial com um tempo de espera inicial de 100 ms. Para obter mais repetições de tentaivas exponenciais, consulte [Novas tentativas e recuo exponencial na AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html).

Quando o número de novas tentativas atinge o `maxRetryCount` configurado, o provedor do token para de tentar ou passa a tentar a cada `maxErrorTokenRefreshDelayMsec` milissegundos, dependendo do tipo de recuperação do token: 
+ **`onTokenReady()`**: o provedor do token passa a esperar `maxErrorTokenRefreshDelayMsec` milissegundos entre as tentativas e continua tentando recuperar o token. 
+ **Atualização em segundo plano**: o provedor de token passa a esperar `maxErrorTokenRefreshDelayMsec` milissegundos entre as tentativas e continua tentando recuperar o token. 
+ **Chamadas `getToken()` sob demanda, quando a atualização em segundo plano está desativada**: o provedor de token para de tentar recuperar um token e retorna o valor do token anterior ou um valor nulo se não houver nenhum token anterior. 

## Cenários de nova tentativa de recuperação de tokens
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

Quando o provedor do tokens tenta recuperar um token, isso pode resultar em novas tentativas automáticas, dependendo de onde a recuperação do token falha no fluxo de aquisição do token. Esta seção lista os possíveis locais em que você pode ver uma nova tentativa automática.
+ **Obtendo ou verificando o AWS WAF Desafio por meio de /inputs ou /verify:**
  + Quando uma solicitação para obter e verificar uma AWS WAF contestação é feita e falha, isso pode resultar em uma nova tentativa automática.
  + Você pode observar novas tentativas automáticas acontecendo aqui junto com um erro de `socketTimeoutException`. Isso pode ter várias causas, incluindo:
    + Baixa largura de banda da rede: confirme as configurações de conectividade de rede
    + URL de integração de aplicativos modificada: confirme se a URL de integração não foi modificada em relação ao que aparece no console AWS WAF 
  + A contagem de repetições automáticas é configurável com a função `maxRetryCount()`.
+ **Atualizar o tokens:**
  + Quando uma solicitação para atualizar o token é feita por meio do manipulador de tokens, isso pode resultar em uma nova tentativa automática.
  + A contagem de repetições automáticas aqui é configurável com a função `maxRetryCount()`.

Uma configuração sem novas tentativas automáticas é possível por meio da definição de `maxRetryCount(0)`.

## Tempo de imunidade do token e atualização em plano de fundo
<a name="waf-mobile-sdk-how-token-immunity"></a>

O tempo de imunidade do token que você configura na Web ACL é independente do intervalo de atualização do token definido no SDK AWS WAF móvel. Quando você ativa a atualização em segundo plano, o SDK atualiza o token no intervalo que você especifica usando `tokenRefreshDelaySec()`. Isso pode resultar na existência simultânea de vários tokens válidos, dependendo do tempo de imunidade configurado.

Para evitar vários tokens válidos, desabilite a atualização em segundo plano e use a função `getToken()` para gerenciar o ciclo de vida do token em sua aplicação móvel.

## Recuperação de um token após a inatividade do aplicativo
<a name="waf-mobile-sdk-how-back-from-inactive"></a>

A atualização em segundo plano só é realizada enquanto seu aplicativo é considerado ativo para seu tipo de aplicativo: 
+ **iOS**: a atualização em segundo plano é realizada quando o aplicativo está em primeiro plano.
+ **Android**: a atualização em segundo plano é realizada quando o aplicativo não está fechado, seja em primeiro plano ou em segundo plano.

Se seu aplicativo permanecer em qualquer estado que não ofereça suporte à atualização em segundo plano por mais tempo do que os `tokenRefreshDelaySec` segundos configurados, o provedor de token pausará a atualização em segundo plano. Por exemplo, para um aplicativo iOS, se `tokenRefreshDelaySec` for 300 e o aplicativo fechar ou ficar em segundo plano por mais de 300 segundos, o provedor do token interromperá a atualização do token. Quando o aplicativo retorna ao estado ativo, o provedor de token reinicia automaticamente a atualização em segundo plano. 

Quando seu aplicativo voltar ao estado ativo, chame `onTokenReady()` para que você possa ser notificado quando o provedor do token tiver recuperado e armazenado em cache um novo token. Não chame `getToken()`, porque o cache pode ainda não conter um token válido e atual. 

## A URL de integração da aplicação
<a name="waf-mobile-sdk-application-integration-url"></a>

O URL de integração de aplicativos do SDK AWS WAF móvel aponta para uma Web ACL que você habilitou para integração de aplicativos. Essa URL encaminha as solicitações para o servidor de backend correto e as associa ao seu cliente. Ela não serve como um controle de segurança rígido, portanto, expor uma URL de integração não representa um risco de segurança.

Você pode modificar tecnicamente a URL de integração fornecida e ainda obter um token. No entanto, não recomendamos isso porque você pode perder a visibilidade das taxas de resolução de desafios ou encontrar falhas na recuperação de tokens com erros `socketTimeoutException`.

## Dependências
<a name="waf-mobile-sdk-dependencies"></a>

Cada SDK AWS WAF móvel disponível para download inclui um arquivo README que lista as dependências de sua versão específica do SDK. Consulte o README para ver as dependências da sua versão do SDK móvel.

## Ofuscação/ ProGuard (somente SDK para Android)
<a name="waf-mobile-sdk-obfuscation"></a>

Se você usa um produto de ofuscação ou minificação ProGuard, como o, talvez seja necessário excluir determinados namespaces para garantir que o SDK móvel funcione corretamente. Verifique o README da sua versão do SDK móvel para encontrar a lista de namespaces e regras de exclusão.

# Exemplos de código para o SDK AWS WAF móvel
<a name="waf-mobile-sdk-coding-examples"></a>

Esta seção fornece exemplos de código para uso do SDK móvel. 

## Inicialização do provedor de tokens e obtenção de tokens
<a name="waf-mobile-sdk-coding-basic"></a>

Você inicia sua instância do provedor de token usando um objeto de configuração. Em seguida, você pode recuperar tokens usando as operações disponíveis. Veja a seguir os componentes básicos do código necessário.

------
#### [ iOS ]

```
let url: URL = URL(string: "protection pack (web ACL) integration URL")!
let configuration = WAFConfiguration(applicationIntegrationUrl: url, domainName: "Domain name")
let tokenProvider = WAFTokenProvider(configuration)

//onTokenReady can be add as an observer for UIApplication.willEnterForegroundNotification
self.tokenProvider.onTokenReady() { token, error in
	if let token = token {
	//token available
	}

	if let error = error {
	//error occurred after exhausting all retries
	}
}

//getToken()
let token = tokenProvider.getToken()
```

------
#### [ Android ]

Exemplo de Java:

```
String applicationIntegrationURL = "protection pack (web ACL) integration URL";
//Or
URL applicationIntegrationURL = new URL("protection pack (web ACL) integration URL");

String domainName = "Domain name";

WAFConfiguration configuration = WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL).domainName(domainName).build();
WAFTokenProvider tokenProvider = new WAFTokenProvider(Application context, configuration);

// implement a token result callback
WAFTokenResultCallback callback = (wafToken, error) -> {
	if (wafToken != null) {
	// token available
	} else {  
	// error occurred in token refresh  
	}
};

// Add this callback to application creation or activity creation where token will be used
tokenProvider.onTokenReady(callback);

// Once you have token in token result callback
// if background refresh is enabled you can call getToken() from same tokenprovider object
// if background refresh is disabled you can directly call getToken()(blocking call) for new token
WAFToken token = tokenProvider.getToken();
```

Exemplo de Kotlin:

```
import com.amazonaws.waf.mobilesdk.token.WAFConfiguration
import com.amazonaws.waf.mobilesdk.token.WAFTokenProvider

private lateinit var wafConfiguration: WAFConfiguration
private lateinit var wafTokenProvider: WAFTokenProvider

private val WAF_INTEGRATION_URL = "protection pack (web ACL) integration URL"
private val WAF_DOMAIN_NAME = "Domain name"

fun initWaf() {
	// Initialize the tokenprovider instance
	val applicationIntegrationURL = URL(WAF_INTEGRATION_URL)
	wafConfiguration =
		WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL)
			.domainName(WAF_DOMAIN_NAME).backgroundRefreshEnabled(true).build()
	wafTokenProvider = WAFTokenProvider(getApplication(), wafConfiguration)
	
		// getToken from tokenprovider object
		println("WAF: "+ wafTokenProvider.token.value)
	
		// implement callback for where token will be used
		wafTokenProvider.onTokenReady {
			wafToken, sdkError ->
		run {
			println("WAF Token:" + wafToken.value)
		}
	}
}
```

------

## Permitindo que o SDK forneça o cookie de token em suas solicitações HTTP
<a name="waf-mobile-sdk-coding-auto-token-cookie"></a>

Se `setTokenCookie` é `TRUE`, o provedor de token inclui o cookie de token para você em suas solicitações da web para todos os locais no caminho especificado em `tokenCookiePath`. Por padrão, `setTokenCookie` é `TRUE` e `tokenCookiePath` é `/`. 

Você pode restringir o escopo das solicitações que incluem um cookie de token especificando o caminho do cookie de token, por exemplo, `/web/login`. Se você fizer isso, verifique se suas AWS WAF regras não inspecionam os tokens nas solicitações que você envia para outros caminhos. Ao usar o grupo de regras `AWSManagedRulesACFPRuleSet`, você configura os caminhos de registro e criação da conta, e o grupo de regras verifica os tokens nas solicitações enviadas para esses caminhos. Para saber mais, consulte [Adicionando o grupo de regras gerenciadas do ACFP à sua web ACL](waf-acfp-rg-using.md). Da mesma forma, ao usar o grupo de regras `AWSManagedRulesATPRuleSet`, você configura o caminho de login e o grupo de regras verifica os tokens nas solicitações enviadas para esse caminho. Para obter mais informações, consulte [Adicionar grupos de regras gerenciadas ao pacote de proteção (ACL da Web)](waf-atp-rg-using.md). 

------
#### [ iOS ]

Quando `setTokenCookie` é`TRUE`, o provedor de token armazena o AWS WAF token em um `HTTPCookieStorage.shared` e inclui automaticamente o cookie nas solicitações para o domínio que você especificou`WAFConfiguration`.

```
let request = URLRequest(url: URL(string: domainEndpointUrl)!)
//The token cookie is set automatically as cookie header
let task = URLSession.shared.dataTask(with: request) { data, urlResponse, error  in
}.resume()
```

------
#### [ Android ]

Quando `setTokenCookie` estiver`TRUE`, o provedor de token armazena o AWS WAF token em uma `CookieHandler` instância que é compartilhada em todo o aplicativo. O provedor de token inclui automaticamente o cookie nas solicitações para o domínio que você especificou em `WAFConfiguration`.

Exemplo de Java:

```
URL url = new URL("Domain name");
//The token cookie is set automatically as cookie header
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
connection.getResponseCode();
```

Exemplo de Kotlin:

```
val url = URL("Domain name")
//The token cookie is set automatically as cookie header
val connection = (url.openConnection() as HttpsURLConnection)
connection.responseCode
```

Se você já tiver a instância padrão `CookieHandler` inicializada, o provedor de token a usará para gerenciar cookies. Caso contrário, o provedor de token inicializará uma nova `CookieManager` instância com o AWS WAF token `CookiePolicy.ACCEPT_ORIGINAL_SERVER` e, em seguida, definirá essa nova instância como a instância padrão em`CookieHandler`.

O código a seguir mostra como o SDK inicializa o gerenciador e o manipulador de cookies quando eles não estão disponíveis no seu aplicativo. 

Exemplo de Java:

```
CookieManager cookieManager = (CookieManager) CookieHandler.getDefault();
if (cookieManager == null) {
	// Cookie manager is initialized with CookiePolicy.ACCEPT_ORIGINAL_SERVER
	cookieManager = new CookieManager();
	CookieHandler.setDefault(cookieManager);
}
```

Exemplo de Kotlin:

```
var cookieManager = CookieHandler.getDefault() as? CookieManager
if (cookieManager == null) {
	// Cookie manager is initialized with CookiePolicy.ACCEPT_ORIGINAL_SERVER
	cookieManager = CookieManager()
	CookieHandler.setDefault(cookieManager)
}
```

------

## Fornecimento manual do cookie de token em suas solicitações HTTP
<a name="waf-mobile-sdk-coding-manual-token-cookie"></a>

Se você definir `setTokenCookie` como `FALSE`, precisará fornecer o cookie de token manualmente, como um cabeçalho de solicitação HTTP de cookie, em suas solicitações para seu endpoint protegido. O código a seguir mostra como fazer isso.

------
#### [ iOS ]

```
var request = URLRequest(url: wafProtectedEndpoint)
request.setValue("aws-waf-token=token from token provider", forHTTPHeaderField: "Cookie")
request.httpShouldHandleCookies = true
URLSession.shared.dataTask(with: request) { data, response, error in }
```

------
#### [ Android ]

Exemplo de Java:

```
URL url = new URL("Domain name");
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
String wafTokenCookie = "aws-waf-token=token from token provider";
connection.setRequestProperty("Cookie", wafTokenCookie);
connection.getInputStream();
```

Exemplo de Kotlin:

```
val url = URL("Domain name")
val connection = (url.openConnection() as HttpsURLConnection)
val wafTokenCookie = "aws-waf-token=token from token provider"
connection.setRequestProperty("Cookie", wafTokenCookie)
connection.inputStream
```

------