API reCAPTCHA SafetyNet

Dịch vụ SafetyNet bao gồm một API reCAPTCHA mà bạn có thể dùng để bảo vệ ứng dụng của mình khỏi lưu lượng truy cập độc hại.

reCAPTCHA là một dịch vụ miễn phí sử dụng công cụ phân tích rủi ro nâng cao để bảo vệ ứng dụng của bạn khỏi nội dung rác và các hành động sử dụng sai mục đích khác. Nếu nghi ngờ người dùng tương tác với ứng dụng là một bot chứ không phải người, thì dịch vụ sẽ hiển thị một hình ảnh xác thực (CAPTCHA) mà người dùng phải giải quyết trước khi ứng dụng có thể tiếp tục thực thi.

Tài liệu này giải thích cách tích hợp API reCAPTCHA từ SafetyNet vào ứng dụng của bạn.

Điều khoản dịch vụ bổ sung

Bằng cách truy cập hoặc sử dụng API reCAPTCHA, bạn đồng ý với Điều khoản dịch vụ dành cho các API của Google và Điều khoản dịch vụ sau đây của reCAPTCHA. Vui lòng đọc và nắm rõ tất cả các điều khoản và chính sách áp dụng trước khi truy cập vào các API này.

Điều khoản dịch vụ của reCAPTCHA

Bạn xác nhận và hiểu rằng API reCAPTCHA hoạt động bằng cách thu thập thông tin phần cứng và phần mềm, chẳng hạn như dữ liệu thiết bị và ứng dụng cũng như kết quả của các lượt kiểm tra tính toàn vẹn, đồng thời gửi dữ liệu đó đến Google để phân tích. Căn cứ vào Mục 3(d) trong Điều khoản dịch vụ dành cho các API của Google, bạn đồng ý rằng nếu bạn sử dụng các API đó, thì bạn có trách nhiệm cung cấp mọi thông báo hoặc sự đồng ý cần thiết cho việc thu thập và chia sẻ dữ liệu này với Google.

Đăng ký một cặp khoá reCAPTCHA

Để đăng ký một cặp khoá dùng với API reCAPTCHA SafetyNet, hãy chuyển đến trang web đăng ký reCAPTCHA cho Android, sau đó hoàn tất tuần tự các bước sau:

Trong biểu mẫu xuất hiện, hãy cung cấp các thông tin sau đây:
- Label (Nhãn): Một nhãn duy nhất cho khoá của bạn. Thông thường, bạn sẽ sử dụng tên của công ty hoặc tổ chức mình.
- reCAPTCHA type (Kiểu reCAPTCHA): Chọn reCAPTCHA v2 (reCAPTCHA phiên bản 2), sau đó chọn reCAPTCHA Android (reCAPTCHA cho Android).
- Packages (Gói): Cung cấp tên gói của từng ứng dụng dùng khoá API này. Để một ứng dụng dùng API này, tên gói bạn nhập phải khớp chính xác với tên gói của ứng dụng đó. Nhập mỗi tên gói trên một dòng riêng.
- Owners (Chủ sở hữu): Thêm địa chỉ email của từng cá nhân chịu trách nhiệm giám sát các lượt đánh giá reCAPTCHA của ứng dụng trong tổ chức của bạn.
Chọn hộp đánh dấu Accept the reCAPTCHA Terms of Service (Chấp nhận Điều khoản dịch vụ của reCAPTCHA).
Send alerts to owners (Gửi cảnh báo đến các chủ sở hữu): Chọn hộp đánh dấu này nếu bạn muốn nhận email về API reCAPTCHA, sau đó nhấp vào Submit (Gửi).
Trên trang tiếp theo hiện ra, khoá công khai và riêng tư của bạn sẽ lần lượt xuất hiện trong phần Site key (Khoá trang web) và Secret key (Khoá bí mật). Bạn sử dụng khoá trang web khi gửi yêu cầu xác minh còn sử dụng khoá bí mật khi xác thực mã thông báo phản hồi của người dùng.

Thêm phần phụ thuộc API SafetyNet

