UserDetect API

Service Features

Service Process

1. Your app integrates the Safety Detect SDK and calls the UserDetect API.
2. Safety Detect evaluates risks of the device running your app. If the risk level is medium or high, it asks the user to enter a verification code and sends a response token to your app.
3. Your app sends the response token to your app server.
4. Your app server sends the response token to the Safety Detect server to obtain the check result.

Use Cases

This API can help your app prevent fake user behavior, such as batch registration, credential stuffing attacks, activity bonus hunting, and content crawling.

App Development

Initializing UserDetect

private void initUserDetect() {
    // Replace with your activity or context as a parameter.
    SafetyDetectClient client = SafetyDetect.getClient(MainActivity.this);
    client.initUserDetect().addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void v) {
            // Indicates that communication with the service was successful.
        }
    }).addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(Exception e) {
            // An error occurred during communication with the service.
        }
    });
}

private fun initUserDetect() {
    // Replace with your activity or context as a parameter.
    val client = SafetyDetect.getClient(this@MainActivity)
    client.initUserDetect().addOnSuccessListener {
        // Indicates that communication with the service was successful.
    }.addOnFailureListener {
        // An error occurred during communication with the service.
    }
}

Calling the UserDetect API

To call the UserDetect API, perform the following steps:

1. Call the userDetection method of the UserDetect API to initiate a fake user detection request. The API will return a responseToken object.

   To initiate a detection request, you need to call the userDetection method. Generally, this method is triggered when a user touches a UI control (such as a button). To call the userDetection method, perform the following steps:

   1. Pass the applied appId as the input parameter of the method.
   2. Add the OnSuccessListener and OnFailureListener instances as listeners.
   3. Override onSuccess and onFailure to process the result.
   The sample code for calling this method is as follows:

   Java

   Kotlin

   Collapse

   Word wrap

   Dark theme

   Copy code

   public void onClick(View v) {
       SafetyDetectClient client = SafetyDetect.getClient(getActivity());
       String appId = "your_app_id";
       client.userDetection(appId)
               .addOnSuccessListener(new OnSuccessListener<UserDetectResponse>() {
                   @Override
                   public void onSuccess(UserDetectResponse userDetectResponse) {
                       // Indicates that communication with the service was successful.
                       String responseToken = userDetectResponse.getResponseToken();
                       if (!responseToken.isEmpty()) {
                           // Send the response token to your app server, and call the cloud API of HMS Core on your server to obtain the fake user detection result. 
                       }
                   }
               })
               .addOnFailureListener(new OnFailureListener() {
                   @Override
                   public void onFailure(Exception e) {
                       // An error occurred during communication with the service.
                       String errorMsg;
                       if (e instanceof ApiException) {
                           // An error with the HMS API contains some additional details.
                           // You can use the apiException.getStatusCode() method to get the status code.
                           ApiException apiException = (ApiException) e;
                           errorMsg = SafetyDetectStatusCodes.getStatusCodeString(apiException.getStatusCode()) + ": "
                                   + apiException.getMessage();
                       } else {
                           // Unknown type of error has occurred.
                           errorMsg = e.getMessage();
                       }
                       Log.i(TAG, "User detection fail. Error info: " + errorMsg);
                   }
               });
   }

   Collapse

   Word wrap

   Dark theme

   Copy code

   override fun onClick(v: View?) {
       val client = SafetyDetect.getClient(activity)
           val appId = "your_app_id"
           client.userDetection(appId)
               .addOnSuccessListener { userDetectResponse ->
                   // Indicates that communication with the service was successful.
                   val responseToken = userDetectResponse.responseToken
                   if (responseToken.isNotEmpty()) {
                       // Send the response token to your app server, and call the cloud API of HMS Core on your server to obtain the fake user detection result.
                   }
               }
               .addOnFailureListener {  // There was an error communicating with the service.
                   val errorMsg: String? = if (it is ApiException) {
                       // An error with the HMS API contains some additional details.
                       // You can use the apiException.getStatusCode() method to get the status code.
                       (SafetyDetectStatusCodes.getStatusCodeString(it.statusCode) + ": "
                               + it.message)
                   } else {
                       // Unknown type of error has occurred.
                       it.message
                   }
                   Log.i(TAG, "User detection fail. Error info: $errorMsg")
               }
       }

   NOTE

   If the UserDetect API has executed the onSuccess() method, the user has completed man-machine distinction. However, you still need to verify responseToken of the user on your app server.

2. Call an on-cloud API (nocaptcha in the Chinese mainland and verify outside the Chinese mainland) based on the response token obtained in 1 to obtain the user detection result.

   To obtain the detection result, perform the following steps on the server:

   1. Obtain an access token. For details, please refer to OAuth 2.0-based Authentication.

   2. Call the cloud API to obtain the detection result. For details, please refer to Obtaining Fake User Detection Results (Outside the Chinese Mainland). The following is a request example:

   Collapse

   Word wrap

   Dark theme

   Copy code

   POST https://{domain}/rms/v1/userRisks/verify?appId=****** HTTP/1.1// For details about {domain}, please refer to Site Information.
   Content-Type: application/json;charset=utf-8

   Collapse

   Word wrap

   Dark theme

   Copy code

   {
       "accessToken":"AAWWHI94sgUR2RU5_P1ZptUiwLq7W8XWJO2LxaAPuXw4_HOJFXnBlN-q5_3bwlxVW_SHeDPx_s5bWW-9DjtWZsvcm9CwXe1FHJg0u-D2pcQPcb3sTxDTJeiwEb9WBPl_9w",
       "response":"1_55d74c04eab36a0a018bb7a879a6f49f072b023690cba936"
   }

Disabling UserDetect in the App

private void shutdownUserDetect() {
    // Replace with your activity or context as a parameter.
    SafetyDetectClient client = SafetyDetect.getClient(MainActivity.this);
    client.shutdownUserDetect().addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void v) {
            // Indicates that communication with the service was successful.
        }
    }).addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(Exception e) {
            // An error occurred during communication with the service.
        }
    });
}

private fun shutdownUserDetect() {
        // Replace with your activity or context as a parameter.
        val client = SafetyDetect.getClient(this@MainActivity)
        client.shutdownUserDetect()
            .addOnSuccessListener {
                // Indicates that communication with the service was successful.
            }.addOnFailureListener {
                // An error occurred during communication with the service.
            }
    }

Common Error Codes

DETECT_FAIL: 19800

Detection failed. Call the UserDetect API again.

NETWORK_ERROR: 19002

The network is not connected. Ensure that the network is connected and call the UserDetect API again.