Ng2-google-recaptcha NPM

Build Status

Master Branch

Develop Branch

Overview

An Angular module implementing Google's reCAPTCHA that actually works, requires no additional dependancies and only needs a single import.

npm.io

Dependancies

Currently built against Angular ^5.2.3 and Typescript ^2.6.2

ng2-google-recaptcha has the following additional dependancies

TsLerp: Typescript library for lerping single and multi-sample data sets over time

Installation

Add the package to your 'dependencies' list in package.json and run npm install
"ng2-google-recaptcha": "^5.0.0"
Optionally, you can manually install the package using the npm command line
npm install ng2-google-recaptcha --save

Add ng2-google-recaptcha to both your map and packages structures in systemjs.config.js

var map = {
  ...
  'ng2-google-recaptcha': 'node_modules/ng2-google-recaptcha'
};

var packages = {
  ...
  'ng2-google-recaptcha': { main: 'index.js', defaultExtension: 'js' },
};

Optionally, add the rootDir option to tsconfig.json to make sure TypeScript's default root path algorithm doesn't pull in the node_modules folder

Usage

Importing The 'ng2-google-recaptcha' Module

To use ng2-google-recaptcha, you need to import the Ng2GoogleRecaptchaModule into the relevent module in your application. In the sample application this is done in the entry module - app.module.ts

import { NgModule }      from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { Ng2GoogleRecaptchaModule }  from 'ng2-google-recaptcha';

@NgModule({
    imports: [
        BrowserModule,
        Ng2GoogleRecaptchaModule,
    ],

    bootstrap: [
        AppComponent,
    ],
})
export class AppModule { }

Adding a reCAPTCHA

To add a reCAPTCHA all you need is to link to Google's reCAPTCHA script, a site key, and a response callback.

Add the following to your <head> tag in your main HTML page

<script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit" async defer></script>

The following is the most basic component to implement the reCAPTCHA

@Component({
    template: `<ng2-google-recaptcha 
                  [siteKey]="recaptchaSiteKey" 
                  (onCaptchaComplete)="onCaptchaComplete($event)">
               </ng2-google-recaptcha>`,
})
export class BasicComponent {

	private recaptchaSiteKey = 'YOUR-RECAPTCHA-SITE-KEY-HERE';

	private onCaptchaComplete(response: any) {
        console.log('reCAPTCHA response recieved:');
        console.log(response.success);
        console.log(response.token);
    }
}

Once BasicComponent.onCaptchaComplete is called, the response element will contain the following attributes

success: True is the request succeeded, False otherwise
token: The validation token which can be used to validate the users response
recaptcha: The ng2-google-recpatcha instance this response was generated on

If the users response times out, BasicComponent.onCaptchaComplete will be automatically called with a failed response and a null token, requiring the user to restart the process.

Additional reCAPTCHA Options

When specifying <ng2-google-recaptcha> you can pass through the following additional properties

captchaStyle: An object containing the style of the reCAPTCHA to render (see the code example below)
renderDelay: A delay (in milliseconds) before the reCAPTCHA renders on screen (defaults to 500ms)
recaptchaId: When using multiple reCAPTCHA elements, a unique ID that identifies this element

@Component({
    template: `<ng2-google-recaptcha 
                  
                  [captchaStyle]="recaptchaStyle" 
                  [renderDelay]="delayToRender" 
                  [recaptchaId]="thisRecaptchaId" 
                  
                  [siteKey]="recaptchaSiteKey" 
                  
                  (onCaptchaComplete)="onCaptchaComplete($event)">
                  
               </ng2-google-recaptcha>`,
})
export class BasicComponent {

	private recaptchaSiteKey: string = 'YOUR-RECAPTCHA-SITE-KEY-HERE';

  private delayToRender: number = 1000; // A one second delay before rendering this element
  private thisRecaptchaId: string = 'this-is-my-unique-id'; // ID to uniquely identify this reCAPTCHA
  
  // Style to use - all properties are optional and the style can be ommitted completely
  private recaptchaStyle = {
        theme: 'dark',     // Uses the Dark theme for this reCAPTCHA
        type: 'audio',     // Use the audio version for user verification
        size: 'compact',   // Use the compact style 
        tabindex: 0,       // Tab Index for this element
  };
  
  

	private onCaptchaComplete(response: string) {
        console.log('reCAPTCHA response recieved:');
        console.log(response);
    }
}

Resetting a reCAPTCHA

If you require the user to redo the reCAPTCHA, you can call resetRecaptcha which will reload the reCAPTCHA and call the onCaptchaComplete callback with a null token allowing it to be reset.

@Component({
  // ...
})
export class BasicComponent {

  // How you get hold of the reCAPTCHA instance is up to you
  @ViewChild(CreateRecaptchaComponent)
  private recaptchaInstance: CreateRecaptchaComponent;

  // Function called after we have used the reCAPTCHA token
  private serverResponse() {
    // ...

    // If we received an error requiring the reCAPTCH to be done again,
    // reset the element causing the previous token to be reset
    recaptchaInstance.resetRecaptcha();

    // ...
  }

}

Building and Running the Sample Application

Check out the repository, browse to the './samples' folder and run npm install to install all the required dependancies.

Note: Running npm install on the sample project requires that Python 2.7.x is available on the command line as it runs a couple of Python scripts to correctly set up the npm_modules folder.

ng2-google-recaptcha is developed in Visual Studio Code so once npm install has finished you should be able to open the './samples' folder in VS Code and it will run out of the box (by default it uses lite-server which is installed as part of npm install).

If you are not using Visual Studio Code, browse to the './samples' folder and run tsc to build the application. Then open your local server of choice pointing to ./samples as the root directory.