Яндекс SmartCaptcha в Angular26.03.2025 18:01

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

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

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

xycx-kfi5glwmhxhsw47twfwyyo.png

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

При разработке 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: `
    

      

        
        
      

      
      

        
      

      
      
    

  `
})
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: 


  
  
  
  
  


submitForm(): void {
  this.submitAttempted = true; // Это запустит невидимую капчу
  
  // Форма будет отправлена только после успешного прохождения капчи
  // и получения токена (через onCaptchaSuccess)
}

onCaptchaSuccess(token: string): void {
  this.apiService.sendFormWithCaptcha(this.form.value, token)
    .subscribe(response => {
      // Обработка ответа
    });
}

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

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

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

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

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

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

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

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

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

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

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

[theme]="'light'"

Заключение

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

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

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

© Habrahabr.ru