Invisible Yandex SmartCaptcha in Android apps

To embed invisible SmartCaptcha in an Android app:

1. Create JavaScript Interface.
2. Configure WebView to work with CAPTCHA.
3. Handle the event that triggered a CAPTCHA challenge to the user.
4. Retrieve the CAPTCHA test results.

Getting startedGetting started

1. Add HTML code to work with SmartCaptcha (or use a ready-made https://smartcaptcha.yandexcloud.net/webview).
2. Create a CAPTCHA following this guide.
3. Retrieve the CAPTCHA keys. Copy the Client key and Server key field values from the Overview tab of the CAPTCHA you created. You will need the Client key to load web pages using CAPTCHA and the Server key, to get the CAPTCHA test results.

Create a JavaScript InterfaceCreate a JavaScript Interface

1. Create a class to receive messages using a callback function from your web page with CAPTCHA.

2. Define the methods with @JavascriptInterface annotations:

   • onGetToken(token: String): Web page returns a token for passing CAPTCHA verification.
   • onChallengeVisible(): Opening the CAPTCHA challenge pop-up window.
   • onChallengeHidden(): Closing the CAPTCHA challenge pop-up window.

   class WebJsInterface {
   
       @JavascriptInterface
       fun onGetToken(token: String) {
           //your code
       }
   
       @JavascriptInterface
       fun onChallengeVisible() {
           //your code
       }
   
       @JavascriptInterface
       fun onChallengeHidden() {
           //your code
       }
   }
   

Configure WebView to work with CAPTCHAConfigure WebView to work with CAPTCHA

1. Create a WebView and add it to the screen.

2. Upload the URL of the web page with CAPTCHA to the WebView.

3. Add the query parameters to the URL:

     val webView = findViewById<WebView>(R.id.webViewCaptcha)
     webView.loadUrl("URL of the page with CAPTCHA?sitekey=<client_key>&invisible=true")
   

   Where:

   • sitekey: Previously obtained client key.
   • invisible=true: Switching CAPTCHA to invisible mode.

4. Add the created JavaScript Interface object to the WebView. Specify NativeClient as the second parameter (this is where the web page will send messages using a callback function):

     settings.javaScriptEnabled = true   // Enables Javascript execution
     addJavascriptInterface(WebJsInterface(), "NativeClient")
   

Handle the event that triggered a CAPTCHA challenge to the userHandle the event that triggered a CAPTCHA challenge to the user

1. Specify the WebView display logic using the onChallengeVisible() method. It is called once the CAPTCHA has shown a challenge to the user. Here is an implementation example of switching visibility (while the CAPTCHA was handling an action, the WebView status was View.GONE):

     val webView = activity.findViewById<WebView>(R.id.webViewCaptcha)
     webView.visibility = View.VISIBLE
   

2. Specify the logic for the event when the user fails a CAPTCHA challenge and collapses it. This calls the onChallengeHidden() method that hides the WebView. Example of the WebView returned to the View.GONE status:

     val webView = activity.findViewById<WebView>(R.id.webViewCaptcha)
     webView.visibility = View.GONE
   

Retrieve the CAPTCHA test resultsRetrieve the CAPTCHA test results

1. Save the token for passing CAPTCHA verification. It is returned in the onGetToken(token: String) method once the service handles an attempt.

2. To validate the token, send a GET request to https://smartcaptcha.yandexcloud.net/validate with the following parameters:

   • secret: Server key.
   • token: One-time token received after passing the check.
   • ip: IP address of the user that originated the request to validate the token. This is an optional parameter, but we ask you to provide the user IP when making requests. This helps improve SmartCaptcha performance.

   Note

   This logic must be implemented on the backend. Make sure the secret key does not get to the Android app.

   Sample request:

   https://smartcaptcha.yandexcloud.net/validate?secret=<server_key>&ip=<user_IP>&token=<token>
   

3. Get a server response. It contains a JSON object with the status and the message fields. For example:

   • It is a human:

     {
         "status": "ok",
         "message": ""
     }
     

   • It is a robot:

     {
         "status": "failed",
         "message": ""
     }
     

SpecificsSpecifics

Invisible CAPTCHA requires less memory than normal CAPTCHA because it does not load the code that renders the I’m not a robot button.

However, the widget loading time may vary for users. This is why we recommend warning users about the CAPTCHA to avoid any confusion while they are waiting.