Captcha integration

Captcha Integration

This document provides guidance for integrating Google reCAPTCHA v3 in Angular applications using the platform's captcha service.

Backend Documentation: For backend implementation details, see Captcha BE

Overview

The platform provides a wrapper service for reCAPTCHA v3 integration that abstracts the underlying implementation and provides a consistent API. This approach ensures maintainability and allows for easy updates to the underlying captcha library.

Current Implementation

Using AsolCaptchaService (Recommended for Angular 19+)

Note: AsolCaptchaService is available starting from Angular 19. For Angular 17 applications, use the Legacy Implementation until you migrate to Angular 19.

The platform provides AsolCaptchaService which wraps the reCAPTCHA functionality and is available through the authentication library.

Installation

The captcha service is included in the platform authentication library:

npm install @asol-platform/authentication

Configuration

Configure the captcha key in your authentication module:

import { AsolPlatformAuthenticationModule } from "@asol-platform/authentication";

@NgModule({
  imports: [
    AsolPlatformAuthenticationModule.forRoot({
      captchaKeyV3: environment.captchaKey,
    }),
  ],
})
export class AppModule {}

Usage in Components

import { Component } from "@angular/core";
import { AsolCaptchaService } from "@asol-platform/authentication";

@Component({
  selector: "app-demo",
  template: `
    <button (click)="executeImportantAction()">Important action</button>
  `,
})
export class DemoComponent {
  constructor(private captchaService: AsolCaptchaService) {}

  public executeImportantAction(): void {
    this.captchaService
      .executeV3("importantAction")
      .subscribe((token) => this.handleToken(token));
  }

  private handleToken(token: string): void {
    // Use the token immediately in your API call
    // Token has short lifetime, so don't store it
    console.log("Captcha token:", token);
  }
}

Legacy Implementation (Angular 17)

Direct ng-recaptcha Usage

Note: This approach is required for Angular 17 applications. After migrating to Angular 19, switch to AsolCaptchaService for better maintainability.

Legacy Installation

npm install ng-recaptcha --save

Module Configuration

import { BrowserModule } from "@angular/platform-browser";
import { RECAPTCHA_V3_SITE_KEY, RecaptchaV3Module } from "ng-recaptcha";

@NgModule({
  imports: [BrowserModule, RecaptchaV3Module],
  providers: [{ provide: RECAPTCHA_V3_SITE_KEY, useValue: "<YOUR_SITE_KEY>" }],
})
export class AppModule {}

Component Usage

import { Component } from "@angular/core";
import { ReCaptchaV3Service } from "ng-recaptcha";

@Component({
  selector: "recaptcha-demo",
  template: `
    <button (click)="executeImportantAction()">Important action</button>
  `,
})
export class RecaptchaV3DemoComponent {
  constructor(private recaptchaV3Service: ReCaptchaV3Service) {}

  public executeImportantAction(): void {
    this.recaptchaV3Service
      .execute("importantAction")
      .subscribe((token) => this.handleToken(token));
  }
}

Migration from Legacy to Current

If you're currently using the legacy ng-recaptcha implementation:

1. Update Module Configuration

Remove the old configuration:

// Remove these imports and providers
import { RECAPTCHA_V3_SITE_KEY, RecaptchaV3Module } from "ng-recaptcha";

@NgModule({
  imports: [RecaptchaV3Module], // Remove
  providers: [
    { provide: RECAPTCHA_V3_SITE_KEY, useValue: "<YOUR_SITE_KEY>" } // Remove
  ]
})

Add the new configuration:

import { AsolPlatformAuthenticationModule } from '@asol-platform/authentication';

@NgModule({
  imports: [
    AsolPlatformAuthenticationModule.forRoot({
      captchaKeyV3: environment.captchaKey
    })
  ]
})

2. Update Component Imports

Replace the old service import:

// Old - Remove
import { ReCaptchaV3Service } from "ng-recaptcha";

// New - Add
import { AsolCaptchaService } from "@asol-platform/authentication";

3. Update Service Injection

Replace the constructor injection:

// Old
constructor(private recaptchaV3Service: ReCaptchaV3Service) {}

// New
constructor(private captchaService: AsolCaptchaService) {}

4. Update Method Calls

Replace the service method call:

// Old
this.recaptchaV3Service.execute("action");

// New
this.captchaService.executeV3("action");

Best Practices

Token Handling

1. Use tokens immediately: reCAPTCHA tokens have a short lifetime (typically 2 minutes)
2. Don't store tokens: Generate a new token for each action that requires verification
3. Handle errors: Always implement error handling for captcha token generation

public executeAction(): void {
  this.captchaService.executeV3('actionName')
    .subscribe({
      next: (token) => {
        // Use token immediately in API call
        this.apiService.performAction(data, token).subscribe(response => {
          // Handle success
        });
      },
      error: (error) => {
        console.error('Captcha token generation failed:', error);
        // Handle captcha error
      }
    });
}

Action Names

Use descriptive action names that represent the user action:

• 'login' - for login attempts
• 'contact' - for contact form submissions
• 'purchase' - for purchase transactions
• 'registration' - for user registration

Environment Configuration

Store captcha keys in environment files:

// environment.ts
export const environment = {
  captchaKey: "your-development-site-key",
};

// environment.prod.ts
export const environment = {
  captchaKey: "your-production-site-key",
};

Troubleshooting

Common Issues

Captcha not loading: Verify the site key is correctly configured in the environment

Token generation fails: Check browser console for reCAPTCHA errors and verify domain configuration

Invalid token errors: Ensure tokens are used immediately and not stored or reused

Module errors after migration: Remove all references to old ng-recaptcha imports and providers

Getting Help

1. Check the Google reCAPTCHA documentation
2. Verify your reCAPTCHA site configuration in Google Admin Console
3. Consult the platform team for authentication library issues