웹사이트에 체크박스 키(체크박스 챌린지) 설치

이 페이지에서는 로봇이 아닙니다 체크박스 챌린지를 사용하여 웹사이트에 체크박스 키를 설치하는 방법을 설명합니다. 체크박스 키를 만들 때 챌린지 보안 옵션을 구성한 방식에 따라 reCAPTCHA는 유효한 토큰을 생성하기 전에 최종 사용자가 CAPTCHA 챌린지에 답하도록 요구할 수 있습니다.

시작하기 전에

reCAPTCHA 환경을 준비합니다.
체크박스 키를 만듭니다.

또는 다음 단계 중 하나를 수행하여 기존 체크박스 키의 ID를 복사할 수 있습니다.
- Google Cloud 콘솔에서 기존 키의 ID를 복사하려면 다음을 수행합니다.
  1. reCAPTCHA 페이지로 이동합니다.
    
    reCAPTCHA로 이동
  2. reCAPTCHA 키 목록에서 복사할 키 위에 마우스 포인터를 올려놓고 를 클릭합니다.
- REST API를 사용하여 기존 키의 ID를 복사하려면 projects.keys.list 메서드를 사용합니다.
- gcloud CLI를 사용하여 기존 키의 ID를 복사하려면 gcloud recaptcha keys list 명령어를 사용합니다.

프런트엔드에서 reCAPTCHA 위젯 렌더링

웹페이지에 reCAPTCHA 위젯을 표시하려면 다음 방법 중 하나를 사용합니다.

이 방법을 사용하면 g-recaptcha 클래스로 모든 객체(예: div 또는 span)에서 위젯을 렌더링할 수 있습니다.

웹페이지에서, 필요한 JavaScript 리소스와 g-recaptcha 클래스가 포함된 HTML 요소를 포함합니다.

g-recaptcha 클래스가 있는 요소에서 data-sitekey 속성을 포함하고 이를 체크박스 키와 동일하게 설정합니다.

작업을 지정하려면 data-action 속성을 포함하고 작업 이름으로 설정합니다. 자세한 내용은 작업을 참조하세요.

스크립트는 HTTPS 프로토콜을 사용하여 로드해야 하며 페이지의 어느 포인트에서 제한 없이 포함할 수 있습니다.

reCAPTCHA는 기본적으로 브라우저의 언어를 사용합니다. 다른 언어를 지정하려면 스크립트에서 hl=LANG 속성을 사용합니다. 예를 들어 프랑스어를 사용하려면 <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>를 지정합니다. 지원되는 언어에 대한 자세한 내용은 reCAPTCHA 언어 코드를 참조하세요.

다음 예시는 샘플 코드의 스니펫입니다.

    <html>
      <head>
        <title>reCAPTCHA demo: Simple page</title>
        <script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
      </head>
      <body>
        <form action="?" method="POST">
          <div class="g-recaptcha" data-sitekey="KEY_ID" data-action="LOGIN"></div>
          <br/>
          <input type="submit" value="Submit">
        </form>
      </body>
    </html>

이 방법을 사용하면 grecaptcha.enterprise.render() 메서드로 기존 JavaScript 스크립트를 통해 위젯을 렌더링할 수 있습니다. 경합 상태를 방지하거나 기존 JavaScript 논리에 따라 위젯을 표시하려는 경우 이 방법을 사용합니다.

위젯을 명시적으로 렌더링할 때 경합 상태를 방지하려면 다음 사항을 검토하세요.

먼저 콜백 함수로, 그 다음에는 reCAPTCHA API를 사용하여 스크립트를 정렬합니다.
script 태그에서 async 및 defer 매개변수를 사용하십시오.

위젯을 명시적으로 렌더링하려면 다음 단계를 따르세요.

