reCAPTCHA용 JavaScript API 참조

이 페이지에서는 reCAPTCHA JavaScript API의 메서드와 reCAPTCHA 키(사이트 키)를 사용하여 웹페이지를 렌더링하는 데 사용할 수 있는 구성 매개변수를 설명합니다.

reCAPTCHA JavaScript API 메서드

이 섹션에서는 reCAPTCHA JavaScript API 메서드의 문법과 매개변수를 설명합니다.

grecaptcha.enterprise.render

컨테이너를 reCAPTCHA 위젯으로 렌더링하고 새로 생성된 위젯의 ID를 반환합니다.

구문

grecaptcha.enterprise.render(container: string | HTMLelement, parameters: Object): number

메서드 매개변수

매개변수 설명
container reCAPTCHA 위젯을 렌더링하기 위한 HTML 요소. 컨테이너의 ID(문자열)나 DOM 요소 자체를 지정합니다.
parameters

매개변수를 키=값 쌍으로 포함하는 객체(예: {"sitekey": "your_site_key", "action": "login", "theme": "dark"})

구성 가능한 각 매개변수에 대한 자세한 내용은 속성 및 매개변수를 참조하세요.

반환 값

새로 만든 위젯의 ID를 반환합니다.

grecaptcha.enterprise.reset

reCAPTCHA 위젯을 재설정합니다.

구문

grecaptcha.enterprise.reset(widget_id: number): void

매개변수

매개변수 설명
widget_id 선택사항. grecaptcha.enterprise.render()에서 반환된 위젯 ID입니다. 지정하지 않으면 기본적으로 생성된 첫 번째 위젯의 ID로 설정됩니다.

반환 값

값을 반환하지 않습니다.

grecaptcha.enterprise.execute

프로그래매틱 방식으로 reCAPTCHA 인증을 호출합니다.

구문

grecaptcha.enterprise.execute(widget_id: number): Promise<string>
 
grecaptcha.enterprise.execute(sitekey: string, action: Object): Promise<string>

매개변수

매개변수 설명
widget_id 선택사항. grecaptcha.enterprise.render()에서 반환된 위젯 ID입니다.

지정하지 않으면 기본적으로 생성된 첫 번째 위젯의 ID로 설정됩니다.
sitekey

보호할 reCAPTCHA 사이트 키를 지정합니다.
action 단일 키=값 쌍이 있는 객체. action 키의 값은 보호된 요소와 연결된 작업 이름을 지정합니다.

예: {"action": "action_name"}

반환 값

성공하면 토큰이 포함된 Promise 객체가 반환됩니다.

grecaptcha.enterprise.ready

reCAPTCHA JavaScript 라이브러리가 로드될 때 함수를 실행합니다.

구문

grecaptcha.enterprise.ready(callback: function): void

매개변수

매개변수 설명
callback reCAPTCHA 라이브러리 로드가 완료되면 호출할 함수입니다.

반환 값

값을 반환하지 않습니다.

grecaptcha.enterprise.getResponse

reCAPTCHA 위젯의 응답을 가져옵니다.

구문

grecaptcha.enterprise.getResponse(widget_id: number): string

매개변수

매개변수 설명
widget_id 선택사항. grecaptcha.enterprise.render()에서 반환된 위젯 ID입니다. 지정하지 않으면 기본적으로 생성된 첫 번째 위젯의 ID로 설정됩니다.

반환 값

reCAPTCHA 위젯의 응답을 가져옵니다. grecaptcha.enterprise.execute()에 의해 생성된 토큰이 있는 문자열이거나 토큰이 아직 생성되지 않은 경우 빈 문자열일 수 있습니다.

구성

이 섹션에서는 JavaScript 리소스 매개변수, grecaptcha.enterprise.render()에서 사용하는 매개변수, g-recaptcha 위젯의 속성을 설명합니다.

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

다음 표에는 reCAPTCHA를 사용할 때 포함해야 하는 JavaScript 리소스(enterprise.js)의 매개변수가 나와 있습니다.

이러한 매개변수 사용에 대한 자세한 내용은 프런트엔드에서 reCAPTCHA 위젯 렌더링의 예시를 참조하세요.

매개변수 값 설명
onload callback 선택사항. 모든 종속 항목이 로드된 후 실행될 콜백 함수의 이름입니다.
render onload

선택사항으로, 기본값입니다. 발견된 첫 번째 g-recaptcha 태그에서 위젯을 렌더링합니다.
explicit

선택사항. 위젯을 자동으로 렌더링하지 않습니다. 프로그래매틱 방식으로 렌더링하려면 grecaptcha.enterprise.render()를 호출해야 합니다.
siteKey

점수 기반 사이트 키와 함께 사용할 경우 이 매개변수는 선택사항이 아닙니다. siteKey 값은 연결된 점수 기반 사이트 키를 지정합니다.
hl 언어 코드 참조 선택사항. 위젯이 특정 언어로 렌더링되도록 합니다. 지정하지 않았으면 사용자의 언어를 자동으로 감지합니다.

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

다음 표에는 g-recaptcha 태그 속성 및 해당하는 grecaptcha.enterprise.render() 매개변수가 나와 있습니다.

g-recaptcha 태그 속성 grecaptcha.enterprise.render() 매개변수 허용되는 값 기본값 설명
data-sitekey sitekey reCAPTCHA 키
data-badge badge bottomright, bottomleft, inline bottomright 선택사항. reCAPTCHA 배지 위치를 변경합니다. inline을 사용하면 CSS로 위치를 지정할 수 있습니다.
data-action action 선택사항. 현재 작업을 설명하는 문자열입니다.
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에 오류(일반적으로 네트워크 연결)가 발생하여 연결이 복원될 때까지 계속할 수 없는 경우 콜백 함수의 이름입니다. 콜백은 오류 세부정보가 포함된 인수를 수신하지 않습니다. 여기에 기능을 지정하면 개발자가 사용자에게 재시도해야 함을 알려야 합니다.