Friendly Captcha Python SDK

A Python client for the Friendly Captcha service. This client allows for easy integration and verification of captcha responses with the Friendly Captcha API.

This library is for Friendly Captcha V2 only. If you are looking for V1, look here

Installation

pip install friendly-captcha-client

Usage

Below are some basic examples of how to use the client.

For a more detailed example, take a look at the example directory.

Initialization

To start using the client:

from friendly_captcha_client.client import FriendlyCaptchaClient

client = FriendlyCaptchaClient(
    api_key="YOUR_API_KEY",
    sitekey="YOUR_SITEKEY"
)

Verifying a Captcha Response

After calling verify_captcha_response with the captcha response there are two functions on the result object that you should check:

• was_able_to_verify indicates whether we were able to verify the captcha response. This will be False in case there was an issue with the network/our service or if there was a mistake in the configuration.
• should_accept indicates whether the captcha response was correct. If the client is running in non-strict mode (default) and was_able_to_verify returned False, this will be True.

Below are some examples of this behaviour.

Verifying a correct captcha response without issues when verifying:

result = client.verify_captcha_response("CORRECT?CAPTCHA_RESPONSE_HERE")
print(result.was_able_to_verify) # True
print(result.should_accept) # True

Verifying an incorrect captcha response without issues when verifying:

result = client.verify_captcha_response("INCORRECT_CAPTCHA_RESPONSE_HERE")
print(result.was_able_to_verify) # True
print(result.should_accept) # False

Verifying an incorrect captcha response with issues (network issues or bad configuration) when verifying in non-strict mode (default):

result = client.verify_captcha_response("INCORRECT_CAPTCHA_RESPONSE_HERE")
print(result.was_able_to_verify) # False
print(result.should_accept) # True

Network errors don't raise an exception. Check result.error.error_code for request_failed or request_failed_due_to_timeout.

Verifying an incorrect captcha response with issues (network/service issues or bad configuration) when verifying in strict mode:

client.strict = True
result = client.verify_captcha_response("INCORRECT_CAPTCHA_RESPONSE_HERE")
print(result.should_accept)  # False
print(result.was_able_to_verify)  # False

Risk Intelligence Data Retrieval

Use retrieve_risk_intelligence to retrieve risk intelligence data from a token.

result = client.retrieve_risk_intelligence("RISK_INTELLIGENCE_TOKEN_HERE")
if not result.was_able_to_retrieve:
    # handle request/client error, inspect result.error
    return
if not result.is_valid:
    # handle invalid token, inspect result.error
    return
print(result.data.risk_intelligence)  # The risk intelligence data

Configuration

The client offers several configuration options:

• api_key: Your Friendly Captcha API key.
• sitekey: (Optional) Your Friendly Captcha sitekey. Configure this if you want to ensure that a captcha solution or risk intelligence token was generated from a specific sitekey.
• strict: (Optional) In case the client was not able to verify the captcha response at all (for example if there is a network failure or a mistake in configuration), by default the verify_captcha_response returns True regardless. By passing strict=True, it will return False instead: every response needs to be strictly verified.
• api_endpoint: (Optional) Base API endpoint (for example https://eu.frcapi.com). Shorthands eu or global are also accepted. Default is global.
• siteverify_endpoint: (Optional,Deprecated) Kept for backwards compatibility, use api_endpoint instead. Accepts a full siteverify URL or shorthands eu/global; path is stripped and converted to api_endpoint.
• verbose: (Optional) Default is False. Turn on basic logging.
• Error Handling: The client has built-in error handling mechanisms. In case of unexpected responses or errors from the Friendly Captcha API, the client will log the error and provide a default response.

Development

To install it locally:

pip install -e .
pip install -r requirements-dev.txt

Run the tests:

# Run the unit tests
python -m pytest

# Run the SDK integration tests (requires that you have the SDK test mock server running)
docker run -p 1090:1090 friendlycaptcha/sdk-testserver:latest
python -m pytest integration_tests

License

Open source under MIT.