@artifact-project/recaptcha

reCAPTCHA API & Components

Usage no npm install needed!

<script type="module">
  import artifactProjectRecaptcha from 'https://cdn.skypack.dev/@artifact-project/recaptcha';
</script>

README

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() {},
    onchallengehide() {},
    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