README.md

🤖 Friendly Captcha Verification API Client

This client library allows JVM-based applications to verify Friendly Captcha puzzle solutions. It wraps the necessary call and interprets the result.

• Easy to use (see example below)
• Compatible with JVM-based applications (Java, Groovy, Kotlin, Scala, Clojure)
• Only two dependencies: Jackson and SLF4J

🔧 Usage

Include the dependency using Maven

<dependency>
  <groupId>org.drjekyll</groupId>
  <artifactId>friendlycaptcha</artifactId>
  <version>2.0.9</version>
</dependency>

or Gradle with Groovy DSL:

implementation 'org.drjekyll:friendlycaptcha:2.0.9'

or Gradle with Kotlin DSL:

implementation("org.drjekyll:friendlycaptcha:2.0.9")

Run your build tool and you can include the verifier as follows:

import org.drjekyll.friendlycaptcha.FriendlyCaptchaVerifier;

public class FriendlyCaptchaExample {

  private final FriendlyCaptchaVerifier friendlyCaptchaVerifier = FriendlyCaptchaVerifier
    .builder()
    .apiKey("YOUR_API_KEY")
    .sitekey("AN_OPTIONAL_SITE_KEY")
    .build();

  public void checkSolution(String solution) {

    boolean success = friendlyCaptchaVerifier.verify(solution);
    if (success) {
      // continue
    } else {
      // stop processing
    }

  }

}

Or Kotlin:

class FriendlyCaptchaExample {
  private val friendlyCaptchaVerifier: FriendlyCaptchaVerifier = FriendlyCaptchaVerifier
    .builder()
    .apiKey("YOUR_API_KEY")
    .sitekey("AN_OPTIONAL_SITE_KEY")
    .build()

  fun checkSolution(solution: String?) {
    val success: Boolean = friendlyCaptchaVerifier.verify(solution)
    if (success) {
      // continue
    } else {
      // stop processing
    }
  }
}

On a non-successful response, verify throws a FriendlyCaptchaException containing either the response details or a description of the error.

⚙️ Verifier Parameters

The Friendly Captcha Verifier currently supports the following builder methods:

• .apiKey(...) An API key that proves it's you, create one on the Friendly Captcha website
• .objectMapper(...) If you would like to use an existing or custom object mapper
• .verificationEndpoint(...) An URI object that can point to another verification endpoint (for example if you would like to use EU hosts). Default is: https://api.friendlycaptcha.com/api/v1/siteverify
• .connectTimeout(...) allows you to change the default connection timeout of 10 seconds. 0 is interpreted as infinite, null uses the system default
• .socketTimeout(...) allows you to change the default socket timeout of 10 seconds. 0 is interpreted as infinite, null uses the system default
• .sitekey(...) is an optional sitekey that you want to make sure the puzzle was generated from.
• .proxyHost(...) The hostname or IP address of an optional HTTP proxy. proxyPort must be configured as well
• .proxyPort(...) The port of an HTTP proxy. proxyHost must be configured as well.
• .proxyUserName(...) If the HTTP proxy requires a user name for basic authentication, it can be configured with this method. Proxy host, port and password must also be set.
• .proxyPassword(...) The corresponding password for the basic auth proxy user. The proxy host, port and user name must be set as well.
• .verbose(...) logs detailed information using INFO level

🧑‍🏭 Development

To build and locally install the library and run the tests, just call

mvn install

🤝 Contributing

Please read the contribution document for details on our code of conduct, and the process for submitting pull requests to us.

📓 Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

📜 License

This project is licensed under the LGPL License - see the license file for details.

📢 Release Notes

2.0.2 -- 2.0.9

Dependency updates

2.0.1

Got rid of HTTP client dependency. Apache HTTP Client is no longer needed.

1.2.1 / 1.2.2

• Update dependencies

1.2.0

• Add verbose logging

1.1.0

• Add proxy authentication

1.0.0

• Initial version