이 페이지는 Cloud Translation API를 통해 번역되었습니다.

reCAPTCHA v2

이 페이지에서는 웹페이지에 reCAPTCHA v2 위젯을 표시하고 맞춤설정하는 방법을 설명합니다.

위젯을 표시하려면 다음 중 하나를 수행하면 됩니다.

위젯 자동 렌더링 또는
위젯을 명시적으로 렌더링

위젯을 맞춤설정하는 방법은 구성을 참조하세요. 예를 들어 위젯의 언어 또는 테마를 지정할 수 있습니다.

사용자가 보안문자를 풀었는지 확인하려면 사용자의 응답 인증하기를 참고하세요.

reCAPTCHA 위젯 자동 렌더링

페이지에서 reCAPTCHA 위젯을 렌더링하는 가장 쉬운 방법은 필요한 JavaScript 리소스와 g-recaptcha 태그를 포함하는 것입니다. g-recaptcha 태그 클래스 이름이 g-recaptcha이고 data-sitekey 속성:

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

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

reCAPTCHA 위젯을 명시적으로 렌더링

onload 콜백 함수를 지정하고 JavaScript 리소스에 매개변수를 추가하여 렌더링 연기를 수행할 수 있습니다.

onload 콜백 함수를 지정합니다. 이 함수는 모든 종속 항목이 로드되었습니다

<script type="text/javascript">
  var onloadCallback = function() {
    alert("grecaptcha is ready!");
  };
</script>

onload 매개변수를 onload 콜백 함수의 이름으로 설정하고 render 매개변수를 explicit로 설정하여 JavaScript 자원을 삽입하십시오.
```
<script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
    async defer>
</script>
```
콜백이 실행될 때 JavaScript API에서 grecaptcha.render 메서드를 호출할 수 있습니다.
onload 콜백 함수는 reCAPTCHA API 로드 전에 정의되어야 합니다. 경합 조건이 없는지 확인하려면 다음 안내를 따르세요.
- 먼저 콜백으로 스크립트를 주문한 다음 reCAPTCHA를 처리하십시오
- `script` 태그에서 async 및 defer 매개변수를 사용하십시오.

구성

JavaScript 리소스(api.js) 매개변수

매개변수	값	설명
`onload`		선택사항입니다. 모든 종속 항목이 로드되면 실행될 콜백 함수의 이름입니다.
`render`	명시적 onload	선택사항. 위젯을 명시적으로 렌더링할지의 여부입니다. 기본적으로 onload로, 발견된 첫 번째 `g-recaptcha` 태그에서 위젯을 렌더링합니다.
`hl`	언어 코드 참조	선택사항. 위젯이 특정 언어로 렌더링되도록 합니다. 지정하지 않았으면 사용자의 언어를 자동으로 감지합니다.

g-recaptcha 태그 속성 및 grecaptcha.render 매개변수

g-recaptcha 태그 속성	grecaptcha.render 매개변수	값	기본값	설명
`data-sitekey`	`sitekey`			sitekey입니다.
`data-theme`	`theme`	`dark light`	`light`	선택사항입니다. 위젯의 색상 테마
`data-size`	`size`	`compact normal`	`normal`	선택사항입니다. 위젯의 크기입니다.
`data-tabindex`	`tabindex`		0	선택사항입니다. 위젯 및 도전과제의 tabindex입니다. 페이지의 다른 요소에 tabindex가 사용되는 경우 사용자 탐색이 쉽도록 설정해야 합니다.
`data-callback`	`callback`			선택사항입니다. 사용자가 성공 응답을 제출할 때 실행되는 콜백 함수의 이름입니다. `g-recaptcha-response` 토큰이 콜백에 전달됩니다.
`data-expired-callback`	`expired-callback`			선택사항입니다. reCAPTCHA 응답이 만료되어 사용자가 다시 확인을 수행해야 할 때 실행되는 콜백 함수의 이름입니다.
`data-error-callback`	`error-callback`			선택사항입니다. reCAPTCHA에 오류(일반적으로 네트워크 연결)가 발생하여 연결이 복원될 때까지 계속할 수 없는 경우 콜백 함수의 이름입니다. 여기에 기능을 지정하면 귀하는 사용자에게 재시도하도록 알려야 할 책임이 있습니다.

JavaScript API

방법	설명
`grecaptcha.render`( container, parameters )	컨테이너를 reCAPTCHA 위젯으로 렌더링하고 새로 생성된 위젯의 ID를 리턴합니다. 컨테이너 reCAPTCHA 위젯을 렌더링하기 위한 HTML 요소. 컨테이너의 ID(문자열)나 DOM 요소 자체를 지정하십시오. 매개변수 {"sitekey": "your_site_key", "theme": "light"}와 같이 key=value 쌍으로 매개변수를 포함하는 객체입니다. grecaptcha.render 매개변수를 참고하세요.
`grecaptcha.reset( opt_widget_id )`	reCAPTCHA 위젯을 재설정합니다. opt_widget_id 선택적인 위젯 ID입니다. 지정하지 않으면 기본적으로 생성된 첫 번째 위젯으로 지정됩니다.
`grecaptcha.getResponse( opt_widget_id )`	reCAPTCHA 위젯의 응답을 가져옵니다. opt_widget_id 선택적인 위젯 ID입니다. 지정하지 않으면 기본적으로 생성된 첫 번째 위젯으로 지정됩니다.

예

onload 콜백 후 명시적 렌더링

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render after an onload callback</title>
    <script type="text/javascript">
      var onloadCallback = function() {
        grecaptcha.render('html_element', {
          'sitekey' : 'your_site_key'
        });
      };
    </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/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

여러 위젯에 대한 명시적 렌더링

<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.render('example1', {
          'sitekey' : 'your_site_key',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.render(document.getElementById('example2'), {
          'sitekey' : 'your_site_key'
        });
        grecaptcha.render('example3', {
          'sitekey' : 'your_site_key',
          'callback' : verifyCallback,
          'theme' : 'dark'
        });
      };
    </script>
  </head>
  <body>
    <!-- The g-recaptcha-response string displays in an alert message upon submit. -->
    <form action="javascript:alert(grecaptcha.getResponse(widgetId1));">
      <div id="example1"></div>
      <br>
      <input type="submit" value="getResponse">
    </form>
    <br>
    <!-- Resets reCAPTCHA widgetId2 upon submit. -->
    <form action="javascript:grecaptcha.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/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>