Яндекс SmartCaptcha в Angular

В эпоху массовых ботнетов и автоматизированных атак защита веб-форм стала неотъемлемой частью разработки современных приложений. Особенно актуальна эта проблема для российских разработчиков после ухода многих зарубежных сервисов с рынка. Одним из отечественных решений, призванных заполнить образовавшуюся нишу, стала Яндекс SmartCaptcha — российская альтернатива Google reCAPTCHA.

Хотя Яндекс предоставляет официальную библиотеку для React, интеграция с Angular требует дополнительных усилий.

В этой статье рассмотрим подходы к созданию Angular-адаптера, его архитектуру и особенности использования.

Подход к реализации

При разработке Angular-решения я стремился учесть следующие критерии:

1. Полная реализация всех функций оригинального JavaScript API.

2. Соответствие Angular-подходам и интеграция с реактивными формами.

3. Поддержка современных возможностей Angular: использование standalone-компонентов, сигналов и работы в zoneless-режиме.

4. Совместимость с серверным рендерингом (SSR).

Основные компоненты библиотеки

Библиотека предоставляет два основных компонента:

1. SmartCaptchaComponent — стандартная капча с видимым элементом на странице.

2. InvisibleSmartCaptchaComponent — невидимая капча, которая запускается программно.

Оба компонента реализуют интерфейсы ControlValueAccessor и Validator, что обеспечивает бесшовную интеграцию с реактивными формами Angular.

Пример использования

Рассмотрим простой пример использования компонента в форме:

import { Component } from '@angular/core'; import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms'; import { SmartCaptchaComponent } from '@ngx-rock/yandex-smart-captcha';  @Component({   selector: 'app-contact-form',   standalone: true,   imports: [ReactiveFormsModule, SmartCaptchaComponent],   template: `     <form [formGroup]="form" (ngSubmit)="onSubmit()">       <div class="form-group">         <label for="email">Почта</label>         <input type="text" id="email" formControlName="email">       </div>              <div class="form-group">         <smart-captcha           formControlName="captcha"           [sitekey]="'YOUR_SITE_KEY'"           (success)="onCaptchaSuccess($event)"         />       </div>              <button type="submit" [disabled]="form.invalid">Отправить</button>     </form>   ` }) export class ContactFormComponent {   form: FormGroup;      constructor(private fb: FormBuilder) {     this.form = this.fb.group({       email: ['', Validators.required],       captcha: [null, Validators.required]     });   }      onCaptchaSuccess(token: string): void {     console.log('Капча успешно пройдена:', token);   }      onSubmit(): void {     if (this.form.valid) {       const formData = this.form.value;       // formData.captcha содержит токен капчи     }   } } 

Особенности использования невидимой капчи

Невидимая капча (invisible captcha) — особый режим работы, когда пользователю не требуется выполнять дополнительных действий. Этот режим особенно полезен для увеличения конверсии форм, где лишние шаги могут отпугнуть пользователей.

Вот пример использования невидимой капчи в Angular:

<form [formGroup]="form" (ngSubmit)="submitForm()">   <!-- Другие поля формы -->      <invisible-smart-captcha     formControlName="captcha"     [sitekey]="'YOUR_SITE_KEY'"     [visible]="submitAttempted"     (success)="onCaptchaSuccess($event)"   />      <button type="submit">Отправить</button> </form> 

submitForm(): void {   this.submitAttempted = true; // Это запустит невидимую капчу      // Форма будет отправлена только после успешного прохождения капчи   // и получения токена (через onCaptchaSuccess) }  onCaptchaSuccess(token: string): void {   this.apiService.sendFormWithCaptcha(this.form.value, token)     .subscribe(response => {       // Обработка ответа     }); } 

Обработка ошибок и граничных случаев

Работа с внешними API всегда связана с возможными ошибками. Библиотека предоставляет обработку следующих сценариев:

1. Сетевые ошибки — когда скрипт не может быть загружен.

2. JavaScript-ошибки — возникающие в коде капчи.

3. Истечение срока действия токена — когда полученный токен истёк.

Для каждого из этих случаев компонент предоставляет соответствующее событие, которое можно обработать:

<smart-captcha   [sitekey]="'YOUR_SITE_KEY'"   (networkError)="handleNetworkError()"   (javascriptError)="handleJsError($event)"   (tokenExpired)="handleTokenExpired()" /> 

Настройка внешнего вида

Яндекс SmartCaptcha предоставляет несколько вариантов настройки внешнего вида:

1. Можно скрыть блок с уведомлением об обработке данных или указать его расположение:

[hideShield]="true"   [shieldPosition]="'bottom-right'"   

2. Можно управлять цветовой схемой ('light' | 'dark' | 'auto'):

[theme]="'light'" 

Заключение

Библиотека доступна как npm-пакет и может быть установлена в любой Angular-проект, начиная с версии 17.3.0:

npm install @ngx-rock/yandex-smart-captcha 

Проект полностью открыт для вкладов сообщества, и вы можете присоединиться к его разработке на GitHub.