BaryshevRS 26 мар в 18:00

Яндекс SmartCaptcha в Angular

Простой

3 мин

565

Туториал

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

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

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

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

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

Полная реализация всех функций оригинального JavaScript API.
Соответствие Angular-подходам и интеграция с реактивными формами.
Поддержка современных возможностей Angular: использование standalone-компонентов, сигналов и работы в zoneless-режиме.
Совместимость с серверным рендерингом (SSR).

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

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

SmartCaptchaComponent — стандартная капча с видимым элементом на странице.
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 всегда связана с возможными ошибками. Библиотека предоставляет обработку следующих сценариев:

Сетевые ошибки — когда скрипт не может быть загружен.
JavaScript-ошибки — возникающие в коде капчи.
Истечение срока действия токена — когда полученный токен истёк.

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

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

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

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

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

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

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

[theme]="'light'"

Заключение

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

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

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

Теги:

Хабы:

Angular