Developer's Guide

Standard Setup

Add this between your <head> tags:


<script src="https://funcaptcha.com/fc/api/" async defer></script>
        
 

Add this between your <form> tags:


<div id="funcaptcha" data-pkey="_YOUR_PUBLIC_KEY_"></div>
        
 

Replace _YOUR_PUBLIC_KEY_ with your public key from your Site Settings.

 

Validate FunCaptcha from your server using one of the methods below:

 

In your PHP code where you are validating your form, you will need to pass your private key and the value of “fc-token” to the FunCaptcha API server either via POST or GET:


$private_key = "_YOUR_PRIVATE_KEY_";
$session_token = $_POST["fc-token"];
$fc_api_url = "https://funcaptcha.com/fc/v/?private_key=".$private_key."&session_token=".$session_token."&simple_mode=1";
if (file_get_contents($fc_api_url) === "1") {
    //valid, the user has solved FunCaptcha correctly
} else {
    //invalid, the user has failed FunCaptcha
}
                                    

Then, replace the commented out sections with the code you want to execute on FunCaptcha being correctly solved — Done!

 

View Example


<?php
if ($_POST) {
    $private_key = "_YOUR_PRIVATE_KEY_";
    $session_token = $_POST["fc-token"];
    $fc_api_url = "https://funcaptcha.com/fc/v/?private_key=".$private_key."&session_token=".$session_token."&simple_mode=1";
    if (file_get_contents($fc_api_url) === "1") {
        //valid, the user has solved FunCaptcha correctly
    } else {
        //invalid, the user has failed FunCaptcha
    }
}
?>
<html>
<head>
<script src="https://funcaptcha.com/fc/api/" async defer></script>
</head>
    <body>
        <form method="post">
            <div id="funcaptcha" data-pkey="_YOUR_PUBLIC_KEY_"></div>
            <input type="submit">
        </form>
    </body>
</html>
                                        

CURL Alternative


$private_key = "_YOUR_PRIVATE_KEY_";
$session_token = $_POST["fc-token"];
$fc_api_url = "https://funcaptcha.com/fc/v/?private_key=".$private_key."&session_token=".$session_token."&simple_mode=1";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $fc_api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$output = curl_exec($ch);
curl_close($ch);

if ($output === "1") {
    //valid, the user has solved FunCaptcha correctly
} else {
    //invalid, the user has failed FunCaptcha
}
    

In your Java code where you are validating your form, you will need to pass your private key and the value of “fc-token” to the FunCaptcha API server either via POST or GET:


String private_key = "_YOUR_PRIVATE_KEY_";
URL url = new URL("https://funcaptcha.com/fc/v/?private_key="+private_key+"&session_token="+request.getParameter("fc-token")+"&simple_mode=1");
BufferedReader reader = new BufferedReader(new InputStreamReader(url.openStream(), "UTF-8"));
String result = reader.readLine();
if (result.equals("1")) {
    //valid, the user has solved FunCaptcha correctly
} else {
    //invalid, the user has failed FunCaptcha
}
    

You will need to import the following Java libraries for the above example:

  • java.net.URL
  • java.io.BufferedReader
  • java.io.InputStreamReader

Then, replace the commented out sections with the code you want to execute on FunCaptcha being correctly solved — Done!

 

View Example


<%@page import="java.net.URL"%>
<%@page import="java.io.BufferedReader"%>
<%@page import="java.io.InputStreamReader"%>
<%
    boolean solved = false;
    if (request.getParameter("fc-token") != null) {
        String private_key = "_YOUR_PRIVATE_KEY_";
        URL url = new URL("https://funcaptcha.com/fc/v/?private_key="+private_key+"&session_token="+request.getParameter("fc-token")+"&simple_mode=1");
        BufferedReader reader = new BufferedReader(new InputStreamReader(url.openStream(), "UTF-8"));
        String result = reader.readLine();
        if (result.equals("1")) {
            //valid, the user has solved FunCaptcha correctly
        } else {
            //invalid, the user has failed FunCaptcha
        }
    }
