Developer's Guide

Advanced Setup

You can take more control over how FunCaptcha by manually setting up FunCaptcha in Javascript.

 

Add the following code within your <head> tag, with the onload variable being the name of the function you would like to call to setup FunCaptcha:


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

Add the following script into your page, we recommend just before the closing <body> tag:


<script type="text/javascript">
    function loadFunCaptcha() {
        new FunCaptcha({
            public_key: "_YOUR_PUBLIC_KEY_",
            target_html: "CAPTCHA",
            callback: function() {
                console.log("played");
            }
        });
    }
</script>
        

In this example the function called “loadFunCaptcha” is called, which creates a new FunCaptcha object with a range of custom values passed into it.

 

These are all of the current FunCaptcha setup settings:

  • public_key – required – Your public key to authenticate with our server. Found in your FunCaptcha account settings.
  • target_html – optional – defaults to ‘funcaptcha’. This is an ID or class of where you want FunCaptcha to be loaded on the page.
  • callback – optional – A function that will be called when FunCaptcha has been solved by the user.
  • language – optional – HTML ISO language paramater to lock FunCaptcha. If not set, FunCaptcha will automatically translate based on the users language. FunCaptcha supports a growing number of languages.
 

Add the following to the form where you would like FunCaptcha to appear:.


<div id="CAPTCHA"></div>
                                    
 

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 = "_PRIVATE_KEY_HERE_";
$session_token = $_POST["fc-token"];
$fc_api_url = "https://funcaptcha.com/fc/v/?private_key=".$private_key."&session_token=".$session_token;
$fc_results = json_decode(file_get_contents($fc_api_url)); //the api returns a JSON result
if (isset($fc_results->solved) && $fc_results->solved == true) {
    //valid, the user has solved FunCaptcha correctly
} else {
    //invalid, the user has failed FunCaptcha and should be prompted to try it again
}
                                    

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 = "_PRIVATE_KEY_HERE_";
    $session_token = $_POST["fc-token"];
    $fc_api_url = "https://funcaptcha.com/fc/v/?private_key=".$private_key."&session_token=".$session_token;
    $fc_results = json_decode(file_get_contents($fc_api_url)); //the api returns a JSON result
    if ($fc_results->solved == true) {
        //valid, the user has solved FunCaptcha correctly
        echo "Solved";
    } else {
        //invalid, the user has failed FunCaptcha and should be prompted to try it again
        echo "Please try again";
    }
}
?>
<html>
<head>
    <script src="https://funcaptcha.com/fc/api/?onload=loadFunCaptcha" async defer></script>
    <script type="text/javascript">
    function loadFunCaptcha() {
        new FunCaptcha({
            public_key: "_PUBLIC_KEY_HERE_",
            target_html: "CAPTCHA",
            callback: function() {
                console.log("played");
            }
        });
    }
</script>
</head>
    <body>
        <form method="post">
            <label for="name">Name</label>
            <input type="text" name="name">
            <div id="CAPTCHA"></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
 

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:


var funcaptcha;
function loadFunCaptcha() {
funcaptcha = new FunCaptcha({
        public_key: "_YOUR_PUBLIC_KEY_",
        target_html: "funcaptcha-container",
        callback: function() { console.log("played") }
    });
}
// now you may call the refresh function using the variable
funcaptcha.refresh_session();
                                    

This will regenerate the session and reload the FunCaptcha.