Skip to content

reCAPTCHA API wrapper + Base Components (vue, react, web-component)

Notifications You must be signed in to change notification settings

artifact-project/recaptcha

Repository files navigation

reCAPTCHA

reCAPTCHA API & Components

npm i --save-dev @artifact-project/recaptcha

Features

  • API 🛠
  • Multi language 🇷🇺🇺🇸🇨🇳
  • Support mock for testing 🔬
  • Events💡& Analytics 📊(support ⚡️@perf-tools/keeper)
  • Components
    • React (ready to use)
      • Server side render
      • Dynamic properties
    • Vue (in progress, help wanted)
    • WebComponent (in progress, help wanted)

Usage

See examples

// As API
import { renderReCaptchaWidget } from '@artifact-project/recaptcha';

const widget = renderReCaptchaWidget({
	el: document.getElementById('captcha-box'),

	params: { // https://developers.google.com/recaptcha/docs/display#render_param
		sitekey: 'XXXX',
		theme: 'dark',
	},

	handle(type, code, error) {
		console.log('type:', type); // Enum('change', 'expired', 'error')
		console.log('code:', code); // 'XXXX' or null
	},

	// Events
	onchallengeshow(challengeRef) {},
	onchallengehide(challengeRef) {},
	onstartattempt(attempt) {
		console.log('attempt.start:', attempt); // {state: 'start', start: 132314124, duration: 0};
	},
	onattempt(attempt) {
		console.log('attempt.resolved:', attempt); // {state: 'verified', start: 132314124, duration: 325325};
	},
});

// As React Compomnent
import { ReCaptcha } from '@artifact-project/recaptcha/react';

const captcha = (
	<ReCaptcha
		sitekey={'XXXX'}
		loading={<span>⏳Loading...</span>}
		onReady={() => console.log('reCAPTCHA is ready')}
		onChange={(code) => console.log('reCAPTCHA code:', code)}
		onExpired={(code) => { /* ... */ }}
		onError={(err) => { /* ... */ }}

		onChallengeShow={() => { /* ... */ }}
		onChallengeHide={() => { /* ... */ }}
		onStartAttempt={(attempt) => { /* ... */ }}
		onAttempt={(attempt) => { /* ... */ }}
	/>
);

Advanced API

import {
	installReCaptchaSDK,
	renderReCaptchaWidget,
} from '@artifact-project/recaptcha';

installReCaptchaSDK().then(() => {
	console.log('reCAPTCHA SDK —> loaded');
});

renderReCaptchaWidget({ ... }).ready.then(widget => {
	console.log('reCAPTCHA SDK —> loaded');
	console.log('reCAPTCHA Widget —> rendered');
})

Enterprise recaptcha

Чтобы подключить enterprise версию рекаптчи, необходимо передать isEnterprise флаг.

// As API
import { renderReCaptchaWidget } from '@artifact-project/recaptcha';

const widget = renderReCaptchaWidget({
	params: {
		sitekey: 'XXXX',
		theme: 'dark',
		isEnterprise: true
	},
    ...
});

// As React Compomnent
import { ReCaptcha } from '@artifact-project/recaptcha/react';

const captcha = (
	<ReCaptcha
		sitekey={'XXXX'}
		isEnterprise
	/>
);

Testing / Mock

React component

See example

import { ReCaptcha, ReCaptchaContextMock } from '@artifact-project/recaptcha/react';

const captchaWithMock = (
	<ReCaptchaContextMock.Provider value={{
		code: 'xx123xx',
		ctrlProps: {'data-qa': 'recaptcha-btn'},
		okProps: {'data-qa': 'recaptcha-successfully'},
	}}>
		<ReCaptcha
			sitekey={'XXXX'}
			onChange={(code) => {
				console.log('reCAPTCHA code:', code); // always: 'xx123xx'
			}}
		/>
	</ReCaptchaContextMock.Provider>
);

Analytics

import { renderReCaptchaWidget } from '@artifact-project/recaptcha';
import { createReCaptchaAnalytics } from '@artifact-project/recaptcha/analytics';

const analytics = createReCaptchaAnalytics('LoginPage');

renderReCaptchaWidget({
	el: document.getElementById('captcha-box'),
	params: { /*...*/ },
	...analytics.mixin('native'), // added `on`-props
});

document.getElementById('login-form').addEventListener('submit', () => {
	const stats = analytics.get();

	sendToMyAnalytics(analytics.name, stats);
	analytics.clear();

	// ...
});

Using with ⚡️@perf-tools/keeper

import { system as systemKepper } from '@perf-tools/keeper';
import { createReCaptchaAnalytics } from '@artifact-project/recaptcha/analytics';

const analytics = createReCaptchaAnalytics('Login', {
	keeper: systemKepper,
});

// ... bla-bla-bla

Analytics in keeper