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. Process 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 by 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 the CAPTCHA page, 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 CAPTCHA completion token.
   • onChallengeVisible(): Opening the challenge pop-up window.
   • onChallengeHidden(): Closing the 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("CAPTCHA_page_URL?sitekey=<client_side_key>&invisible=true")
   

   Where:

   • sitekey: Client key you got earlier.
   • invisible=true: Switching CAPTCHA to invisible mode.

4. Add the created JavaScript Interface object to the WebView. Specify NativeClient (which is the name the web page will use to send messages via a callback function) as the second parameter:

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

Process the event that triggered a CAPTCHA challenge to the userProcess the event that triggered a CAPTCHA challenge to the user

1. Specify the WebView display logic using the onChallengeVisible() method. It is called when the CAPTCHA displays a challenge to the user.

   Here is an example involving visibility switching (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 will invoke the onChallengeHidden() method that hides WebView.

   Example of WebView returning to View.GONE:

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

Retrieve the CAPTCHA test resultsRetrieve the CAPTCHA test results

1. Save the CAPTCHA verification passed token. It will be returned in the onGetToken(token: String) method after the service processes an attempt.

2. To validate the token, send a POST request to https://smartcaptcha.yandexcloud.net/validate, providing the following parameters in x-www-form-urlencoded format:

   • 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 end up in the Android app itself.

   Request example:

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

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

   Here is an example:

   • It is a human:

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

   • It is a robot:

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

Things to considerThings to consider

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.