Trước khi sử dụng API reCAPTCHA, hãy thêm API SafetyNet vào dự án của bạn. Nếu bạn đang sử dụng Android Studio, hãy thêm phần phụ thuộc này vào tệp Gradle cấp ứng dụng. Để biết thêm thông tin, hãy xem phần Thiết lập API SafetyNet.

Sử dụng API reCAPTCHA

Phần này mô tả cách gọi API reCAPTCHA để gửi một yêu cầu xác minh CAPTCHA và nhận mã thông báo phản hồi của người dùng.

Gửi yêu cầu xác minh

Để gọi API reCAPTCHA SafetyNet, bạn cần gọi phương thức verifyWithRecaptcha(). Thông thường, phương thức này tương ứng với việc người dùng chọn một phần tử trên giao diện người dùng (chẳng hạn như một nút) trong hoạt động của bạn.

Khi dùng phương thức verifyWithRecaptcha() trong ứng dụng, bạn phải làm như sau:

Truyền khoá trang web API dưới dạng tham số.
Ghi đè phương thức onSuccess() và onFailure() để xử lý cả hai kết quả có thể xảy ra của tác vụ yêu cầu xác minh. Cụ thể, nếu API truyền một thực thể của ApiException vào onFailure(), bạn cần phải xử lý từng mã trạng thái có thể có mà bạn truy xuất được bằng getStatusCode().

Đoạn mã sau đây minh hoạ cách gọi phương thức này:

Kotlin

fun onClick(view: View) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
            .addOnSuccessListener(this as Executor, OnSuccessListener { response ->
                // Indicates communication with reCAPTCHA service was
                // successful.
                val userResponseToken = response.tokenResult
                if (response.tokenResult?.isNotEmpty() == true) {
                    // Validate the user response token using the
                    // reCAPTCHA siteverify API.
                }
            })
            .addOnFailureListener(this as Executor, OnFailureListener { e ->
                if (e is ApiException) {
                    // An error occurred when communicating with the
                    // reCAPTCHA service. Refer to the status code to
                    // handle the error appropriately.
                    Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")
                } else {
                    // A different, unknown type of error occurred.
                    Log.d(TAG, "Error: ${e.message}")
                }
            })
}

Java

public void onClick(View v) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
        .addOnSuccessListener((Executor) this,
            new OnSuccessListener<SafetyNetApi.RecaptchaTokenResponse>() {
                @Override
                public void onSuccess(SafetyNetApi.RecaptchaTokenResponse response) {
                    // Indicates communication with reCAPTCHA service was
                    // successful.
                    String userResponseToken = response.getTokenResult();
                    if (!userResponseToken.isEmpty()) {
                        // Validate the user response token using the
                        // reCAPTCHA siteverify API.
                    }
                }
        })
        .addOnFailureListener((Executor) this, new OnFailureListener() {
                @Override
                public void onFailure(@NonNull Exception e) {
                    if (e instanceof ApiException) {
                        // An error occurred when communicating with the
                        // reCAPTCHA service. Refer to the status code to
                        // handle the error appropriately.
                        ApiException apiException = (ApiException) e;
                        int statusCode = apiException.getStatusCode();
                        Log.d(TAG, "Error: " + CommonStatusCodes
                                .getStatusCodeString(statusCode));
                    } else {
                        // A different, unknown type of error occurred.
                        Log.d(TAG, "Error: " + e.getMessage());
                    }
                }
        });
}

Xác thực mã thông báo phản hồi của người dùng

Khi API reCAPTCHA thực thi phương thức onSuccess(), người dùng đã hoàn tất thành công thử thách xác thực hình ảnh (CAPTCHA). Tuy nhiên, phương thức này chỉ cho biết rằng người dùng đã giải quyết CAPTCHA một cách chính xác. Bạn vẫn cần xác thực mã thông báo phản hồi của người dùng từ máy chủ phụ trợ.

Để tìm hiểu cách xác thực mã thông báo phản hồi của người dùng, hãy xem bài viết Xác minh phản hồi của người dùng.