%>
<html>
<head>
<script src="https://funcaptcha.com/fc/api/" async defer></script>
</head>
    <body>
        <form method="post">
            <div id="funcaptcha" data-pkey="_YOUR_PUBLIC_KEY_"></div>
            <input type="submit">
        </form>
    </body>
</html>
                                        

In your .Net code where you are validating your form (most likely within your controller), you will need to pass your private key and the value of “fc-token” to the FunCaptcha API server either via POST or GET:


const string privateKey = "_YOUR_PRIVATE_KEY_";
string sessionToken = Request.Form["fc-token"];
string url = string.Format("https://funcaptcha.com/fc/v/?private_key={0}&session_token={1}&simple_mode=1", privateKey, sessionToken);
if (new WebClient().DownloadString(url) == "1") {
    //valid, the user has solved FunCaptcha correctly
} else {
    //invalid, the user has failed FunCaptcha
}
    

Then, replace the commented out sections with the code you want to execute on FunCaptcha being correctly solved — Done!

 

View Example

You can also download a sample full project that demonstrates FunCaptcha validation using the Razor markup language.

In your server code, after the user has submitted the form, do a GET request with the fc-token response (which is embedded within the form) while passing up your private key (also from your account dashboard) to check if the user solved correctly.


https://funcaptcha.com/fc/v/?private_key=_YOUR_PRIVATE_KEY&session_token=_VALUE_OF_fc-token_&simple_mode=1
    

Using simple_mode=1 makes the response only return 1 if solved correctly, otherwise false. Without this set, you will get more information, such as the users IP address and other details from the FunCaptcha game session.

 

FunCaptcha Verify Possible Results

If you include the value of “simple_mode=1” on your validation call, the server will return null/empty on failure and a simple “1” on success. If you exclude that, it will return a full JSON response with the below possible values.

 
Key Eg. Value Optional Description Other
solved TRUE/FALSE No If set to true, the user has successfully completed FunCaptcha. This will always be accurate and takes into account any of the below fields automatically. This is the primary value you want to check.
score 0 No Always 0 for now, may be used in future.
user_ip 163.207.150.119 No The IP Address of the user who solved FunCaptcha.
Other These values are additional information and are always stored within "Other".
session 957585b3a141993c8.64352582 No The FunCaptcha session token. This is always set and always unique. This can be shared with the FunCaptcha team for us to look into more detailed logs, so you may want to store/log this value.
time_verified 1482373662 No Unix Timestamp of when FunCaptcha was verified with our server as solved or not.
attempted FALSE Yes If the user didn't interact with FunCaptcha but it was submitted for verification. For example if the user hit submit on your form without solving FunCaptcha first.
previously_verified TRUE Yes If this session had previously been validated. Sessions can only be validated once and will always return solved:false with this added if previously verified. Prevents replay attacks.
session_timed_out TRUE Yes Sessions can only live for a certain time, by default 30 minutes. If you attempt to validate a timed out session, it will fail and require the user to solve again.
suppressed TRUE Yes FunCaptcha was not shown due to users prior history.
suppress_limited TRUE Yes Suppress mode would have shown, except user hit internal rate limits
session_created 2017-10-24T22:44:17+00:00 Yes When the public key was passed to the API and FunCaptcha loads on the page.
check_answer 2017-10-24T22:44:24+00:00 Yes When the user last submitted an answer to a security challenge (null if no answer provided).
verified 2017-10-24T22:44:26+00:00 Yes When the private key validated the game as solved.
 

Refreshing FunCaptcha Sessions

You can also recreate a new FunCaptcha session using Javascript if the old session is invalid, such as if you are using AJAX to submit your form, but the server response was incorrect. FunCaptcha sessions can only be checked to the API server once. To do this, run the following:


<script>
FunCaptcha();
</script>
                                    

This will regenerate the session and reload the FunCaptcha.

 

Manually Setting Language

FunCaptcha by default will automatic show language based on the users browser prefrences. If you would like to manually force a language to show, you can pass it in as part of the script URL in the HTML ISO format:


<script src="https://funcaptcha.com/fc/api/?language=ar" async="" defer="defer"></script>
    

This example will show FunCaptcha in the Arabic language. FunCaptcha supports a growing number of languages. If we do not support a language it will display in English. If there is a language you need supported please contact us and we can add it.