Updating the README.md.

Author: jooni91

README.md

@@ -1,7 +1,7 @@
-# ASP.NET Core reCAPTCHA
-A Google reCPATCHA validation wrapper service for ASP.NET Core. With only a few simple setup steps you are ready to block bots from filling in and submitting forms on your website.
+# ASP.NET Core reCAPTCHA
+A Google reCAPTCHA validation wrapper service for ASP.NET Core. In only a few simple steps, you are ready to block bots from filling in and submitting forms on your website with reCAPTCHA.
 
-This package also supports reCAPTCHA V3, but at the moment does not provide any frontend tag helpers for that. So only backend validation is supported at the moment.
+The package supports V2 and V3 and comes with tag helpers that make it easy to add challenges to your forms. Also, backend validation is made easy and requires only the use of an attribute in your controllers or actions that should get validated.
 
 [![Build Status](https://dev.azure.com/griesingersoftware/ASP.NET%20Core%20Recaptcha/_apis/build/status/jgdevlabs.aspnetcore-recaptcha?branchName=master)](https://dev.azure.com/griesingersoftware/ASP.NET%20Core%20Recaptcha/_build/latest?definitionId=17&branchName=master)
 [![Build Status](https://vsrm.dev.azure.com/griesingersoftware/_apis/public/Release/badge/f9036ec9-eb1c-4aff-a2b8-27fdaa573d0f/1/2)](https://vsrm.dev.azure.com/griesingersoftware/_apis/public/Release/badge/f9036ec9-eb1c-4aff-a2b8-27fdaa573d0f/1/2)
@@ -13,16 +13,19 @@ This package also supports reCAPTCHA V3, but at the moment does not provide any
 
 Install via [NuGet](https://www.nuget.org/packages/Griesoft.AspNetCore.ReCaptcha/) using:
 
-``PM> Install-Package Griesoft.AspNetCore.ReCaptcha``
+`PM> Install-Package Griesoft.AspNetCore.ReCaptcha`
 
 ## Quickstart
 
-The first thing you need to do is to sign up for a new API key-pair for your project. You can follow [Google's guide](https://developers.google.com/recaptcha/intro#overview), if you haven't done that yet.
+### Prequisites
+You will need an API key pair which can be acquired by [signing up here](http://www.google.com/recaptcha/admin). For assistance or other questions regarding that topic, refer to [Google's guide](https://developers.google.com/recaptcha/intro#overview).
 
-After sign-up you should now have a **Site key** and a **Secret key**. Make note of those, you will need them for the next step.
+After sign-up, you should have a **Site key** and a **Secret key**. You will need those to configure the service in your app.
 
 ### Configuration
 
+#### Settings
+
 Open your `appsettings.json` and add the following lines:
 
 ```json
@@ -31,41 +34,57 @@ Open your `appsettings.json` and add the following lines:
     "SecretKey": "<Your secret key goes here>"
 }
 ```
+**Important:** The `SiteKey` will be exposed to the public, so make sure you don't accidentally swap it with the `SecretKey`.
 
-Make sure to place your site & secret key in the right spot. You risk to expose your secret key to the public if you switch it with the site key.
+#### Service Registration
 
-For more inforamtion about ASP.NET Core configuration check out the [Microsoft docs](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1).
+Register this service by calling the `AddRecaptchaService()` method which is an extension method of `IServiceCollection`. For example:
 
-In your `Startup.cs` you now need to add the service. Add the following line `services.AddRecaptchaService();` into the `ConfigureServices(IServiceCollection services)` method, like this for excample.
+##### .NET 6
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddRecaptchaService();
+```
+
+##### Prior to .NET 6
 
 ```csharp
 public void ConfigureServices(IServiceCollection services)
 {
-    // Add other services here
-    
     services.AddRecaptchaService();
-    
-    // Add other services here
 }
 ```
 
-### Adding a reCAPTCHA element on your view
+### Adding a reCAPTCHA element to your view
 
-First you will need to import the tag helpers. Open your `_ViewImports.cshtml` file and add the following lines:
+First, import the tag helpers. Open your `_ViewImports.cshtml` file and add the following lines:
 
 ```razor
 @using Griesoft.AspNetCore.ReCaptcha
-
 @addTagHelper *, Griesoft.AspNetCore.ReCaptcha
 ```
 
-Now you are ready to use the tag helpers in your views. Always add the `<recaptcha-script>` tag on the bottom of your view. This will render the script tag which will load the reCAPTCHA.js API.
+Next, you need to add the `<recaptcha-script>` to every view you intend to use the reCAPTCHA. That will render the API script. Preferably you would add this somewhere close to the bottom of your body element.
 
-Next you only need to add a `<recaptcha>` tag in your form and you are all set. This is the most simplest way of adding reCAPTCHA to your views. Now you only need to add backend validation to the controller of your view.
+Now you may add a reCAPTCHA challenge to your view where ever you need it. Using the `<recaptcha />` tag in your form will render a reCAPTCHA V2 checkbox inside it.
+
+For invisible reCAPTCHA use:
+```html
+<button re-invisible form-id="yourFormId">Submit</button>
+```
+
+For reCAPTCHA V3 use:
+```html
+<recaptcha-v3 form-id="yourFormId" action="submit">Submit</recaptcha-v3>
+```
 
 ### Adding backend validation to an action
 
-Add a using statement to `Griesoft.AspNetCore.ReCaptcha` in your controller. Next you just need to the `[ValidateRecaptcha]` attribute to the action which is triggered by your form.
+Validation is done by decorating your controller or action with `[ValidateRecaptcha]`.
+
+For example:
 
 ```csharp
 using Griesoft.AspNetCore.ReCaptcha;
@@ -75,25 +94,54 @@ namespace ReCaptcha.Sample.Controllers
 {
     public class ExampleController : Controller
     {
-        public IActionResult Index()
-        {
-            return View();
-        }
-
         [ValidateRecaptcha]
         public IActionResult FormSubmit(SomeModel model)
         {
-            // Will hit the next line only if validation was successfull
+            // Will hit the next line only if validation was successful
             return View("FormSubmitSuccessView");
         }
     }
 }
 ```
+Now each incoming request to that action will be validated for a valid reCAPTCHA token.
+
+The default behavior for invalid tokens is a 404 (BadRequest) response. But this behavior is configurable, and you may also instead request the validation result as an argument to your action. 
+
+This can be achieved like this:
+
+```csharp
+[ValidateRecaptcha(ValidationFailedAction = ValidationFailedAction.ContinueRequest)]
+public IActionResult FormSubmit(SomeModel model, ValidationResponse recaptchaResponse)
+{
+    if (!recaptchaResponse.Success)
+    {
+        return BadRequest();
+    }
+
+    return View("FormSubmitSuccessView");
+}
+```
+
+In case you are validating a reCAPTCHA V3 token, make sure you also add an action name to your validator.  
+
+For example:
+
+```csharp
+[ValidateRecaptcha(Action = "submit")]
+public IActionResult FormSubmit(SomeModel model)
+{
+    return View("FormSubmitSuccessView");
+}
+```
+
+## Options & Customization
 
-Now if validation would fail, the action method would never get called.
+There are global defaults that you may modify on your application startup. Also, the appearance and position of V2 tags may be modified. Either globally or each tag individually.
 
-You can configure that behaviour and a lot of other stuff globally at startup or even just seperatly for each controller or action.
+All options from the [official reCAPTCHA docs](https://developers.google.com/recaptcha/intro) are available to you in this package.
 
-### Addition information
+## Detailed Documentation
+Is on it's way...
 
-For more detailed usage guides check out the wiki. You can find guides about additional configuration options, response validation behaviour, explicit rendering of tags, invisible reCAPTCHA elements and the usage of reCAPTCHA V3.
+## Contributing
+Contributing is heavily encouraged. :muscle: The best way of doing so is by first starting a discussion about new features or improvements you would like to make. Or, in case of a bug, report it first by creating a new issue. From there, you may volunteer to fix it if you like. 😄