**Memperkenalkan pengalaman konsol baru untuk AWS WAF**

Anda sekarang dapat menggunakan pengalaman yang diperbarui untuk mengakses AWS WAF fungsionalitas di mana saja di konsol. Untuk detail selengkapnya, lihat [Bekerja dengan konsol](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). 

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Integrasi aplikasi klien di AWS WAF
<a name="waf-application-integration"></a>

Bagian ini menjelaskan cara menggunakan integrasi ancaman cerdas APIs dan API integrasi JavaScript CAPTCHA dengan fitur Anda AWS WAF . 

Gunakan integrasi aplikasi AWS WAF klien APIs untuk memasangkan perlindungan sisi klien dengan perlindungan paket perlindungan AWS sisi server (web ACL) Anda, untuk membantu memverifikasi bahwa aplikasi klien yang mengirim permintaan web ke sumber daya yang dilindungi adalah klien yang dituju dan bahwa pengguna akhir Anda adalah manusia. 

Gunakan integrasi klien untuk mengelola tantangan browser senyap dan teka-teki CAPTCHA, dapatkan token dengan bukti keberhasilan browser dan tanggapan pengguna akhir, dan untuk memasukkan token ini dalam permintaan ke titik akhir Anda yang dilindungi. Untuk informasi umum tentang AWS WAF token, lihat[Penggunaan token dalam AWS WAF mitigasi ancaman cerdas](waf-tokens.md). 

Gabungkan integrasi klien Anda dengan perlindungan paket perlindungan (web ACL) yang memerlukan token yang valid untuk akses ke sumber daya Anda. Anda dapat menggunakan grup aturan yang memeriksa dan memantau token tantangan, seperti yang tercantum di bagian berikutnya, di[Integrasi ancaman cerdas dan Aturan AWS Terkelola](waf-application-integration-with-AMRs.md), dan Anda dapat menggunakan tindakan CAPTCHA dan Challenge aturan untuk memeriksa, seperti yang dijelaskan dalam[CAPTCHAdan Challenge di AWS WAF](waf-captcha-and-challenge.md). 

AWS WAF menyediakan dua tingkat integrasi untuk JavaScript aplikasi, dan satu untuk aplikasi seluler: 
+ **Integrasi ancaman cerdas** — Verifikasi aplikasi klien dan berikan akuisisi dan manajemen AWS token. Ini mirip dengan fungsi yang disediakan oleh tindakan AWS WAF Challenge aturan. Fungsionalitas ini sepenuhnya mengintegrasikan aplikasi klien Anda dengan grup aturan `AWSManagedRulesACFPRuleSet` terkelola, grup aturan `AWSManagedRulesATPRuleSet` terkelola, dan tingkat perlindungan yang ditargetkan dari grup aturan `AWSManagedRulesBotControlRuleSet` terkelola. 

  Integrasi ancaman cerdas APIs menggunakan tantangan browser AWS WAF senyap untuk membantu memastikan bahwa upaya login dan panggilan lain ke sumber daya Anda yang dilindungi hanya diizinkan setelah klien memperoleh token yang valid. APIs Mengelola otorisasi token untuk sesi aplikasi klien Anda dan mengumpulkan informasi tentang klien untuk membantu menentukan apakah itu dioperasikan oleh bot atau oleh manusia. 
**catatan**  
Ini tersedia untuk JavaScript dan untuk aplikasi seluler Android dan iOS. 
+ **Integrasi CAPTCHA** - Verifikasi pengguna akhir dengan teka-teki CAPTCHA yang disesuaikan yang Anda kelola dalam aplikasi Anda. Ini mirip dengan fungsionalitas yang disediakan oleh tindakan AWS WAF CAPTCHA aturan, tetapi dengan kontrol tambahan atas penempatan dan perilaku teka-teki. 

  Integrasi ini memanfaatkan integrasi ancaman JavaScript cerdas untuk menjalankan tantangan diam dan memberikan AWS WAF token ke halaman pelanggan. 
**catatan**  
Ini tersedia untuk JavaScript aplikasi. 

**Topics**
+ [Integrasi ancaman cerdas dan Aturan AWS Terkelola](waf-application-integration-with-AMRs.md)
+ [Mengakses integrasi aplikasi AWS WAF klien APIs](waf-application-integration-location-in-console.md)
+ [AWS WAF JavaScript integrasi](waf-javascript-api.md)
+ [AWS WAF integrasi aplikasi seluler](waf-mobile-sdk.md)

# Integrasi ancaman cerdas dan Aturan AWS Terkelola
<a name="waf-application-integration-with-AMRs"></a>

Bagian ini menjelaskan cara APIs kerja integrasi ancaman cerdas dengan grup aturan Aturan AWS Terkelola.

Integrasi ancaman cerdas APIs bekerja dengan paket perlindungan (web ACLs) yang menggunakan kelompok aturan ancaman cerdas untuk mengaktifkan fungsionalitas penuh dari kelompok aturan terkelola lanjutan ini. 
+ AWS WAF Grup aturan terkelola pencegahan penipuan (ACFP) pembuatan akun Kontrol Penipuan. `AWSManagedRulesACFPRuleSet` 

  Penipuan pembuatan akun adalah aktivitas ilegal online di mana penyerang membuat akun yang tidak valid dalam aplikasi Anda untuk tujuan seperti menerima bonus pendaftaran atau meniru seseorang. Grup aturan terkelola ACFP menyediakan aturan untuk memblokir, memberi label, dan mengelola permintaan yang mungkin merupakan bagian dari upaya pembuatan akun palsu. APIs Memungkinkan verifikasi browser klien yang disetel dengan baik dan informasi interaktivitas manusia yang digunakan aturan ACFP untuk memisahkan lalu lintas klien yang valid dari lalu lintas berbahaya.

  Untuk informasi selengkapnya, lihat [AWS WAF Grup aturan pencegahan penipuan (ACFP) pembuatan akun Kontrol Penipuan](aws-managed-rule-groups-acfp.md) dan [AWS WAF Pencegahan penipuan pembuatan akun Kontrol Penipuan (ACFP)](waf-acfp.md).
+ AWS WAF Kelompok aturan terkelola pencegahan pengambilalihan akun Kontrol Penipuan (ATP). `AWSManagedRulesATPRuleSet` 

  Pengambilalihan akun adalah aktivitas ilegal online di mana penyerang mendapatkan akses tidak sah ke akun seseorang. Grup aturan terkelola ATP menyediakan aturan untuk memblokir, memberi label, dan mengelola permintaan yang mungkin merupakan bagian dari upaya pengambilalihan akun berbahaya. APIs Memungkinkan verifikasi klien yang disetel dengan baik dan agregasi perilaku yang digunakan aturan ATP untuk memisahkan lalu lintas klien yang valid dari lalu lintas berbahaya.

  Untuk informasi selengkapnya, lihat [AWS WAF Kelompok aturan pencegahan pengambilalihan akun Kontrol Penipuan (ATP)](aws-managed-rule-groups-atp.md) dan [AWS WAF Pencegahan pengambilalihan akun Kontrol Penipuan (ATP)](waf-atp.md).
+ Tingkat perlindungan yang ditargetkan dari grup aturan terkelola Kontrol AWS WAF Bot`AWSManagedRulesBotControlRuleSet`. 

  Bot berjalan dari yang mengidentifikasi diri dan berguna, seperti kebanyakan mesin pencari dan crawler, hingga bot jahat yang beroperasi melawan situs web Anda dan tidak mengidentifikasi diri. Grup aturan terkelola Bot Control menyediakan aturan untuk memantau, memberi label, dan mengelola aktivitas bot di lalu lintas web Anda. Saat Anda menggunakan tingkat perlindungan yang ditargetkan dari grup aturan ini, aturan yang ditargetkan menggunakan informasi sesi klien yang APIs disediakan untuk mendeteksi bot berbahaya dengan lebih baik. 

  Untuk informasi selengkapnya, lihat [AWS WAF Grup aturan Bot Control](aws-managed-rule-groups-bot.md) dan [AWS WAF Kontrol Bot](waf-bot-control.md).

Untuk menambahkan salah satu grup aturan terkelola ini ke paket perlindungan Anda (web ACL), lihat prosedurnya [Menambahkan grup aturan terkelola ACFP ke ACL web Anda](waf-acfp-rg-using.md)[Menambahkan grup aturan terkelola ATP ke paket perlindungan Anda (web ACL)](waf-atp-rg-using.md), dan[Menambahkan grup aturan terkelola AWS WAF Bot Control ke ACL web Anda](waf-bot-control-rg-using.md).

**catatan**  
Grup aturan terkelola saat ini tidak memblokir permintaan yang tidak memiliki token. Untuk memblokir permintaan yang tidak memiliki token, setelah Anda menerapkan integrasi aplikasi APIs, ikuti panduan di[Memblokir permintaan yang tidak memiliki AWS WAF token yang valid](waf-tokens-block-missing-tokens.md). 

# Mengakses integrasi aplikasi AWS WAF klien APIs
<a name="waf-application-integration-location-in-console"></a>

Bagian ini menjelaskan di mana menemukan integrasi aplikasi APIs di AWS WAF konsol.

 JavaScript Integrasi APIs umumnya tersedia, dan Anda dapat menggunakannya untuk browser Anda dan perangkat lain yang mengeksekusi JavaScript. 

