reCAPTCHA v2

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

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

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

사용자가 보안문자를 해결했는지 확인하려면 사용자 응답 확인을 참조하세요.

reCAPTCHA 위젯 자동 렌더링

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

<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 리소스에 매개변수를 추가하여 렌더링 연기를 수행할 수 있습니다.

  1. onload 콜백 함수를 지정합니다. 이 함수는 모든 종속 항목이 로드되면 호출됩니다.

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

  2. 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 메서드를 호출할 수 있습니다.

구성

자바스크립트 리소스 (api.js) 매개변수

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

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

g-recaptcha 태그 속성 grecaptcha.render 매개변수 값 기본 설명
data-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>