ng-recaptcha
Version:
Angular component for Google reCAPTCHA
648 lines (510 loc) • 26 kB
Markdown
# Angular component for Google reCAPTCHA
## ng-recaptcha [](https://www.npmjs.com/package/ng-recaptcha)
[](https://raw.githubusercontent.com/dethariel/ng-recaptcha/master/LICENSE)
[](https://app.travis-ci.com/DethAriel/ng-recaptcha)
[](https://coveralls.io/github/DethAriel/ng-recaptcha?branch=master)
[](https://www.npmjs.com/package/ng-recaptcha)
A simple, configurable, easy-to-start component for handling reCAPTCHA v2 and v3.
## Table of contents
1. [Installation](#installation)
1. [Basic Usage](#example-basic)
- [reCAPTCHA v3 Usage](#example-basic-v3)
- [Playground](#playground)
1. [Working with `@angular/forms`](#forms-ready)
1. [API](#api)
- [Input Options](#api-options)
- [Events](#api-events)
- [Methods](#api-methods)
1. [Angular version compatibility](#angular-versions)
1. [Examples](#examples)
- [Configuring the component globally](#example-global-config)
- [Specifying a different language](#example-language)
- [Handling errors](#example-error-handling)
- [Loading the reCAPTCHA API by yourself](#example-preload-api)
- [Usage with `required` in forms](#example-forms)
- [Working with invisible reCAPTCHA](#example-invisible)
- [Resizing](#example-resizing)
- [SystemJS configuration](#example-systemjs)
- [Loading from a different location](#example-different-url)
- [Specifying nonce for Content-Security-Policy](#example-csp-nonce)
- [Listening for all actions with reCAPTCHA v3](#example-v3-all-actions)
- [Loading reCAPTCHA keys asynchronously](#async-config-load)
- [Hiding reCAPTCHA badge](#hide-recaptcha-badge)
## <a name="installation"></a>Installation
The easiest way is to install through [yarn](https://yarnpkg.com/package/ng-recaptcha) or [npm](https://www.npmjs.com/package/ng-recaptcha):
```sh
yarn add ng-recaptcha
npm i ng-recaptcha --save
```
## <a name="example-basic"></a>Basic Usage [(see in action)](https://dethariel.github.io/ng-recaptcha/)
The below applies to reCAPTCHA v2, for basic usage with reCAPTCHA v3 scroll down to [here](#example-basic-v3).
To start with, you need to import the `RecaptchaModule` (more on that [later](#modules)):
```typescript
// app.module.ts
import { RecaptchaModule } from "ng-recaptcha";
// if you need forms support:
// import { RecaptchaModule, RecaptchaFormsModule } from 'ng-recaptcha';
import { BrowserModule } from "@angular/platform-browser";
import { MyApp } from "./app.component.ts";
@NgModule({
bootstrap: [MyApp],
declarations: [MyApp],
imports: [
BrowserModule,
RecaptchaModule,
// RecaptchaFormsModule, // if you need forms support
],
})
export class MyAppModule {}
```
Once you have done that, the rest is simple:
```typescript
// app.component.ts
import { Component } from "@angular/core";
@Component({
selector: "my-app",
template: `<re-captcha (resolved)="resolved($event)" siteKey="YOUR_SITE_KEY"></re-captcha>`,
})
export class MyApp {
resolved(captchaResponse: string) {
console.log(`Resolved captcha with response: ${captchaResponse}`);
}
}
```
```typescript
// main.ts
import { platformBrowserDynamic } from "@angular/platform-browser-dynamic";
import { MyAppModule } from "./app.module.ts";
platformBrowserDynamic().bootstrapModule(MyAppModule);
```
### <a name="example-basic-v3"></a>reCAPTCHA v3 Usage [(see in action)](https://dethariel.github.io/ng-recaptcha/v3)
[reCAPTCHA v3](https://developers.google.com/recaptcha/docs/v3) introduces a different way of bot protection. To work with v3 APIs, `ng-recaptcha` provides a service (as opposed to a component). To start with, you need to import the `RecaptchaV3Module` and provide your reCAPTCHA v3 site key using `RECAPTCHA_V3_SITE_KEY` injection token:
```ts
import { BrowserModule } from "@angular/platform-browser";
import { RECAPTCHA_V3_SITE_KEY, RecaptchaV3Module } from "ng-recaptcha";
import { MyApp } from "./app.component.ts";
@NgModule({
bootstrap: [MyApp],
declarations: [MyApp],
imports: [BrowserModule, RecaptchaV3Module],
providers: [{ provide: RECAPTCHA_V3_SITE_KEY, useValue: "<YOUR_SITE_KEY>" }],
})
export class MyAppModule {}
```
In order to execute a reCAPTCHA v3 action, import the `ReCaptchaV3Service` into your desired component:
```ts
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));
}
```
As always with subscriptions, please don't forget to **unsubscribe**.
❗️ **Important note**: If your site uses both v2 and v3, then you should _always_ provide `RECAPTCHA_V3_SITE_KEY` (even in modules that only rely on v2 functionality). This will prevent bugs in your code by allowing `ng-recaptcha` to follow reCAPTCHA development guidelines properly ([this one](https://developers.google.com/recaptcha/docs/faq#can-i-run-recaptcha-v2-and-v3-on-the-same-page) in particular).
A more advanced v3 usage scenario includes listening to all actions and their respectively emitted tokens. This is covered [later on this page](#example-v3-all-actions).
### <a name="playground"></a>Playground
You can also play with [this Stackblitz demo](https://stackblitz.com/edit/ng-recaptcha-example) to get a feel of how this component can be used.
## <a name="forms-ready"></a>Working with `@angular/forms`
There are two modules available for you:
```typescript
import { RecaptchaModule, RecaptchaFormsModule } from "ng-recaptcha";
```
If you want your `<re-captcha>` element to work correctly with `[(ngModel)]` directive,
you need to import the `RecaptchaFormsModule` into your application module (pretty much
like with Angular own `'@angular/forms'` module).
## <a name="api"></a>API
### <a name="api-options"></a>Input Options
The component supports this options:
- `siteKey`
- `theme`
- `type`
- `size`
- `tabIndex`
- `badge`
They are all pretty well described either in the [reCAPTCHA docs](https://developers.google.com/recaptcha/docs/display), or in the [invisible reCAPTCHA docs](https://developers.google.com/recaptcha/docs/invisible),
so I won't duplicate it here.
One additional option that component accepts is `errorMode`. You can learn more about it in the [Handling errors](#example-error-handling) section below.
Besides specifying these options on the component itself, you can provide a global `<re-captcha>` configuration - see [Configuring the component globally](#example-global-config) section below.
### <a name="api-events"></a>Events
- `resolved(response: string)`. Occurs when the captcha resolution value changed.
When user resolves captcha, use `response` parameter to send to the server for verification.
This parameter is equivalent to calling [`grecaptcha.getResponse`](https://developers.google.com/recaptcha/docs/display#js_api).
If the captcha has expired prior to submitting its value to the server, the component
will reset the captcha, and trigger the `resolved` event with `response === null`.
- `errored(errorDetails: RecaptchaErrorParameters)`. Occurs when reCAPTCHA encounters an error (usually a connectivity problem) **if and only if** `errorMode` input has been set to `"handled"`.
`errorDetails` is a simple propagation of any arguments that the original `error-callback` has provided, and is documented here for the purposes of completeness and future-proofing. This array will most often (if not always) be empty. A good strategy would be to rely on just the fact that this event got triggered, and show a message to your app's user telling them to retry.
### <a name="api-methods"></a>Methods
- `reset()`. Performs a manual captcha reset. This method might be useful if your form
validation failed, and you need the user to re-enter the captcha.
- `execute()`. Executes the invisible recaptcha. Does nothing if component's size is not set to "invisible". See [Invisible reCAPTCHA developers guide](https://developers.google.com/recaptcha/docs/invisible#js_api) for more information.
## <a name="angular-versions"></a>Angular version compatibility
| `ng-recaptcha` version | Supported Angular versions |
| -------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `13.x.x` | `17.x.x` |
| `12.x.x` | `16.x.x` |
| `11.x.x` | `15.x.x` |
| `10.x.x` | `14.x.x` |
| `9.x.x` | `13.x.x` |
| `8.x.x` | `12.x.x` |
| `7.x.x` | `11.x.x` |
| ⬆️ Starting with `ng-recaptcha@7`, only one version of Angular will be supported |
| `6.x.x` | `6.x.x \|\| 7.x.x \|\| 8.x.x \|\| 9.x.x \|\| 10.x.x` |
| `5.x.x` | `6.x.x \|\| 7.x.x \|\| 8.x.x` |
| `4.x.x` | `6.x.x \|\| 7.x.x` |
| `3.x.x` | `4.x.x \|\| 5.x.x` |
| `2.x.x` | `2.x.x \|\| 4.x.x` |
| `1.x.x` | `2.x.x` |
## <a name="examples"></a>Examples
### <a name="example-global-config"></a>Configuring the component globally [(see in action)](https://dethariel.github.io/ng-recaptcha/global-config)
Some properties are global - including `siteKey`, `size`, and others. You can provide them at the module-level using the `RECAPTCHA_SETTINGS` provider:
```typescript
import { RECAPTCHA_SETTINGS, RecaptchaSettings } from "ng-recaptcha";
@NgModule({
providers: [
{
provide: RECAPTCHA_SETTINGS,
useValue: { siteKey: "<YOUR_KEY>" } as RecaptchaSettings,
},
],
})
export class MyModule {}
```
Global properties can be overridden on a case-by-case basis - the values on the `<re-captcha>` component itself take precedence over global settings.
### <a name="example-language"></a>Specifying a different language [(see in action)](https://dethariel.github.io/ng-recaptcha/basic?lang-fr)
`<re-captcha>` supports various languages. By default recaptcha will guess the user's language itself
(which is beyond the scope of this lib).
But you can override this behavior and provide a specific language to use by setting the `"hl"` search param in the `onBeforeLoad` hook.
Note, that the language setting is **global**, and cannot be set on a per-captcha basis.
A good way to synchronize reCAPTCHA language with the rest of your application is relying on `LOCALE_ID` value like so:
```typescript
import { LOCALE_ID } from "@angular/core";
import { RECAPTCHA_LOADER_OPTIONS } from "ng-recaptcha";
@NgModule({
providers: [
{
provide: RECAPTCHA_LOADER_OPTIONS,
useFactory: (locale: string) => ({
onBeforeLoad(url) {
url.searchParams.set("hl", locale);
return { url };
},
}),
deps: [LOCALE_ID],
},
],
})
export class MyModule {}
```
Alternatively, a specific language can be provided like so:
```typescript
import { RECAPTCHA_LOADER_OPTIONS } from "ng-recaptcha";
@NgModule({
providers: [
{
provide: RECAPTCHA_LOADER_OPTIONS,
useValue: {
onBeforeLoad(url) {
url.searchParams.set("hl", "fr"); // use French language
return { url };
},
},
},
],
})
export class MyModule {}
```
You can find the list of supported languages in [reCAPTCHA docs](https://developers.google.com/recaptcha/docs/language).
### <a name="example-error-handling"></a>Handling errors
Sometimes reCAPTCHA encounters an error, which is usually a network connectivity problem. It cannot continue until connectivity is restored. By default, reCAPTCHA lets the user know that an error has happened (it's a built-in functionality of reCAPTCHA itself, and this lib is not in control of it). The downside of such behavior is that you, as a developer, don't get notified about this in any way. Opting into such notifications is easy, but comes at a cost of assuming responsibility for informing the user that they should retry. Here's how you would do this:
```typescript
import { Component } from "@angular/core";
@Component({
selector: "my-app",
template: `<re-captcha (resolved)="resolved($event)" (errored)="errored($event)" errorMode="handled"></re-captcha>`,
})
export class MyApp {
resolved(captchaResponse: string) {
console.log(`Resolved captcha with response: ${captchaResponse}`);
}
errored() {
console.warn(`reCAPTCHA error encountered`);
}
}
```
You can see this in action by navigating to either [basic example demo](https://dethariel.github.io/ng-recaptcha/basic) or [invisible demo](https://dethariel.github.io/ng-recaptcha/invisible) and trying to interact with reCAPTCHA after setting the network to "Offline".
The `errorMode` input has two possible values -- `"handled"` and `"default"`, with latter being the default as the name suggests. Not specifying `errorMode`, or setting it to anything other than `"handled"` will not invoke your `(errored)` callback, and will instead result in default reCAPTCHA functionality.
The `(errored)` callback will propagate all of the parameters that it receives from `grecaptcha['error-callback']` (which might be none) as an array.
### <a name="example-preload-api"></a>Loading the reCAPTCHA API by yourself [(see in action)](https://dethariel.github.io/ng-recaptcha/v8/preload-api)
By default, the component assumes that the reCAPTCHA API loading will be handled
by the `RecaptchaLoaderService`. However, you can override that by providing your
instance of this service to the Angular DI.
The below code snippet is an example of how such a provider can be implemented.
**TL;DR**: there should be an `Observable` that eventually resolves to a
`grecaptcha`-compatible object (e.g. `grecaptcha` itself).
```html
<script src="https://www.google.com/recaptcha/api.js?render=explicit&onload=onloadCallback"></script>
<script>
// bootstrap the application once the reCAPTCHA api has loaded
function onloadCallback() {
System.import("app").catch(function (err) {
console.error(err);
});
}
</script>
```
```typescript
import { RecaptchaLoaderService } from "ng-recaptcha";
@Injectable()
export class PreloadedRecaptchaAPIService {
public ready: Observable<ReCaptchaV2.ReCaptcha>;
constructor() {
let readySubject = new BehaviorSubject<ReCaptchaV2.ReCaptcha>(grecaptcha);
this.ready = readySubject.asObservable();
}
}
@NgModule({
providers: [
{
provide: RecaptchaLoaderService,
useValue: new PreloadedRecaptchaAPIService(),
},
],
})
export class MyModule {}
```
### <a name="example-forms"></a>Usage with `required` in forms [(see in action)](https://dethariel.github.io/ng-recaptcha/forms)
It's very easy to put `<re-captcha>` in an Angular form and have it `require`d - just
add the `required` attribute to the `<re-captcha>` element. Do not forget to import `RecaptchaFormsModule` from `'ng-recaptcha'`!
```typescript
@Component({
selector: "my-form",
template: ` <form>
<re-captcha [(ngModel)]="formModel.captcha" name="captcha" required siteKey="YOUR_SITE_KEY"></re-captcha>
</form>`,
})
export class MyForm {
formModel = new MyFormModel();
}
```
A similar approach can be taken for reactive forms:
```typescript
@Component({
selector: "my-reactive-form",
template: `
<form [formGroup]="reactiveForm">
<re-captcha formControlName="recaptchaReactive"></re-captcha>
<button [disabled]="reactiveForm.invalid">Submit</button>
</form>
`,
})
export class MyReactiveForm {
reactiveForm: FormGroup;
ngOnInit() {
this.reactiveForm = new FormGroup({
recaptchaReactive: new FormControl(null, Validators.required),
});
}
}
```
### <a name="example-invisible"></a>Working with invisible reCAPTCHA [(see in action)](https://dethariel.github.io/ng-recaptcha/invisible)
Working with [invisible reCAPTCHA](https://developers.google.com/recaptcha/docs/invisible) is almost the same as with regular one.
First, you need to provide the right size:
```html
<re-captcha size="invisible" ...></re-captcha>
```
You will also need to invoke the [`"execute()"`](https://developers.google.com/recaptcha/docs/invisible#programmatic_execute) method manually. This can be done by either obtaining a reference to `RecaptchaComponent` via `@ViewChild()`, or by using inline template reference:
```html
<re-captcha #captchaRef="reCaptcha" ...></re-captcha>
...
<button (click)="captchaRef.execute()">Submit</button>
```
Normally you would only submit a form when recaptcha response has been received. This can be achieved by reacting to `(resolved)` event and invoking submit logic when the captcha response is truthy (this will not try to submit the form when recaptcha response has expired). A sample implementation would look like this:
```typescript
@Component({
selector: "my-form",
template: ` <form>
<re-captcha
#captchaRef="reCaptcha"
siteKey="YOUR_SITE_KEY"
size="invisible"
(resolved)="$event && submit($event)"
></re-captcha>
<button (click)="captchaRef.execute()">Submit</button>
</form>`,
})
export class MyForm {
public submit(captchaResponse: string): void {
this.http.post({
captcha: captchaResponse,
/* ... */
});
}
}
```
### <a name="example-resizing"></a>Resizing
Making reCAPTCHA responsive is sometimes necessary, especially when working with mobile devices. You can use css-transforms to achieve that as in [this StackOverflow answer](https://stackoverflow.com/a/29521983/2645305), which is also ell-described in [this blog post](https://geekgoddess.com/how-to-resize-the-google-nocaptcha-recaptcha/). You can also take a look at a [live example](https://stackblitz.com/edit/ng-recaptcha-example-uncvxq?file=src/app/app.component.html) of how this might be implemented. This boils down to
```html
<div style="transform:scale(0.7);transform-origin:0;">
<re-captcha></re-captcha>
</div>
```
### <a name="example-systemjs"></a>SystemJS configuration
To configure the package to work with SystemJS, you would configure it approximately like that (assuming you've installed `ng-recaptcha` using `npm`):
```javascript
// SystemJS config file
(function () {
System.config({
paths: {
"npm:": "/node_modules/",
},
map: {
"ng-recaptcha": "npm:ng-recaptcha",
},
packages: {
"ng-recaptcha": { main: "./index.js" },
},
});
})();
```
### <a name="example-different-url"></a>Loading from a different location
Since `"google.com"` domain might be unavailable in some countries, reCAPTCHA core team has a solution for that - using `"recaptcha.net"` domain. You can configure the component to use that by using the `onBeforeLoad` hook of `RECAPTCHA_LOADER_OPTIONS`, for example:
```javascript
import { RECAPTCHA_LOADER_OPTIONS } from "ng-recaptcha";
@NgModule({
providers: [
{
provide: RECAPTCHA_LOADER_OPTIONS,
useValue: {
onBeforeLoad(_url) {
return {
url: new URL("https://www.recaptcha.net/recaptcha/api.js"), // use recaptcha.net script source for some of our users
};
},
},
},
],
})
export class MyModule {}
```
### <a name="example-csp-nonce"></a>Specifying nonce for Content-Security-Policy
Per [reCAPTCHA FAQ on CSP](https://developers.google.com/recaptcha/docs/faq#im-using-content-security-policy-csp-on-my-website-how-can-i-configure-it-to-work-with-recaptcha), the recommended approach for that is to supply nonce to the script tag. This is possible by providing the nonce as part of the `onBeforeLoad` hook of `RECAPTCHA_LOADER_OPTIONS`, for example
```javascript
import { RECAPTCHA_LOADER_OPTIONS } from "ng-recaptcha";
@NgModule({
providers: [
{
provide: RECAPTCHA_LOADER_OPTIONS,
useValue: {
onBeforeLoad(_url) {
return {
url,
nonce: "<YOUR_NONCE_VALUE>",
};
},
},
},
],
})
export class MyModule {}
```
### <a name="example-v3-all-actions"></a>Listening for all actions with reCAPTCHA v3
More often than not you will need to only get a reCAPTCHA token with the action the user is currently taking, and submit it to the backend at that time. However, having a single listener for all events will be desirable.
There is an `Observable` exactly for that purpose: `ReCaptchaV3Service.onExecute`. It emits a value every time a token is received from reCAPTCHA. The shape of payload it operates on is defined via `OnExecuteData` interface:
```ts
interface OnExecuteData {
action: string;
token: string;
}
```
where `action` is the name of the action that has been executed, and `token` is what reCAPTCHA v3 provided when executing that action.
Here's how you would potentially set this up:
```ts
import { OnExecuteData, ReCaptchaV3Service } from "ng-recaptcha";
@Component({
selector: "my-component",
templateUrl: "./v3-demo.component.html",
})
export class MyComponent implements OnInit, OnDestroy {
private subscription: Subscription;
constructor(private recaptchaV3Service: ReCaptchaV3Service) {}
public ngOnInit() {
this.subscription = this.recaptchaV3Service.onExecute.subscribe((data: OnExecuteData) => {
this.handleRecaptchaExecute(data.action, data.token);
});
}
public ngOnDestroy() {
if (this.subscription) {
this.subscription.unsubscribe();
}
}
}
```
There are a couple things to keep in mind:
- `onExecute` will trigger for **all** actions. If you only need to bulk-process some actions, and not others - you will have to apply filtering yourself.
- `onExecute` observable will provide you with all the events emitted **after** you have subscribed to it - it doesn't keep references to the previously emitted actions. So make sure you add such a subscription as early in your code as you feel is necessary.
- `onExecute` does not emit anything for when a `grecaptcha` error occurs. Use `onExecuteError` Observable for that.
### <a name="async-config-load"></a>Loading reCAPTCHA keys asynchronously
If your use-case needs to load the reCAPTCHA v2/v3 key from the backend (as opposed to specifying it in-code during build time), the Angular-idiomatic way to do that is by relying on [`APP_INITIALIZER`](https://angular.io/api/core/APP_INITIALIZER). You can find an example of how this could look like below, and you can also consult the source code for the demo site.
```ts
// config.service.ts
import { Injectable } from "@angular/core";
@Injectable({
providedIn: "root",
})
export class ConfigService {
public recaptchaSiteKeyV2: string | null = null;
public recaptchaSiteKeyV3: string | null = null;
public async loadConfig(): Promise<void> {
const { siteKeyV2, siteKeyV3 } = await fetchConfig(/* some API call */);
this.recaptchaSiteKeyV2 = siteKeyV2;
this.recaptchaSiteKeyV3 = siteKeyV3;
}
}
// app.module.ts
import { APP_INITIALIZER, NgModule } from "@angular/core";
import { RECAPTCHA_SETTINGS, RecaptchaSettings, RECAPTCHA_V3_SITE_KEY } from "ng-recaptcha";
import { ConfigService } from "./config.service";
function appLoadFactory(config: ConfigService) {
return () => config.loadConfig().then(() => console.log(`config resolved`, config));
}
@NgModule({
providers: [
{
provide: RECAPTCHA_V3_SITE_KEY,
useFactory: (config: ConfigService) => {
return config.recaptchaSiteKeyV3;
},
deps: [ConfigService],
},
{
provide: RECAPTCHA_SETTINGS,
useFactory: (config: ConfigService): RecaptchaSettings => {
return { siteKey: config.recaptchaSiteKeyV2 };
},
deps: [ConfigService],
},
{
provide: APP_INITIALIZER,
useFactory: appLoadFactory,
deps: [ConfigService],
multi: true,
},
],
})
export class AppModule {}
```
### <a name="hide-recaptcha-badge"></a>Hiding reCAPTCHA badge
To start with, this is not strictly under `ng-recaptcha` library control.
However, there is a way of doing so (albeit subject to certain conditions).
Please refer to the [FAQ section of reCAPTCHA documentation](https://developers.google.com/recaptcha/docs/faq#id-like-to-hide-the-recaptcha-badge.-what-is-allowed) to get an idea of what you're required to do.