위젯 렌더링을 지연시키는 방법은 다음과 같습니다.
1. reCAPTCHA API 및 기타 종속 항목이 로드되기 전에 onload 콜백 함수를 지정합니다.
```
 <script type="text/javascript">
 var onloadCallback = function() {
    alert("grecaptcha is ready!");
 };
 </script>
```
2. 콜백 함수가 실행되면 JavaScript API에서 다음 매개변수를 사용하여 grecaptcha.enterprise.render() 메서드를 호출합니다.
  - 컨테이너: reCAPTCHA 위젯을 렌더링하기 위한 HTML 요소. 컨테이너의 ID(문자열)나 DOM 요소 자체를 지정합니다.
  - 파라미터: 파라미터가 키-값 쌍으로 포함된 객체입니다(예: {"sitekey": "KEY_ID", "theme": "light"}).
  - 작업: 보호된 요소와 연결된 작업 이름을 지정합니다.
    
    중요: 지정한 작업은 평가의 일부로 반환됩니다. 평가의 JSON 응답에 있는 작업이 이 평가를 만들 때 지정한 예상 작업과 일치하는지 확인해야 합니다. 예를 들어 로그인 페이지에 로그인 작업이 반환되어야 합니다. 불일치가 있으면 공격자가 작업을 조작하려고 시도함을 나타냅니다.
```
grecaptcha.enterprise.render('html_element', {
   'sitekey' : 'KEY_ID',
   'action': 'LOGIN',
 });
```
위젯을 렌더링하려면 JavaScript 리소스를 삽입합니다. onload를 onload 콜백 함수의 이름으로 설정하고 render=explicit을 포함합니다.

reCAPTCHA는 기본적으로 브라우저의 언어를 사용합니다. 다른 언어를 지정하려면 스크립트에서 hl=LANG 속성을 사용합니다. 예를 들어 프랑스어를 사용하려면 <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>를 지정합니다. 지원되는 언어에 대한 자세한 내용은 reCAPTCHA 언어 코드를 참조하세요.
```
 <script src="https://www.google.com/recaptcha/enterprise.js?onload=onload_Callback_function&render=explicit"
    async defer>
 </script>
```

예시 1

다음 코드 샘플은 onload 콜백 후 명시적 렌더링을 보여줍니다.

<html>
   <head>
    <title>reCAPTCHA demo: Explicit render after an onload callback</title>
     <script type="text/javascript">
      var onloadCallback = function() {
        grecaptcha.enterprise.render('html_element', {
          'sitekey' : 'KEY_ID',
        });
      };
    </script>
  </head>
  <body>
    <form action="?" method="POST">
      <div id="html_element"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
      <script src="https://www.google.com/recaptcha/enterprise.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

예시 2

다음 코드 샘플은 여러 위젯의 명시적 렌더링을 보여줍니다.

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render for multiple widgets</title>
        <script type="text/javascript">
      var verifyCallback = function(response) {
        alert(response);
      };
      var widgetId1;
      var widgetId2;
      var onloadCallback = function() {
        // Renders the HTML element with id 'example1' as a reCAPTCHA widget.
        // The id of the reCAPTCHA widget is assigned to 'widgetId1'.
        widgetId1 = grecaptcha.enterprise.render('example1', {
          'sitekey' : 'KEY_ID',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.enterprise.render(document.getElementById('example2'), {
          'sitekey' : 'KEY_ID',
        });
        grecaptcha.enterprise.render('example3', {
          'sitekey' : 'KEY_ID',
          'callback' : verifyCallback,
          'theme' : 'dark'
        });
      };
    </script>
  </head>
  <body>
    <!-- The g-recaptcha-response string displays in an alert message upon submit. -->
    <form action="javascript:alert(grecaptcha.enterprise.getResponse(widgetId1));">
      <div id="example1"></div>
      <br>
      <input type="submit" value="getResponse">
    </form>
    <br>
    <!-- Resets reCAPTCHA widgetId2 upon submit. -->
    <form action="javascript:grecaptcha.enterprise.reset(widgetId2);">
      <div id="example2"></div>
      <br>
      <input type="submit" value="reset">
    </form>
    <br>
    <!-- POSTs back to the page's URL upon submit with a g-recaptcha-response POST parameter. -->
    <form action="?" method="POST">
      <div id="example3"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
     <script src="https://www.google.com/recaptcha/enterprise.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

다음 단계

reCAPTCHA 응답 토큰을 평가하려면 평가를 만듭니다.

웹사이트에 체크박스 키(체크박스 챌린지) 설치

시작하기 전에

프런트엔드에서 reCAPTCHA 위젯 렌더링

자동으로 위젯 렌더링

위젯을 명시적으로 렌더링

다음 단계