Angular Yandex Smart Captcha

An Angular library for integrating Yandex SmartCaptcha into your applications. This package provides Angular components that wrap the Yandex SmartCaptcha JavaScript library, supporting both standard and invisible captchas. It leverages Angular’s reactive forms (via ControlValueAccessor and Validator) and modern features like signals and effects (with zoneless support).

Note: This documentation mirrors the concepts from the Yandex SmartCaptcha React documentation while adapting them to Angular.

Installation

Install the package via npm:

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

Components

This library provides two main standalone components:

• SmartCaptchaComponent: The standard Yandex SmartCaptcha component.
• InvisibleSmartCaptchaComponent: An extension of SmartCaptchaComponent configured for invisible captcha behavior.

Both components implement Angular’s ControlValueAccessor and Validator, making them easily integrated into reactive forms.

Usage

Importing the Component

Since the components are standalone, you can directly import them into your Angular module or component:

import { SmartCaptchaComponent } from '@ngx-rock/yandex-smart-captcha';
// or for invisible captcha
import { InvisibleSmartCaptchaComponent } from '@ngx-rock/yandex-smart-captcha';

Template Example (Standard Captcha)

<form [formGroup]="form">
  <smart-captcha
    formControlName="captcha"
    [sitekey]="'YOUR_SITE_KEY'"
    [language]="'en'"
    (challengeVisible)="onChallengeVisible()"
    (challengeHidden)="onChallengeHidden()"
    (success)="onSuccess($event)"
    (networkError)="onNetworkError()"
    (tokenExpired)="onTokenExpired()"
    (javascriptError)="onJavascriptError($event)"
  ></smart-captcha>
  
  <button type="submit" [disabled]="form.invalid">Submit</button>
</form>

Template Example (Invisible Captcha)

<form [formGroup]="form">
  <invisible-smart-captcha
    formControlName="captcha"
    [sitekey]="'YOUR_SITE_KEY'"
    [language]="'en'"
    (challengeVisible)="onChallengeVisible()"
    (challengeHidden)="onChallengeHidden()"
    (success)="onSuccess($event)"
    (networkError)="onNetworkError()"
    (tokenExpired)="onTokenExpired()"
    (javascriptError)="onJavascriptError($event)"
  ></invisible-smart-captcha>
  
  <button type="submit" [disabled]="form.invalid">Submit</button>
</form>

Component API

Inputs

Common Inputs (for both components)

• sitekey (string, required): Your Yandex SmartCaptcha site key.
• language (string): Locale code for language customization (e.g., 'en' or 'ru').
• test (boolean): Enable test mode for development.
• webview (boolean): Enable special behavior for webview contexts.

Specific Inputs

• invisible (boolean):
  • SmartCaptchaComponent: Determines whether the captcha is invisible.
  • InvisibleSmartCaptchaComponent: Always set to true (cannot be overridden).
• visible (boolean): Triggers the execution for invisible captcha when set.
• hideShield (boolean): Option to hide the shield.
• shieldPosition ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right'): Position of the shield with data processing notice when visible.

Outputs (Events)

• challengeVisible: Emitted when the captcha challenge is displayed.
• challengeHidden: Emitted when the captcha challenge is hidden.
• success: Emitted with the token string when the captcha is successfully solved.
• networkError: Emitted when there is a network error loading the captcha.
• tokenExpired: Emitted when the previously obtained token expires.
• javascriptError: Emitted with an error payload if a JavaScript error occurs in the captcha script.

How It Works

1. Script Loading & Initialization:
   The component dynamically creates and appends a <script> tag to load the Yandex SmartCaptcha API. A shared callback mechanism ensures that the captcha is rendered as soon as the script is ready.

2. Rendering the Captcha:
   Once the API is loaded, the component renders the captcha inside the container element referenced in the template. It passes the configuration parameters (such as sitekey, theme, language, etc.) to the underlying Yandex SmartCaptcha instance.

3. Event Handling & Subscriptions:
   The component sets up subscriptions to various captcha events (e.g., challenge visibility, success, network errors) and emits Angular outputs accordingly. This allows you to hook custom logic into the captcha lifecycle.

4. Validation & Value Access:
   When the captcha is solved, the token is set internally and propagated to Angular forms via the registered change callback. The validator ensures that a token exists (or defers validation for invisible captcha until user interaction).

Example Component

Here is an example of an Angular component using the SmartCaptcha:

import { Component, OnInit } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

@Component({
  selector: 'app-captcha-form',
  templateUrl: './captcha-form.component.html',
})
export class CaptchaFormComponent {
  form: FormGroup;

  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      // The captcha control will store the token returned by the captcha
      captcha: [null, Validators.required],
    });
  }

  onChallengeVisible(): void {
    console.log('Captcha challenge visible');
  }

  onChallengeHidden(): void {
    console.log('Captcha challenge hidden');
  }

  onSuccess(token: string): void {
    console.log('Captcha solved, token:', token);
  }

  onNetworkError(): void {
    console.error('Captcha network error');
  }

  onTokenExpired(): void {
    console.warn('Captcha token expired');
  }

  onJavascriptError(error: any): void {
    console.error('Captcha javascript error:', error);
  }

  onSubmit(): void {
    if (this.form.valid) {
      // Process form submission
      console.log('Form submitted with captcha token:', this.form.value.captcha);
    } else {
      console.error('Form is invalid');
    }
  }
}

Customization Options

You can customize various aspects of the captcha by passing different inputs:

• Language: Adjust the captcha language with the language input.
• Shield Customization: Configure shield visibility and position with hideShield and shieldPosition.

Troubleshooting

• Invalid Host Error:
  Ensure the host input is in the correct format (e.g., domain.ru or localhost:3000). An invalid host will log an error and prevent captcha rendering.

• Script Loading Issues:
  Verify that your network allows access to the Yandex SmartCaptcha API endpoint. Check your browser console for errors if the script fails to load.

• Form Validation:
  If the captcha control remains invalid, ensure that the user interacts with the captcha (for invisible captcha, make sure the visible input is triggered).

Contributing

Contributions are welcome! Feel free to fork the repository and submit pull requests. For major changes, please open an issue first to discuss what you would like to change.

License

Distributed under the MIT License.

References

• Yandex SmartCaptcha 2.9.0 Documentation (React)

This documentation should provide a complete guide for developers integrating the Yandex SmartCaptcha into their Angular projects using @ngx-rock/yandex-smart-captcha. Enjoy secure and seamless captcha integration in your Angular apps!

English | Русский