AWS WAF menawarkan integrasi ancaman cerdas khusus SDKs untuk aplikasi seluler Android dan iOS. 
+ Untuk aplikasi seluler dan TV Android, SDKs berfungsi untuk Android API versi 23 (Android versi 6) dan yang lebih baru. Untuk informasi tentang versi Android, lihat [catatan rilis SDK Platform](https://developer.android.com/tools/releases/platforms).
+ Untuk aplikasi seluler iOS, SDKs berfungsi untuk iOS versi 13 dan yang lebih baru. Untuk informasi tentang versi iOS, lihat Catatan [Rilis iOS & iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Untuk aplikasi Apple TV, SDKs berfungsi untuk tvOS versi 14 atau yang lebih baru. Untuk informasi tentang versi tvOS, lihat Catatan Rilis [tvOS](https://developer.apple.com/documentation/tvos-release-notes).

**Untuk mengakses integrasi APIs melalui konsol**

1. Masuk ke Konsol Manajemen AWS dan buka AWS WAF konsol di [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Pilih **Integrasi aplikasi** di panel navigasi, lalu pilih tab yang Anda minati.
   + **Integrasi ancaman cerdas** tersedia untuk JavaScript dan aplikasi seluler. 

     Tab berisi yang berikut:
     + Daftar paket perlindungan (web ACLs) yang diaktifkan untuk integrasi aplikasi ancaman cerdas. Daftar ini mencakup setiap paket perlindungan (web ACL) yang menggunakan grup aturan `AWSManagedRulesACFPRuleSet` terkelola, grup aturan `AWSManagedRulesATPRuleSet` terkelola, atau tingkat perlindungan yang ditargetkan dari grup aturan `AWSManagedRulesBotControlRuleSet` terkelola. Saat Anda menerapkan ancaman cerdas APIs, Anda menggunakan URL integrasi untuk paket perlindungan (web ACL) yang ingin Anda integrasikan.
     +  APIs Yang Anda memiliki akses ke. Itu JavaScript APIs selalu tersedia. Untuk akses ke ponsel SDKs, hubungi dukungan di [Kontak AWS](https://aws.amazon.com/contact-us).
   + **Integrasi CAPTCHA** tersedia untuk JavaScript aplikasi. 

     Tab berisi yang berikut: 
     + URL integrasi untuk digunakan dalam integrasi Anda. 
     + Kunci API yang telah Anda buat untuk domain aplikasi klien Anda. Penggunaan CAPTCHA API Anda memerlukan kunci API terenkripsi yang memberi klien hak untuk mengakses AWS WAF CAPTCHA dari domain mereka. Untuk setiap klien yang Anda integrasikan, gunakan kunci API yang berisi domain klien. Untuk informasi selengkapnya persyaratan ini dan tentang mengelola kunci ini, lihat[Mengelola kunci API untuk JS CAPTCHA API](waf-js-captcha-api-key.md).

# AWS WAF JavaScript integrasi
<a name="waf-javascript-api"></a>

Bagian ini menjelaskan cara menggunakan AWS WAF JavaScript integrasi.

Anda dapat menggunakan JavaScript integrasi APIs untuk mengimplementasikan integrasi AWS WAF aplikasi di browser Anda dan perangkat lain yang mengeksekusi JavaScript. 

Teka-teki CAPTCHA dan tantangan diam hanya dapat berjalan ketika browser mengakses titik akhir HTTPS. Klien browser harus berjalan dalam konteks aman untuk mendapatkan token. 
+ Ancaman cerdas APIs memungkinkan Anda mengelola otorisasi token melalui tantangan browser sisi klien yang diam, dan memasukkan token dalam permintaan yang Anda kirim ke sumber daya yang dilindungi. 
+ API integrasi CAPTCHA menambah ancaman cerdas APIs, dan memungkinkan Anda menyesuaikan penempatan dan karakteristik teka-teki CAPTCHA dalam aplikasi klien Anda. API ini memanfaatkan ancaman cerdas APIs untuk memperoleh AWS WAF token untuk digunakan di halaman setelah pengguna akhir berhasil menyelesaikan teka-teki CAPTCHA. 

Dengan menggunakan integrasi ini, Anda memastikan bahwa panggilan prosedur jarak jauh oleh klien Anda berisi token yang valid. Ketika integrasi ini APIs diterapkan pada halaman aplikasi Anda, Anda dapat menerapkan aturan mitigasi dalam paket perlindungan Anda (web ACL), seperti memblokir permintaan yang tidak berisi token yang valid. Anda juga dapat menerapkan aturan yang memberlakukan penggunaan token yang diperoleh aplikasi klien Anda, dengan menggunakan Challenge atau CAPTCHA tindakan dalam aturan Anda. 

**Contoh implementasi ancaman cerdas APIs**  
Daftar berikut menunjukkan komponen dasar dari implementasi tipikal ancaman cerdas APIs di halaman aplikasi 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>
```

**Contoh implementasi JavaScript CAPTCHA API**  
API integrasi CAPTCHA memungkinkan Anda menyesuaikan pengalaman teka-teki CAPTCHA pengguna akhir Anda. Integrasi CAPTCHA memanfaatkan integrasi ancaman JavaScript cerdas, untuk verifikasi browser dan manajemen token, dan menambahkan fungsi untuk mengonfigurasi dan merender teka-teki CAPTCHA. 

Daftar berikut menunjukkan komponen dasar implementasi khas CAPTCHA JavaScript API di halaman aplikasi 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**
+ [Menyediakan domain untuk digunakan dalam token](waf-js-challenge-api-set-token-domain.md)
+ [Menggunakan JavaScript API dengan kebijakan keamanan konten](waf-javascript-api-csp.md)
+ [Menggunakan JavaScript API ancaman cerdas](waf-js-challenge-api.md)
+ [Menggunakan JavaScript CAPTCHA API](waf-js-captcha-api.md)

# Menyediakan domain untuk digunakan dalam token
<a name="waf-js-challenge-api-set-token-domain"></a>

Bagian ini menjelaskan cara menyediakan domain tambahan untuk token.

Secara default, saat AWS WAF membuat token, ia menggunakan domain host dari sumber daya yang terkait dengan paket perlindungan (web ACL). Anda dapat memberikan domain tambahan untuk token yang AWS WAF dibuat untuk. JavaScript APIs Untuk melakukan ini, konfigurasikan variabel global`window.awsWafCookieDomainList`, dengan satu atau lebih domain token. 

Saat AWS WAF membuat token, ia menggunakan domain terpendek yang paling tepat dari antara kombinasi domain di `window.awsWafCookieDomainList` dan domain host dari sumber daya yang terkait dengan paket perlindungan (web ACL). 

Contoh pengaturan: 

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

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

Anda tidak dapat menggunakan sufiks publik dalam daftar ini. Misalnya, Anda tidak dapat menggunakan `gov.au` atau `co.uk` sebagai domain token dalam daftar.

Domain yang Anda tentukan dalam daftar ini harus kompatibel dengan domain dan konfigurasi domain Anda yang lain: 
+ Domain haruslah yang AWS WAF akan menerima, berdasarkan domain host yang dilindungi dan daftar domain token yang dikonfigurasi untuk paket perlindungan (web ACL). Untuk informasi selengkapnya, lihat [AWS WAF paket perlindungan (web ACL) konfigurasi daftar domain token](waf-tokens-domains.md#waf-tokens-domain-lists). 
+ Jika Anda menggunakan JavaScript CAPTCHA API, setidaknya satu domain di kunci API CAPTCHA Anda harus sama persis dengan salah satu domain token di dalamnya `window.awsWafCookieDomainList` atau harus domain puncak dari salah satu domain token tersebut. 

  Misalnya, untuk domain token`mySubdomain.myApex.com`, kunci `mySubdomain.myApex.com` API sama persis dan kunci API `myApex.com` adalah domain apex. Salah satu kunci cocok dengan domain token. 

  Untuk informasi selengkapnya tentang kunci API, lihat[Mengelola kunci API untuk JS CAPTCHA API](waf-js-captcha-api-key.md). 

Jika Anda menggunakan grup aturan `AWSManagedRulesACFPRuleSet` terkelola, Anda dapat mengonfigurasi domain yang cocok dengan domain di jalur pembuatan akun yang Anda berikan ke konfigurasi grup aturan. Untuk informasi selengkapnya tentang konfigurasi ini, silakan lihat [Menambahkan grup aturan terkelola ACFP ke ACL web Anda](waf-acfp-rg-using.md).

Jika Anda menggunakan grup aturan `AWSManagedRulesATPRuleSet` terkelola, Anda dapat mengonfigurasi domain yang cocok dengan domain di jalur masuk yang Anda berikan ke konfigurasi grup aturan. Untuk informasi selengkapnya tentang konfigurasi ini, silakan lihat [Menambahkan grup aturan terkelola ATP ke paket perlindungan Anda (web ACL)](waf-atp-rg-using.md).

# Menggunakan JavaScript API dengan kebijakan keamanan konten
<a name="waf-javascript-api-csp"></a>

Bagian ini memberikan contoh konfigurasi untuk mengizinkan daftar domain AWS WAF apex.

Jika Anda menerapkan kebijakan keamanan konten (CSP) ke sumber daya Anda, agar JavaScript implementasi Anda berfungsi, Anda perlu mengizinkan daftar domain AWS WAF apex. `awswaf.com` JavaScript SDKs Melakukan panggilan ke AWS WAF titik akhir yang berbeda, jadi izinkan daftar domain ini memberikan izin yang SDKs perlu dioperasikan.

Berikut ini menunjukkan contoh konfigurasi untuk mengizinkan domain AWS WAF apex: 

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

Jika Anda mencoba menggunakan sumber daya JavaScript SDKs dengan yang menggunakan CSP, dan Anda belum mengizinkan daftar AWS WAF domain, Anda akan menerima kesalahan seperti berikut: 

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

# Menggunakan JavaScript API ancaman cerdas
<a name="waf-js-challenge-api"></a>

Bagian ini memberikan instruksi untuk menggunakan JavaScript API ancaman cerdas dalam aplikasi klien Anda.

Ancaman cerdas APIs menyediakan operasi untuk menjalankan tantangan diam terhadap browser pengguna, dan untuk menangani AWS WAF token yang memberikan bukti tantangan yang berhasil dan respons CAPTCHA. 

Terapkan JavaScript integrasi terlebih dahulu di lingkungan pengujian, kemudian dalam produksi. Untuk panduan pengkodean tambahan, lihat bagian berikut. 

 

**Menggunakan Ancaman Cerdas APIs**

1. **Instal APIs** 

   Jika Anda menggunakan CAPTCHA API, Anda dapat melewati langkah ini. Saat Anda menginstal CAPTCHA API, skrip secara otomatis menginstal ancaman cerdas. APIs

   1. Masuk ke Konsol Manajemen AWS dan buka AWS WAF konsol di [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. Di panel navigasi, pilih **Integrasi aplikasi**. Pada halaman **Integrasi aplikasi**, Anda dapat melihat opsi tab. 

   1. Pilih **Integrasi ancaman cerdas**

   1. Di tab, pilih paket perlindungan (web ACL) yang ingin Anda integrasikan. Daftar paket perlindungan (web ACL) hanya mencakup paket perlindungan (web ACLs) yang menggunakan grup aturan `AWSManagedRulesACFPRuleSet` terkelola, grup aturan `AWSManagedRulesATPRuleSet` terkelola, atau tingkat perlindungan yang ditargetkan dari grup aturan `AWSManagedRulesBotControlRuleSet` terkelola. 

   1. Buka panel **JavaScript SDK**, dan salin tag skrip untuk digunakan dalam integrasi Anda. 

   1. Dalam kode halaman aplikasi Anda, di `<head>` bagian, masukkan tag skrip yang Anda salin untuk paket perlindungan (web ACL). Inklusi ini menyebabkan aplikasi klien Anda secara otomatis mengambil token di latar belakang pada pemuatan halaman. 

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

      `<script>`Daftar ini dikonfigurasi dengan `defer` atribut, tetapi Anda dapat mengubah pengaturan `async` jika Anda menginginkan perilaku yang berbeda untuk halaman Anda. 

1. **(Opsional) Tambahkan konfigurasi domain untuk token klien** — Secara default, saat AWS WAF membuat token, ia menggunakan domain host dari sumber daya yang terkait dengan paket perlindungan (web ACL). Untuk menyediakan domain tambahan untuk JavaScript APIs, ikuti panduan di[Menyediakan domain untuk digunakan dalam token](waf-js-challenge-api-set-token-domain.md). 

1. **Kode integrasi ancaman cerdas Anda** — Tulis kode Anda untuk memastikan bahwa pengambilan token selesai sebelum klien mengirimkan permintaannya ke titik akhir yang dilindungi. Jika Anda sudah menggunakan `fetch` API untuk melakukan panggilan, Anda dapat mengganti `fetch` pembungkus AWS WAF integrasi. Jika Anda tidak menggunakan `fetch` API, Anda dapat menggunakan `getToken` operasi AWS WAF integrasi sebagai gantinya. Untuk panduan pengkodean, lihat bagian berikut. 

1. **Tambahkan verifikasi token dalam paket perlindungan Anda (web ACL)** — Tambahkan setidaknya satu aturan ke paket perlindungan Anda (web ACL) yang memeriksa token tantangan yang valid dalam permintaan web yang dikirim klien Anda. Anda dapat menggunakan grup aturan yang memeriksa dan memantau token tantangan, seperti level target grup aturan terkelola Kontrol Bot, dan Anda dapat menggunakan tindakan Challenge aturan untuk memeriksa, seperti yang dijelaskan dalam[CAPTCHAdan Challenge di AWS WAF](waf-captcha-and-challenge.md). 

   Penambahan paket perlindungan (web ACL) memverifikasi bahwa permintaan ke titik akhir yang dilindungi menyertakan token yang telah Anda peroleh dalam integrasi klien Anda. Permintaan yang menyertakan token yang valid dan belum kedaluwarsa lulus Challenge inspeksi dan tidak mengirim tantangan diam lain kepada klien Anda. 

1. **(Opsional) Blokir permintaan yang tidak memiliki token** — Jika Anda menggunakan grup aturan terkelola ACFP, grup aturan terkelola ATP, atau aturan yang ditargetkan dari grup aturan Kontrol Bot, aturan ini tidak memblokir permintaan yang tidak memiliki token. APIs Untuk memblokir permintaan yang tidak memiliki token, ikuti panduan di[Memblokir permintaan yang tidak memiliki AWS WAF token yang valid](waf-tokens-block-missing-tokens.md). 

**Topics**
+ [Spesifikasi API ancaman cerdas](waf-js-challenge-api-specification.md)
+ [Cara menggunakan `fetch` pembungkus integrasi](waf-js-challenge-api-fetch-wrapper.md)
+ [Cara menggunakan integrasi `getToken`](waf-js-challenge-api-get-token.md)

# Spesifikasi API ancaman cerdas
<a name="waf-js-challenge-api-specification"></a>

Bagian ini mencantumkan spesifikasi untuk metode dan properti mitigasi JavaScript APIs ancaman cerdas. Gunakan ini APIs untuk ancaman cerdas dan integrasi CAPTCHA.

**`AwsWafIntegration.fetch()`**  
Mengirim `fetch` permintaan HTTP ke server menggunakan implementasi AWS WAF integrasi. 

**`AwsWafIntegration.getToken()`**  
Mengambil AWS WAF token yang disimpan dan menyimpannya dalam cookie pada halaman saat ini dengan nama`aws-waf-token`, dan nilai ditetapkan ke nilai token. 

**`AwsWafIntegration.hasToken()`**  
Mengembalikan boolean yang menunjukkan apakah `aws-waf-token` cookie saat ini memegang token yang belum kedaluwarsa. 

Jika Anda juga menggunakan integrasi CAPTCHA, lihat spesifikasinya di. [Spesifikasi CAPTCHA API JavaScript](waf-js-captcha-api-specification.md)

# Cara menggunakan `fetch` pembungkus integrasi
<a name="waf-js-challenge-api-fetch-wrapper"></a>

Bagian ini memberikan instruksi untuk menggunakan `fetch` pembungkus integrasi.

Anda dapat menggunakan AWS WAF `fetch` pembungkus dengan mengubah `fetch` panggilan normal Anda ke `fetch` API di bawah `AwsWafIntegration` namespace. AWS WAF Pembungkus mendukung semua opsi yang sama dengan panggilan JavaScript `fetch` API standar dan menambahkan penanganan token untuk integrasi. Pendekatan ini umumnya merupakan cara paling sederhana untuk mengintegrasikan aplikasi Anda. 

**Sebelum implementasi pembungkus**  
Daftar contoh berikut menunjukkan kode standar sebelum menerapkan `AwsWafIntegration` `fetch` pembungkus.

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

**Setelah implementasi pembungkus**  
Daftar berikut menunjukkan kode yang sama dengan implementasi `AwsWafIntegration` `fetch` wrapper.

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

# Cara menggunakan integrasi `getToken`
<a name="waf-js-challenge-api-get-token"></a>

Bagian ini menjelaskan cara menggunakan `getToken` operasi.

AWS WAF mengharuskan permintaan Anda ke titik akhir yang dilindungi untuk menyertakan cookie yang diberi nama `aws-waf-token` dengan nilai token Anda saat ini. 

`getToken`Operasi ini adalah panggilan API asinkron yang mengambil AWS WAF token dan menyimpannya dalam cookie pada halaman saat ini dengan nama`aws-waf-token`, dan nilai yang ditetapkan ke nilai token. Anda dapat menggunakan cookie token ini sesuai kebutuhan di halaman Anda. 

Saat Anda menelepon`getToken`, itu melakukan hal berikut: 
+ Jika token yang belum kedaluwarsa sudah tersedia, panggilan akan segera mengembalikannya.
+ Jika tidak, panggilan akan mengambil token baru dari penyedia token, menunggu hingga 2 detik hingga alur kerja akuisisi token selesai sebelum waktu habis. Jika waktu operasi habis, itu akan menimbulkan kesalahan, yang harus ditangani oleh kode panggilan Anda. 

`getToken`Operasi ini memiliki operasi yang menyertainya`hasToken`, yang menunjukkan apakah `aws-waf-token` cookie saat ini memegang token yang belum kedaluwarsa. 

`AwsWafIntegration.getToken()`mengambil token yang valid dan menyimpannya sebagai cookie. Sebagian besar panggilan klien secara otomatis melampirkan cookie ini, tetapi beberapa tidak. Misalnya, panggilan yang dilakukan di seluruh domain host tidak melampirkan cookie. Dalam detail implementasi yang mengikuti, kami menunjukkan cara bekerja dengan kedua jenis panggilan klien. 

**`getToken`Implementasi dasar, untuk panggilan yang melampirkan `aws-waf-token` cookie**  
Daftar contoh berikut menunjukkan kode standar untuk mengimplementasikan `getToken` operasi dengan permintaan 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
	}
```

**Kirim formulir hanya setelah token tersedia dari `getToken`**  
Daftar berikut menunjukkan cara mendaftarkan pendengar acara untuk mencegat kiriman formulir hingga token yang valid tersedia untuk digunakan. 

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

**Melampirkan token saat klien Anda tidak melampirkan `aws-waf-token` cookie secara default**  
`AwsWafIntegration.getToken()`mengambil token yang valid dan menyimpannya sebagai cookie, tetapi tidak semua panggilan klien melampirkan cookie ini secara default. Misalnya, panggilan yang dilakukan di seluruh domain host tidak melampirkan cookie. 

`fetch`Pembungkus menangani kasus ini secara otomatis, tetapi jika Anda tidak dapat menggunakan `fetch` pembungkus, Anda dapat menangani ini dengan menggunakan header khusus`x-aws-waf-token`. AWS WAF membaca token dari header ini, selain membacanya dari `aws-waf-token` cookie. Kode berikut menunjukkan contoh pengaturan header. 

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

Secara default, AWS WAF hanya menerima token yang berisi domain yang sama dengan domain host yang diminta. Setiap token lintas domain memerlukan entri yang sesuai dalam daftar domain token paket perlindungan (web ACL). Untuk informasi selengkapnya, lihat [AWS WAF paket perlindungan (web ACL) konfigurasi daftar domain token](waf-tokens-domains.md#waf-tokens-domain-lists). 

Untuk informasi tambahan tentang penggunaan token lintas domain, lihat [aws-waf-bot-controlaws-samples/](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha) -. api-protection-with-captcha

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

Bagian ini memberikan instruksi untuk menggunakan API integrasi CAPTCHA.

CAPTCHA JavaScript API memungkinkan Anda untuk mengkonfigurasi teka-teki CAPTCHA dan menempatkannya di tempat yang Anda inginkan dalam aplikasi klien Anda. API ini memanfaatkan fitur ancaman cerdas JavaScript APIs untuk memperoleh dan menggunakan AWS WAF token setelah pengguna akhir berhasil menyelesaikan teka-teki CAPTCHA. 

Terapkan JavaScript integrasi terlebih dahulu di lingkungan pengujian, kemudian dalam produksi. Untuk panduan pengkodean tambahan, lihat bagian berikut. 

**Untuk menggunakan API integrasi CAPTCHA**

1. **Instal API**

   1. Masuk ke Konsol Manajemen AWS dan buka AWS WAF konsol di [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. Di panel navigasi, pilih **Integrasi aplikasi**. Pada halaman **Integrasi aplikasi**, Anda dapat melihat opsi tab. 

   1. Pilih integrasi **CAPTCHA**.

   1. Salin tag skrip JavaScript integrasi yang terdaftar untuk digunakan dalam integrasi Anda.

   1. Dalam kode halaman aplikasi Anda, di `<head>` bagian, masukkan tag skrip yang Anda salin. Inklusi ini membuat teka-teki CAPTCHA tersedia untuk konfigurasi dan penggunaan. 

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

      `<script>`Daftar ini dikonfigurasi dengan `defer` atribut, tetapi Anda dapat mengubah pengaturan `async` jika Anda menginginkan perilaku yang berbeda untuk halaman Anda. 

      Skrip CAPTCHA juga secara otomatis memuat skrip integrasi ancaman cerdas jika belum ada. Skrip integrasi ancaman cerdas menyebabkan aplikasi klien Anda secara otomatis mengambil token di latar belakang pada pemuatan halaman, dan menyediakan fungsionalitas manajemen token lain yang Anda butuhkan untuk penggunaan CAPTCHA API. 

1. **(Opsional) Tambahkan konfigurasi domain untuk token klien** — Secara default, saat AWS WAF membuat token, ia menggunakan domain host dari sumber daya yang terkait dengan paket perlindungan (web ACL). Untuk menyediakan domain tambahan untuk JavaScript APIs, ikuti panduan di[Menyediakan domain untuk digunakan dalam token](waf-js-challenge-api-set-token-domain.md). 

1. **Dapatkan kunci API terenkripsi untuk klien** — CAPTCHA API memerlukan kunci API terenkripsi yang berisi daftar domain klien yang valid. AWS WAF menggunakan kunci ini untuk memverifikasi bahwa domain klien yang Anda gunakan dengan integrasi disetujui untuk menggunakan AWS WAF CAPTCHA. Untuk membuat kunci API Anda, ikuti panduan di[Mengelola kunci API untuk JS CAPTCHA API](waf-js-captcha-api-key.md).

1. **Kode implementasi widget CAPTCHA Anda** - Terapkan panggilan `renderCaptcha()` API di halaman Anda, di lokasi di mana Anda ingin menggunakannya. Untuk informasi tentang mengkonfigurasi dan menggunakan fungsi ini, lihat bagian berikut, [Spesifikasi CAPTCHA API JavaScript](waf-js-captcha-api-specification.md) dan[Cara membuat teka-teki CAPTCHA](waf-js-captcha-api-render.md). 

   Implementasi CAPTCHA terintegrasi dengan integrasi ancaman cerdas APIs untuk manajemen token dan menjalankan panggilan pengambilan yang menggunakan token. AWS WAF Untuk panduan tentang menggunakan ini APIs, lihat[Menggunakan JavaScript API ancaman cerdas](waf-js-challenge-api.md).

1. **Tambahkan verifikasi token dalam paket perlindungan Anda (web ACL)** — Tambahkan setidaknya satu aturan ke paket perlindungan Anda (web ACL) yang memeriksa token CAPTCHA yang valid dalam permintaan web yang dikirim klien Anda. Anda dapat menggunakan tindakan CAPTCHA aturan untuk memeriksa, seperti yang dijelaskan dalam[CAPTCHAdan Challenge di AWS WAF](waf-captcha-and-challenge.md). 

   Penambahan paket perlindungan (web ACL) memverifikasi bahwa permintaan yang masuk ke titik akhir yang dilindungi menyertakan token yang telah Anda peroleh dalam integrasi klien Anda. Permintaan yang menyertakan token CAPTCHA yang valid dan belum kedaluwarsa lulus inspeksi tindakan CAPTCHA aturan dan tidak menghadirkan teka-teki CAPTCHA lain kepada pengguna akhir Anda. 

Setelah menerapkan JavaScript API, Anda dapat meninjau CloudWatch metrik untuk upaya dan solusi teka-teki CAPTCHA. Untuk detail metrik dan dimensi, lihat[Metrik dan dimensi akun](waf-metrics.md#waf-metrics-account).

**Topics**
+ [Spesifikasi CAPTCHA API JavaScript](waf-js-captcha-api-specification.md)
+ [Cara membuat teka-teki CAPTCHA](waf-js-captcha-api-render.md)
+ [Menangani respons CAPTCHA dari AWS WAF](waf-js-captcha-api-conditional.md)
+ [Mengelola kunci API untuk JS CAPTCHA API](waf-js-captcha-api-key.md)

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

Bagian ini mencantumkan spesifikasi untuk metode dan properti JavaScript APIs CAPTCHA. Gunakan CAPTCHA JavaScript APIs untuk menjalankan teka-teki CAPTCHA khusus di aplikasi klien Anda. 

API ini dibangun di atas ancaman cerdas APIs, yang Anda gunakan untuk mengonfigurasi dan mengelola akuisisi dan penggunaan AWS WAF token. Lihat[Spesifikasi API ancaman cerdas](waf-js-challenge-api-specification.md).

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
Menyajikan teka-teki AWS WAF CAPTCHA kepada pengguna akhir dan, setelah berhasil, memperbarui token klien dengan validasi CAPTCHA. Ini hanya tersedia dengan integrasi CAPTCHA. Gunakan panggilan ini bersama dengan ancaman cerdas APIs untuk mengelola pengambilan token dan untuk memberikan token dalam `fetch` panggilan Anda. Lihat ancaman cerdas APIs di[Spesifikasi API ancaman cerdas](waf-js-challenge-api-specification.md).  
Berbeda dengan pengantara CAPTCHA yang AWS WAF mengirim, teka-teki CAPTCHA yang diberikan oleh metode ini menampilkan teka-teki segera, tanpa layar judul awal.     
**`container`**  
`Element`Objek untuk elemen kontainer target pada halaman. Ini biasanya diambil dengan menelepon `document.getElementById()` atau`document.querySelector()`.  
Wajib: Ya  
Tipe: `Element`  
**konfigurasi**  
Objek yang berisi pengaturan konfigurasi CAPTCHA, sebagai berikut: ****    
**`apiKey`**   
Kunci API terenkripsi yang memungkinkan izin untuk domain klien. Gunakan AWS WAF konsol untuk membuat kunci API Anda untuk domain klien Anda. Anda dapat menggunakan satu kunci hingga lima domain. Untuk informasi, lihat [Mengelola kunci API untuk JS CAPTCHA API](waf-js-captcha-api-key.md).   
Wajib: Ya  
Tipe: `string`  
**`onSuccess: (wafToken: string) => void;`**   
Dipanggil dengan AWS WAF token yang valid ketika pengguna akhir berhasil menyelesaikan teka-teki CAPTCHA. Gunakan token dalam permintaan yang Anda kirim ke titik akhir yang Anda lindungi dengan paket AWS WAF perlindungan (web ACL). Token memberikan bukti dan stempel waktu penyelesaian teka-teki terbaru yang berhasil.   
Wajib: Ya  
**`onError?: (error: CaptchaError) => void;`**   
Dipanggil dengan objek kesalahan ketika terjadi kesalahan selama operasi CAPTCHA.   
Wajib: Tidak  
**`CaptchaError`definisi kelas** - `onError` Handler menyediakan jenis kesalahan dengan definisi kelas berikut.   

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind`— Jenis kesalahan yang dikembalikan. 
+ `statusCode`— Kode status HTTP, jika tersedia. Ini digunakan oleh `network_error` jika kesalahan disebabkan oleh kesalahan HTTP.  
**`onLoad?: () => void;`**   
Dipanggil ketika teka-teki CAPTCHA baru dimuat.  
Wajib: Tidak  
**`onPuzzleTimeout?: () => void;`**   
Dipanggil ketika teka-teki CAPTCHA tidak selesai sebelum kedaluwarsa.  
Wajib: Tidak  
**`onPuzzleCorrect?: () => void;`**   
Dipanggil ketika jawaban yang benar diberikan untuk teka-teki CAPTCHA.  
Wajib: Tidak  
**`onPuzzleIncorrect?: () => void;`**   
Dipanggil ketika jawaban yang salah diberikan untuk teka-teki CAPTCHA.  
Wajib: Tidak  
**`defaultLocale`**   
Lokal default yang digunakan untuk teka-teki CAPTCHA. Instruksi tertulis untuk teka-teki CAPTCHA tersedia dalam bahasa Arab (ar-sa), bahasa Mandarin sederhana (Zh-CN), Belanda (nl-NL), Inggris (en-US), Prancis (fr-Fr), Jerman (de-DE), Italia (IT-it), Jepang (Ja-jp), Portugis Brasil (Pt-BR), Spanyol (es-ES), dan Turki (Tr-tr). Instruksi audio tersedia untuk semua bahasa tertulis kecuali bahasa Mandarin dan Jepang, yang default ke bahasa Inggris. Untuk mengubah bahasa default, berikan bahasa internasional dan kode lokal, misalnya,`ar-SA`.  
Default: Bahasa yang saat ini digunakan di browser pengguna akhir  
Wajib: Tidak  
Tipe: `string`  
**`disableLanguageSelector`**   
Jika diatur ke`true`, teka-teki CAPTCHA menyembunyikan pemilih bahasa.   
Default: `false`  
Wajib: Tidak  
Tipe: `boolean`  
**`dynamicWidth`**   
Jika diatur ke`true`, teka-teki CAPTCHA mengubah lebar untuk kompatibilitas dengan lebar jendela browser.   
Default: `false`  
Wajib: Tidak  
Tipe: `boolean`  
**`skipTitle`**   
Jika diatur ke`true`, teka-teki CAPTCHA tidak menampilkan judul puzzle **Pecahkan teka-teki.**   
Default: `false`  
Wajib: Tidak  
Tipe: `boolean`

# Cara membuat teka-teki CAPTCHA
<a name="waf-js-captcha-api-render"></a>

Bagian ini memberikan contoh `renderCaptcha` implementasi.

Anda dapat menggunakan AWS WAF `renderCaptcha` panggilan di mana Anda ingin di antarmuka klien Anda. Panggilan mengambil teka-teki CAPTCHA dari AWS WAF, merendernya, dan mengirimkan hasilnya untuk verifikasi. AWS WAF Saat Anda melakukan panggilan, Anda menyediakan konfigurasi rendering teka-teki dan panggilan balik yang ingin Anda jalankan saat pengguna akhir menyelesaikan teka-teki. Untuk detail tentang opsi, lihat bagian sebelumnya,. [Spesifikasi CAPTCHA API JavaScript](waf-js-captcha-api-specification.md)

Gunakan panggilan ini bersama dengan fungsionalitas manajemen token dari integrasi APIs ancaman cerdas. Panggilan ini memberi klien Anda token yang memverifikasi keberhasilan penyelesaian teka-teki CAPTCHA. Gunakan integrasi ancaman cerdas APIs untuk mengelola token dan untuk menyediakan token dalam panggilan klien Anda ke titik akhir yang dilindungi dengan paket AWS WAF perlindungan (web ACLs). Untuk informasi tentang ancaman cerdas APIs, lihat[Menggunakan JavaScript API ancaman cerdas](waf-js-challenge-api.md).

**Contoh implementasi**  
Daftar contoh berikut menunjukkan implementasi CAPTCHA standar, termasuk penempatan URL AWS WAF integrasi di bagian`<head>`. 

Daftar ini mengonfigurasi `renderCaptcha` fungsi dengan callback sukses yang menggunakan `AwsWafIntegration.fetch` pembungkus integrasi ancaman cerdas. APIs Untuk informasi tentang fungsi ini, lihat[Cara menggunakan `fetch` pembungkus integrasi](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>
```

**Contoh pengaturan konfigurasi**  
Contoh daftar berikut menunjukkan `renderCaptcha` dengan pengaturan non-default untuk lebar dan pilihan judul. 

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

Untuk informasi selengkapnya tentang opsi konfigurasi, lihat[Spesifikasi CAPTCHA API JavaScript](waf-js-captcha-api-specification.md).

# Menangani respons CAPTCHA dari AWS WAF
<a name="waf-js-captcha-api-conditional"></a>

Bagian ini memberikan contoh penanganan respons CAPTCHA.

 AWS WAF Aturan dengan CAPTCHA tindakan menghentikan evaluasi permintaan web yang cocok jika permintaan tidak memiliki token dengan stempel waktu CAPTCHA yang valid. Jika permintaan adalah `GET` text/html panggilan, CAPTCHA tindakan kemudian melayani klien pengantara dengan teka-teki CAPTCHA. Ketika Anda tidak mengintegrasikan CAPTCHA JavaScript API, pengantara menjalankan teka-teki dan, jika pengguna akhir berhasil menyelesaikannya, secara otomatis mengirimkan kembali permintaan. 

Saat Anda mengintegrasikan CAPTCHA JavaScript API dan menyesuaikan penanganan CAPTCHA Anda, Anda perlu mendeteksi respons CAPTCHA yang mengakhiri, menyajikan CAPTCHA kustom Anda, dan kemudian jika pengguna akhir berhasil memecahkan teka-teki, kirimkan kembali permintaan web klien. 

Contoh kode berikut ini menunjukkan cara untuk melakukannya. 

**catatan**  
Respons AWS WAF CAPTCHA tindakan memiliki kode status HTTP 405, yang kami gunakan untuk mengenali CAPTCHA respons dalam kode ini. Jika titik akhir Anda yang dilindungi menggunakan kode status HTTP 405 untuk mengkomunikasikan jenis respons lain untuk panggilan yang sama, kode contoh ini akan membuat teka-teki CAPTCHA untuk tanggapan tersebut juga. 

```
<!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>
```

# Mengelola kunci API untuk JS CAPTCHA API
<a name="waf-js-captcha-api-key"></a>

Bagian ini memberikan petunjuk untuk membuat dan menghapus kunci API.

Untuk mengintegrasikan AWS WAF CAPTCHA ke dalam aplikasi klien dengan JavaScript API, Anda memerlukan tag integrasi JavaScript API dan kunci API terenkripsi untuk domain klien tempat Anda ingin menjalankan teka-teki CAPTCHA Anda. 

Integrasi aplikasi CAPTCHA untuk JavaScript menggunakan kunci API terenkripsi untuk memverifikasi bahwa domain aplikasi klien memiliki izin untuk menggunakan CAPTCHA API. AWS WAF Ketika Anda memanggil CAPTCHA API dari JavaScript klien Anda, Anda menyediakan kunci API dengan daftar domain yang menyertakan domain untuk klien saat ini. Anda dapat mencantumkan hingga 5 domain dalam satu kunci terenkripsi. 

**Persyaratan kunci API**  
Kunci API yang Anda gunakan dalam integrasi CAPTCHA harus berisi domain yang berlaku untuk klien tempat Anda menggunakan kunci tersebut. 
+ Jika Anda menentukan a `window.awsWafCookieDomainList` dalam integrasi ancaman cerdas klien Anda, maka setidaknya satu domain dalam kunci API Anda harus sama persis dengan salah satu domain token di dalamnya `window.awsWafCookieDomainList` atau domain tersebut harus menjadi domain puncak dari salah satu domain token tersebut. 

  Misalnya, untuk domain token`mySubdomain.myApex.com`, kunci `mySubdomain.myApex.com` API sama persis dan kunci API `myApex.com` adalah domain apex. Salah satu kunci cocok dengan domain token. 

  Untuk informasi tentang pengaturan daftar domain token, lihat[Menyediakan domain untuk digunakan dalam token](waf-js-challenge-api-set-token-domain.md).
+ Jika tidak, domain saat ini harus terkandung dalam kunci API. Domain saat ini adalah domain yang dapat Anda lihat di bilah alamat browser. 

Domain yang Anda gunakan haruslah yang AWS WAF akan menerima, berdasarkan domain host yang dilindungi dan daftar domain token yang dikonfigurasi untuk ACL web. Untuk informasi selengkapnya, lihat [AWS WAF paket perlindungan (web ACL) konfigurasi daftar domain token](waf-tokens-domains.md#waf-tokens-domain-lists).

**Cara memilih Region untuk kunci API Anda**  
AWS WAF dapat menghasilkan kunci API CAPTCHA di Wilayah mana pun yang AWS WAF tersedia. 

Sebagai aturan umum, Anda harus menggunakan Region yang sama untuk kunci API CAPTCHA Anda seperti yang Anda gunakan untuk paket perlindungan Anda (web ACL). Namun, jika Anda mengharapkan audiens global untuk paket perlindungan regional (web ACL), Anda dapat memperoleh tag JavaScript integrasi CAPTCHA yang dicakup CloudFront dan kunci API yang dicakup CloudFront, dan menggunakannya dengan paket perlindungan regional (web ACL). Pendekatan ini memungkinkan klien memuat teka-teki CAPTCHA dari Wilayah yang paling dekat dengan mereka, yang mengurangi latensi. 

Kunci API CAPTCHA yang dicakup ke Wilayah selain tidak didukung untuk digunakan CloudFront di beberapa Wilayah. Mereka hanya dapat digunakan di Wilayah yang mereka cakupkan. 

**Untuk menghasilkan kunci API untuk domain klien Anda**  
Untuk mendapatkan URL integrasi dan menghasilkan serta mengambil kunci API melalui konsol. 

1. Masuk ke Konsol Manajemen AWS dan buka AWS WAF konsol di [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Di panel navigasi, pilih **Integrasi aplikasi**. 

1. Di panel, **paket perlindungan (web ACLs) yang diaktifkan untuk integrasi aplikasi**, pilih Wilayah yang ingin Anda gunakan untuk kunci API Anda. Anda juga dapat memilih Wilayah di panel **kunci API** pada tab integrasi **CAPTCHA**.

1. Pilih tab Integrasi **CAPTCHA**. Tab ini menyediakan tag JavaScript integrasi CAPTCHA, yang dapat Anda gunakan dalam integrasi Anda, dan daftar kunci API. Keduanya tercakup ke Wilayah yang dipilih.

1. Di panel **kunci API**, pilih **Generate key**. Dialog generasi kunci muncul. 

1. Masukkan domain klien yang ingin Anda sertakan dalam kunci. Anda dapat memasukkan hingga 5. Setelah selesai, pilih **Generate key**. Antarmuka kembali ke tab integrasi CAPTCHA, di mana kunci baru Anda terdaftar. 

   Setelah dibuat, kunci API tidak dapat diubah. Jika Anda perlu membuat perubahan pada kunci, buat kunci baru dan gunakan itu sebagai gantinya. 

1. (Opsional) Salin kunci yang baru dibuat untuk digunakan dalam integrasi Anda. 

Anda juga dapat menggunakan REST APIs atau salah satu bahasa khusus AWS SDKs untuk pekerjaan ini. Panggilan REST API adalah [Create APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) and [List APIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html). 

**Untuk menghapus kunci API**  
Untuk menghapus kunci API, Anda harus menggunakan REST API atau salah satu bahasa khusus AWS SDKs. Panggilan REST API adalah [Delete APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html). Anda tidak dapat menggunakan konsol untuk menghapus kunci. 

Setelah Anda menghapus kunci, diperlukan waktu hingga 24 jam AWS WAF untuk melarang penggunaan kunci di semua wilayah. 

# AWS WAF integrasi aplikasi seluler
<a name="waf-mobile-sdk"></a>

Bagian ini memperkenalkan topik penggunaan AWS WAF ponsel SDKs untuk menerapkan integrasi ancaman AWS WAF cerdas SDKs untuk aplikasi seluler dan TV Android dan iOS. Untuk aplikasi TV, ini SDKs kompatibel dengan platform TV pintar utama, termasuk Android TV dan Apple TV.
+ Untuk aplikasi seluler dan TV Android, SDKs berfungsi untuk Android API versi 23 (Android versi 6) dan yang lebih baru. Untuk informasi tentang versi Android, lihat [catatan rilis SDK Platform](https://developer.android.com/tools/releases/platforms).
+ Untuk aplikasi seluler iOS, SDKs berfungsi untuk iOS versi 13 dan yang lebih baru. Untuk informasi tentang versi iOS, lihat Catatan [Rilis iOS & iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Untuk aplikasi Apple TV, SDKs berfungsi untuk tvOS versi 14 atau yang lebih baru. Untuk informasi tentang versi tvOS, lihat Catatan Rilis [tvOS](https://developer.apple.com/documentation/tvos-release-notes).

Dengan AWS WAF SDK seluler, Anda dapat mengelola otorisasi token, dan menyertakan token dalam permintaan yang Anda kirim ke sumber daya yang dilindungi. Dengan menggunakan SDKs, Anda memastikan bahwa panggilan prosedur jarak jauh ini oleh klien Anda berisi token yang valid. Selain itu, ketika integrasi ini diterapkan pada halaman aplikasi Anda, Anda dapat menerapkan aturan mitigasi dalam paket perlindungan Anda (web ACL), seperti memblokir permintaan yang tidak berisi token yang valid.

Untuk akses ke ponsel SDKs, hubungi dukungan di [Kontak AWS](https://aws.amazon.com/contact-us).

**catatan**  
 AWS WAF Ponsel SDKs tidak tersedia untuk kustomisasi CAPTCHA.

Pendekatan dasar untuk menggunakan SDK adalah membuat penyedia token menggunakan objek konfigurasi, kemudian menggunakan penyedia token untuk mengambil token dari. AWS WAF Secara default, penyedia token menyertakan token yang diambil dalam permintaan web Anda ke sumber daya yang dilindungi. 

Berikut ini adalah sebagian daftar implementasi SDK, yang menunjukkan komponen utama. Untuk contoh lebih detail, lihat [Contoh kode untuk SDK AWS WAF seluler](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();
```

------

# Menginstal SDK AWS WAF seluler
<a name="waf-mobile-sdk-installing"></a>

Bagian ini memberikan instruksi untuk menginstal SDK AWS WAF seluler.

Untuk akses ke ponsel SDKs, hubungi dukungan di [Kontak AWS](https://aws.amazon.com/contact-us).

Terapkan SDK seluler terlebih dahulu di lingkungan pengujian, kemudian dalam produksi.

**Untuk menginstal SDK AWS WAF seluler**

1. Masuk ke Konsol Manajemen AWS dan buka AWS WAF konsol di [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Di panel navigasi, pilih **Integrasi aplikasi**. 

1. Di tab **Integrasi ancaman cerdas**, lakukan hal berikut: 

   1. Dalam **paket perlindungan panel (web ACLs) yang diaktifkan untuk integrasi aplikasi**, cari paket perlindungan (web ACL) yang Anda integrasikan. Salin dan simpan URL integrasi paket perlindungan (web ACL) untuk digunakan dalam implementasi Anda. Anda juga dapat memperoleh URL ini melalui panggilan API`GetWebACL`.

   1. Pilih jenis dan versi perangkat seluler, lalu pilih **Unduh**. Anda dapat memilih versi apa pun yang Anda suka, tetapi kami sarankan menggunakan versi terbaru. AWS WAF mengunduh `zip` file untuk perangkat Anda ke lokasi unduhan standar Anda.

1. Di lingkungan pengembangan aplikasi Anda, unzip file ke lokasi kerja pilihan Anda. Di direktori tingkat atas file zip, cari dan buka file. `README` Ikuti petunjuk dalam `README` file untuk menginstal SDK AWS WAF seluler untuk digunakan dalam kode aplikasi seluler Anda. 

1. Program aplikasi Anda sesuai dengan panduan di bagian berikut.

# AWS WAF spesifikasi SDK seluler
<a name="waf-mobile-sdk-specification"></a>

Bagian ini mencantumkan objek SDK, operasi, dan pengaturan konfigurasi untuk versi SDK AWS WAF seluler terbaru yang tersedia. Untuk informasi terperinci tentang cara kerja penyedia token dan operasi untuk berbagai kombinasi pengaturan konfigurasi, lihat[Cara kerja SDK AWS WAF seluler](waf-mobile-sdk-how-it-works.md). 

**`WAFToken`**  
Memegang AWS WAF token.    
**`getValue()`**  
Mengambil `String` representasi dari. `WAFToken` 

**`WAFTokenProvider`**  
Mengelola token di aplikasi seluler Anda. Menerapkan ini menggunakan `WAFConfiguration` objek.    
**`getToken()`**  
Jika penyegaran latar belakang diaktifkan, ini mengembalikan token yang di-cache. Jika penyegaran latar belakang dinonaktifkan, ini membuat panggilan pemblokiran sinkron AWS WAF untuk mengambil token baru.   
**`loadTokenIntoProvider(WAFToken)`**  
Memuat token yang ditentukan ke dalam`WAFTokenProvider`, menggantikan token apa pun yang dikelola penyedia. Penyedia token mengambil kepemilikan token baru dan menangani penyegarannya ke depan. Operasi ini juga memperbarui token di toko cookie, jika `setTokenCookie` diaktifkan di`WAFConfiguration`.  
**`onTokenReady(WAFTokenResultCallback)`**  
Menginstruksikan penyedia token untuk me-refresh token dan memanggil panggilan balik yang disediakan saat token aktif siap. Penyedia token akan memanggil panggilan balik Anda di utas latar belakang saat token di-cache dan siap. Panggil ini saat aplikasi Anda pertama kali dimuat dan juga saat kembali ke status aktif. Untuk informasi selengkapnya tentang kembali ke status aktif, lihat[Mengambil token setelah aplikasi tidak aktif](waf-mobile-sdk-how-it-works.md#waf-mobile-sdk-how-back-from-inactive).   
Untuk aplikasi Android atau iOS, Anda dapat mengatur `WAFTokenResultCallback` ke operasi yang ingin dijalankan oleh penyedia token saat token yang diminta sudah siap. Implementasi Anda `WAFTokenResultCallback` harus mengambil parameter`WAFToken`,`SdkError`. Untuk aplikasi iOS, Anda dapat membuat fungsi inline secara bergantian.   
**`storeTokenInCookieStorage(WAFToken)`**  
Menginstruksikan `WAFTokenProvider` untuk menyimpan AWS WAF token yang ditentukan ke dalam manajer cookie SDK. Secara default, token hanya ditambahkan ke toko cookie saat pertama kali diperoleh dan saat di-refresh. Jika aplikasi menghapus penyimpanan cookie bersama karena alasan apa pun, SDK tidak secara otomatis menambahkan AWS WAF token kembali hingga penyegaran berikutnya. 

**`WAFConfiguration`**  
Memegang konfigurasi untuk implementasi`WAFTokenProvider`. Saat menerapkan ini, Anda memberikan URL integrasi paket perlindungan (web ACL), nama domain yang akan digunakan dalam token, dan pengaturan non-default apa pun yang ingin digunakan oleh penyedia token.   
Daftar berikut menentukan pengaturan konfigurasi yang dapat Anda kelola dalam `WAFConfiguration` objek.    
**`applicationIntegrationUrl`**   
URL integrasi aplikasi. Dapatkan ini dari AWS WAF konsol atau melalui panggilan `getWebACL` API.  
Wajib: Ya  
Jenis: URL khusus aplikasi. Untuk iOS, lihat [URL iOS](https://developer.apple.com/documentation/foundation/url). Untuk Android, lihat URL [java.net](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html).   
**`backgroundRefreshEnabled`**   
Menunjukkan apakah Anda ingin penyedia token menyegarkan token di latar belakang. Jika Anda menyetel ini, penyedia token akan menyegarkan token Anda di latar belakang sesuai dengan pengaturan konfigurasi yang mengatur aktivitas penyegaran token otomatis.   
Wajib: Tidak  
Tipe: `Boolean`  
Nilai default: `TRUE`  
**`domainName`**   
Domain yang akan digunakan dalam token, yang digunakan dalam akuisisi token dan penyimpanan cookie. Misalnya, `example.com` atau `aws.amazon.com`. Ini biasanya domain host dari sumber daya Anda yang terkait dengan paket perlindungan (web ACL), tempat Anda akan mengirim permintaan web. Untuk grup aturan terkelola ACFP`AWSManagedRulesACFPRuleSet`, ini biasanya akan menjadi domain tunggal yang cocok dengan domain di jalur pembuatan akun yang Anda berikan dalam konfigurasi grup aturan. Untuk grup aturan terkelola ATP`AWSManagedRulesATPRuleSet`, ini biasanya akan menjadi domain tunggal yang cocok dengan domain di jalur login yang Anda berikan dalam konfigurasi grup aturan.   
Sufiks publik tidak diizinkan. Misalnya, Anda tidak dapat menggunakan `gov.au` atau `co.uk` sebagai domain token.  
Domain harus menjadi salah satu yang AWS WAF akan menerima, berdasarkan domain host yang dilindungi dan daftar domain token paket perlindungan (web ACL). Untuk informasi selengkapnya, lihat [AWS WAF paket perlindungan (web ACL) konfigurasi daftar domain token](waf-tokens-domains.md#waf-tokens-domain-lists).  
Wajib: Ya  
Tipe: `String`   
**`maxErrorTokenRefreshDelayMsec`**   
Waktu maksimum dalam milidetik untuk menunggu sebelum mengulangi penyegaran token setelah upaya gagal. Untuk setiap percobaan ulang otomatis untuk upaya yang gagal, itu akan menambahkan cadangan eksponensial hingga waktu tunda input yang diberikan. Nilai ini digunakan setelah pengambilan token gagal dan berulang kali dicoba`maxRetryCount`.   
Wajib: Tidak  
Tipe: `Integer`  
Nilai default: `5000` (5 detik)  
Nilai minimum yang diizinkan: `1` (1 milidetik)  
Nilai maksimum yang diizinkan: `30000` (30 detik)  
**`maxRetryCount`**   
Jumlah maksimum percobaan ulang untuk dilakukan dengan backoff eksponensial ketika token diminta.   
Wajib: Tidak  
Tipe: `Integer`  
Nilai default: `Infinity`  
Nilai minimum yang diizinkan: `0`  
Nilai maksimum yang diizinkan: `100`  
**`setTokenCookie`**   
Menunjukkan apakah Anda ingin pengelola cookie SDK menambahkan cookie token ke dalam permintaan dan di area lain.   
Dengan `TRUE` nilai:   
+ Manajer cookie menambahkan cookie token ke semua permintaan yang jalurnya berada di bawah jalur yang ditentukan dalam`tokenCookiePath`. 
+ `WAFTokenProvider`Operasi `loadTokenIntoProvider()` memperbarui token di toko cookie, selain memuatnya ke penyedia token.
Wajib: Tidak  
Tipe: `Boolean`  
Nilai default: `TRUE`  
**`tokenCookiePath`**   
Digunakan kapan `setTokenCookie``TRUE`. Menunjukkan jalur tingkat atas tempat Anda ingin pengelola cookie SDK menambahkan cookie token. Manajer menambahkan cookie token ke semua permintaan yang Anda kirim ke jalur ini dan ke semua jalur anak.   
Misalnya, jika Anda menyetel ini`/web/login`, maka manajer menyertakan cookie token untuk semua yang dikirim ke `/web/login` dan jalur turunannya, seperti`/web/login/help`. Itu tidak termasuk token untuk permintaan yang dikirim ke jalur lain, seperti`/`,`/web`, atau`/web/order`.   
Wajib: Tidak  
Tipe: `String`  
Nilai default: `/`  
**`tokenRefreshDelaySec`**   
Digunakan untuk penyegaran latar belakang. Jumlah waktu maksimum dalam hitungan detik antara token latar belakang menyegarkan.  
Wajib: Tidak  
Tipe: `Integer`  
Nilai default: `88`  
Nilai minimum yang diizinkan: `88`  
Nilai maksimum yang diizinkan: `300` (5 menit)

## AWS WAF kesalahan SDK seluler
<a name="waf-mobile-sdk-errors"></a>

Bagian ini mencantumkan kemungkinan kesalahan untuk versi SDK AWS WAF seluler saat ini.

**`SdkError`**  
Jenis kesalahan dikembalikan saat gagal mengambil token. SDK Android dan iOS memiliki jenis kesalahan yang sama.  
SDK AWS WAF seluler memiliki jenis kesalahan berikut:    
**`invalidChallenge`**  
Kesalahan ini dikembalikan ketika server token mengembalikan data tantangan yang tidak valid, atau gumpalan respons dimutasi oleh penyerang.  
**`errorInvokingGetChallengeEndpoint`**  
Kesalahan ini dikembalikan ketika server token mengirimkan kode respons yang tidak berhasil kembali ke klien atau ketika terjadi kesalahan jaringan.  
**`invalidVerifyChallengeResponse`**  
Kesalahan ini dikembalikan ketika ada kesalahan mengambil `aws-waf-token` dari respons verifikasi AWS WAF server, atau respons server dirusak.  
**`errorInvokingVerifyEndpoint`**  
Kesalahan ini dikembalikan ketika klien menerima respons buruk dari AWS WAF server atau kesalahan jaringan saat memverifikasi tantangan yang diselesaikan.  
**`internalError`**  
Kesalahan ini dikembalikan pada semua kesalahan lain yang mungkin terjadi dalam SDK itu sendiri.

**`socketTimeoutException`**  
Kesalahan ini sering dikembalikan saat mengalami kesalahan jaringan selama pengambilan token.  
Kesalahan ini mungkin disebabkan oleh hal-hal berikut:  
+ Bandwidth jaringan rendah: Konfirmasikan pengaturan konektivitas jaringan Anda
+ URL Integrasi Aplikasi Bermutasi: Konfirmasikan bahwa URL integrasi tidak dimodifikasi dari apa yang muncul di konsol AWS WAF 

# Cara kerja SDK AWS WAF seluler
<a name="waf-mobile-sdk-how-it-works"></a>

Bagian ini menjelaskan bagaimana kelas, properti, dan operasi SDK AWS WAF seluler bekerja sama.

Ponsel SDKs memberi Anda penyedia token yang dapat dikonfigurasi yang dapat Anda gunakan untuk pengambilan dan penggunaan token. Penyedia token memverifikasi bahwa permintaan yang Anda izinkan berasal dari pelanggan yang sah. Saat Anda mengirim permintaan ke AWS sumber daya yang Anda lindungi AWS WAF, Anda menyertakan token dalam cookie, untuk memvalidasi permintaan tersebut. Anda dapat menangani cookie token secara manual atau meminta penyedia token melakukannya untuk Anda.

Bagian ini mencakup interaksi antara kelas, properti, dan metode yang disertakan dalam SDK seluler. Untuk spesifikasi SDK, lihat[AWS WAF spesifikasi SDK seluler](waf-mobile-sdk-specification.md). 

## Pengambilan dan caching token
<a name="waf-mobile-sdk-how-token-basics"></a>

Saat membuat instance penyedia token di aplikasi seluler, Anda mengonfigurasi cara mengelola token dan pengambilan token. Pilihan utama Anda adalah cara mempertahankan token yang valid dan belum kedaluwarsa untuk digunakan dalam permintaan web aplikasi Anda:
+ **Penyegaran latar belakang diaktifkan** - Ini adalah default. Penyedia token secara otomatis menyegarkan token di latar belakang dan menyimpannya dalam cache. Dengan penyegaran latar belakang diaktifkan, saat Anda menelepon`getToken()`, operasi mengambil token yang di-cache. 

  Penyedia token melakukan penyegaran token pada interval yang dapat dikonfigurasi, sehingga token yang belum kedaluwarsa selalu tersedia di cache saat aplikasi aktif. Penyegaran latar belakang dijeda saat aplikasi Anda dalam keadaan tidak aktif. Untuk informasi tentang ini, lihat[Mengambil token setelah aplikasi tidak aktif](#waf-mobile-sdk-how-back-from-inactive).
+ **Penyegaran latar belakang dinonaktifkan** — Anda dapat menonaktifkan penyegaran token latar belakang, dan kemudian mengambil token hanya sesuai permintaan. Token yang diambil sesuai permintaan tidak di-cache, dan Anda dapat mengambil lebih dari satu jika Anda mau. Setiap token independen dari token lain yang Anda ambil, dan masing-masing memiliki stempel waktu sendiri yang digunakan untuk menghitung kedaluwarsa.

  Anda memiliki pilihan berikut untuk pengambilan token saat penyegaran latar belakang dinonaktifkan: 
  + **`getToken()`**— Saat Anda menelepon `getToken()` dengan penyegaran latar belakang dinonaktifkan, panggilan secara sinkron mengambil token baru dari. AWS WAF Ini adalah panggilan yang berpotensi memblokir yang dapat memengaruhi respons aplikasi jika Anda memanggilnya di utas utama. 
  + **`onTokenReady(WAFTokenResultCallback)`**— Panggilan ini secara asinkron mengambil token baru dan kemudian memanggil panggilan balik hasil yang disediakan di utas latar belakang saat token siap. 

### Bagaimana penyedia token mencoba kembali pengambilan token yang gagal
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

Penyedia token secara otomatis mencoba kembali pengambilan token saat pengambilan gagal. Percobaan ulang awalnya dilakukan menggunakan backoff eksponensial dengan waktu tunggu coba lagi mulai 100 ms. Untuk informasi tentang percobaan ulang eksponensial, lihat [Error retries dan](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) exponential backoff di. AWS

Ketika jumlah percobaan ulang mencapai konfigurasi`maxRetryCount`, penyedia token berhenti mencoba atau beralih ke mencoba setiap `maxErrorTokenRefreshDelayMsec` milidetik, tergantung pada jenis pengambilan token: 
+ **`onTokenReady()`**— Penyedia token beralih ke `maxErrorTokenRefreshDelayMsec` milidetik menunggu di antara upaya, dan terus mencoba mengambil token. 
+ **Penyegaran latar belakang** — Penyedia token beralih ke `maxErrorTokenRefreshDelayMsec` milidetik menunggu di antara upaya, dan terus mencoba mengambil token. 
+ **`getToken()`Panggilan sesuai permintaan, saat penyegaran latar belakang dinonaktifkan** — Penyedia token berhenti mencoba mengambil token dan mengembalikan nilai token sebelumnya, atau nilai nol jika tidak ada token sebelumnya. 

## Skenario coba lagi pengambilan token
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

Ketika penyedia token mencoba mengambil token, itu mungkin mengakibatkan percobaan ulang otomatis tergantung di mana pengambilan token gagal dalam aliran akuisisi token. Bagian ini mencantumkan kemungkinan tempat di mana Anda mungkin melihat percobaan ulang otomatis.
+ **Memperoleh atau memverifikasi AWS WAF Tantangan melalui /input atau/verifikasi:**
  + Ketika permintaan untuk mendapatkan dan memverifikasi AWS WAF tantangan dibuat dan gagal, itu dapat mengakibatkan percobaan ulang otomatis.
  + Anda mungkin mengamati percobaan ulang otomatis terjadi di sini bersama dengan `socketTimeoutException` kesalahan. Ini dapat memiliki beberapa penyebab termasuk:
    + Bandwidth jaringan rendah: Konfirmasikan pengaturan konektivitas jaringan Anda
    + URL Integrasi Aplikasi Bermutasi: Konfirmasikan bahwa URL integrasi tidak dimodifikasi dari apa yang muncul di konsol AWS WAF 
  + Hitungan coba ulang otomatis dapat dikonfigurasi dengan fungsi `maxRetryCount()`
+ **Menyegarkan token:**
  + Ketika permintaan untuk menyegarkan token dibuat melalui penangan token, itu mungkin menghasilkan percobaan ulang otomatis.
  + Hitungan coba ulang otomatis di sini dapat dikonfigurasi dengan fungsi. `maxRetryCount()`

Konfigurasi tanpa percobaan ulang otomatis dimungkinkan dengan pengaturan. `maxRetryCount(0)`

## Waktu kekebalan token dan penyegaran latar belakang
<a name="waf-mobile-sdk-how-token-immunity"></a>

Waktu kekebalan token yang Anda konfigurasikan di ACL Web tidak tergantung pada interval penyegaran token yang Anda tetapkan di SDK AWS WAF seluler. Saat Anda mengaktifkan penyegaran latar belakang, SDK akan menyegarkan token pada interval yang Anda tentukan. `tokenRefreshDelaySec()` Ini dapat menghasilkan beberapa token valid yang ada secara bersamaan, tergantung pada waktu kekebalan Anda yang dikonfigurasi.

Untuk mencegah beberapa token yang valid, Anda dapat menonaktifkan penyegaran latar belakang dan menggunakan `getToken()` fungsi untuk mengelola siklus hidup token di aplikasi seluler Anda.

## Mengambil token setelah aplikasi tidak aktif
<a name="waf-mobile-sdk-how-back-from-inactive"></a>

Penyegaran latar belakang hanya dilakukan saat aplikasi Anda dianggap aktif untuk jenis aplikasi Anda: 
+ **iOS** — Penyegaran latar belakang dilakukan saat aplikasi berada di latar depan.
+ **Android** — Penyegaran latar belakang dilakukan saat aplikasi tidak ditutup, baik itu di latar depan atau latar belakang.

Jika aplikasi Anda tetap dalam status apa pun yang tidak mendukung penyegaran latar belakang lebih lama dari `tokenRefreshDelaySec` detik yang dikonfigurasi, penyedia token akan menghentikan penyegaran latar belakang. Misalnya, untuk aplikasi iOS, jika `tokenRefreshDelaySec` 300 dan aplikasi ditutup atau masuk ke latar belakang selama lebih dari 300 detik, penyedia token berhenti menyegarkan token. Saat aplikasi kembali ke status aktif, penyedia token secara otomatis memulai ulang penyegaran latar belakang. 

Saat aplikasi Anda kembali ke status aktif, hubungi `onTokenReady()` agar Anda dapat diberi tahu saat penyedia token telah mengambil dan menyimpan token baru dalam cache. Jangan hanya menelepon`getToken()`, karena cache mungkin belum berisi token yang valid saat ini. 

## URL Integrasi Aplikasi
<a name="waf-mobile-sdk-application-integration-url"></a>

URL integrasi aplikasi SDK AWS WAF seluler menunjuk ke ACL Web yang telah Anda aktifkan untuk integrasi aplikasi. URL ini merutekan permintaan ke server backend yang benar dan mengaitkannya dengan pelanggan Anda. Ini tidak berfungsi sebagai kontrol keamanan yang keras, jadi mengekspos URL integrasi tidak menimbulkan risiko keamanan.

Anda secara teknis dapat memodifikasi URL integrasi yang disediakan dan masih mendapatkan token. Namun, kami tidak merekomendasikan ini karena Anda mungkin kehilangan visibilitas ke tingkat pemecahan tantangan atau mengalami kegagalan pengambilan token dengan `socketTimeoutException` kesalahan.

## Dependensi
<a name="waf-mobile-sdk-dependencies"></a>

Setiap SDK AWS WAF seluler yang dapat diunduh menyertakan file README yang mencantumkan dependensi untuk versi SDK spesifiknya. Lihat README untuk dependensi untuk versi SDK seluler Anda.

## Kekaburan/ (Hanya ProGuard Android SDK)
<a name="waf-mobile-sdk-obfuscation"></a>

Jika Anda menggunakan produk penyamaran atau minifikasi seperti ProGuard, Anda mungkin perlu mengecualikan ruang nama tertentu untuk memastikan SDK seluler berfungsi dengan benar. Periksa README untuk versi SDK seluler Anda untuk menemukan daftar ruang nama dan aturan pengecualian.

# Contoh kode untuk SDK AWS WAF seluler
<a name="waf-mobile-sdk-coding-examples"></a>

Bagian ini memberikan contoh kode untuk menggunakan SDK seluler. 

## Menginisialisasi penyedia token dan mendapatkan token
<a name="waf-mobile-sdk-coding-basic"></a>

Anda memulai instance penyedia token Anda menggunakan objek konfigurasi. Kemudian Anda dapat mengambil token menggunakan operasi yang tersedia. Berikut ini menunjukkan komponen dasar dari kode yang diperlukan.

------
#### [ 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 ]

Contoh 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();
```

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

------

## Mengizinkan SDK menyediakan cookie token dalam permintaan HTTP Anda
<a name="waf-mobile-sdk-coding-auto-token-cookie"></a>

Jika `setTokenCookie` ya`TRUE`, penyedia token menyertakan cookie token untuk Anda dalam permintaan web Anda ke semua lokasi di bawah jalur yang ditentukan`tokenCookiePath`. Secara default, `setTokenCookie` adalah `TRUE` dan `tokenCookiePath` adalah`/`. 

Anda dapat mempersempit cakupan permintaan yang menyertakan cookie token dengan menentukan jalur cookie token, misalnya,`/web/login`. Jika Anda melakukan ini, periksa apakah AWS WAF aturan Anda tidak memeriksa token dalam permintaan yang Anda kirim ke jalur lain. Saat Anda menggunakan grup `AWSManagedRulesACFPRuleSet` aturan, Anda mengonfigurasi jalur pendaftaran dan pembuatan akun, dan grup aturan memeriksa token dalam permintaan yang dikirim ke jalur tersebut. Untuk informasi selengkapnya, lihat [Menambahkan grup aturan terkelola ACFP ke ACL web Anda](waf-acfp-rg-using.md). Demikian pula, saat Anda menggunakan grup `AWSManagedRulesATPRuleSet` aturan, Anda mengonfigurasi jalur masuk, dan grup aturan memeriksa token dalam permintaan yang dikirim ke jalur tersebut. Untuk informasi selengkapnya, lihat [Menambahkan grup aturan terkelola ATP ke paket perlindungan Anda (web ACL)](waf-atp-rg-using.md). 

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

`setTokenCookie`Kapan`TRUE`, penyedia token menyimpan AWS WAF token dalam a `HTTPCookieStorage.shared` dan secara otomatis menyertakan cookie dalam permintaan ke domain yang Anda tentukan`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 ]

`setTokenCookie`Kapan`TRUE`, penyedia token menyimpan AWS WAF token dalam `CookieHandler` instance yang dibagikan di seluruh aplikasi. Penyedia token secara otomatis menyertakan cookie dalam permintaan ke domain yang Anda tentukan`WAFConfiguration`.

Contoh Java:

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

Contoh Kotlin:

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

Jika Anda sudah menginisialisasi instance `CookieHandler` default, penyedia token akan menggunakannya untuk mengelola cookie. Jika tidak, penyedia token akan menginisialisasi `CookieManager` instance baru dengan AWS WAF token `CookiePolicy.ACCEPT_ORIGINAL_SERVER` dan kemudian mengatur instance baru ini sebagai instance default di`CookieHandler`.

Kode berikut menunjukkan cara SDK menginisialisasi pengelola cookie dan penangan cookie saat tidak tersedia di aplikasi Anda. 

Contoh Java:

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

Contoh Kotlin:

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

------

## Menyediakan cookie token secara manual dalam permintaan HTTP Anda
<a name="waf-mobile-sdk-coding-manual-token-cookie"></a>

Jika Anda menyetel `setTokenCookie` ke`FALSE`, maka Anda perlu memberikan cookie token secara manual, sebagai header permintaan HTTP Cookie, dalam permintaan Anda ke titik akhir yang dilindungi. Kode berikut menunjukkan bagaimana melakukan ini.

------
#### [ 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 ]

Contoh 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();
```

Contoh 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
```

------