Tích Hợp Google reCAPTCHA v3 Trong Ứng Dụng Flutter

Tôi đã dành hàng giờ để gỡ lỗi và nghiên cứu, chỉ để phát hiện ra rằng giải pháp đơn giản hơn nhiều so với tôi nghĩ. Để giúp bạn tiết kiệm thời gian, dưới đây là hướng dẫn từng bước để tích hợp Google reCAPTCHA v3 vào ứng dụng di động Flutter của bạn.

Các yêu cầu cần thiết

• Một site key từ backend của bạn (hãy hỏi lập trình viên backend hoặc tự tạo một cái trong bảng điều khiển quản lý reCAPTCHA).
• Xác nhận với backend xem bạn đang sử dụng Enterprise hay Standard (v2/v3) reCAPTCHA.

Lựa Chọn Gói Phù Hợp

• Enterprise reCAPTCHA → sử dụng recaptcha_enterprise_flutter.
• Standard v2/v3 reCAPTCHA → sử dụng flutter_gcaptcha_v3.

Hướng dẫn này tập trung vào Standard v3.

Tại Sao Bạn Cần Một HTML Được Đưa Lên Mạng

Khác với các trình duyệt, ứng dụng Flutter không có tên miền. Nếu bạn cố gắng chạy reCAPTCHA trực tiếp trong WebView, tên miền sẽ trở thành about:blank, điều mà Google không chấp nhận.

Mẹo:

• Tạo một file HTML đơn giản để tải reCAPTCHA và tạo token.
• Tải HTML này vào WebView của Flutter.
• Truyền token được tạo trở lại Flutter.

👉 Bạn có thể tự lưu trữ mẫu HTML này hoặc sử dụng trang demo tại đây.
Tôi khuyên bạn nên tự lưu trữ để không phải phụ thuộc vào trang của bên thứ ba.

⚠️ Đừng quên whitelist tên miền mà bạn đã lưu trữ trong bảng điều khiển quản lý Google reCAPTCHA, nếu không token sẽ luôn bị không hợp lệ.

Bước 1: Khởi Tạo Site Key

Đặt đoạn mã này trong phần khởi tạo ứng dụng của bạn (ví dụ: main.dart):

RecaptchaHandler.instance.setupSiteKey(
  dataSiteKey: AppConstants.dataSiteKey,
);

Bước 2: Thêm WebView Ẩn

Trong cây widget của bạn, hãy thêm một ReCaptchaWebView ẩn chỉ dẫn đến HTML bạn đã lưu trữ:

SizedBox(
  width: 1,
  height: 1,
  child: Opacity(
    opacity: 0.01, // không đặt là 0 (có thể cắt giảm render)
    child: IgnorePointer(
      ignoring: true,
      child: ReCaptchaWebView(
        width: 1,
        height: 1,
        url: selfHostedRecaptchaHtml, // ví dụ: https://yourdomain.com/recaptcha.html
        onTokenReceived: _onTokenReceived,
      ),
    ),
  ),
);

Xử lý token như sau:

void _onTokenReceived(String token) {
  // Làm gì đó với token (ví dụ: gửi đến backend)
  print("Nhận được token reCAPTCHA: $token");
}

Bước 3: Kích Hoạt reCAPTCHA

Khi nào bạn cần một token mới (ví dụ: trong quá trình đăng ký, OTP, v.v.), hãy gọi:

RecaptchaHandler.executeV3(action: 'register');

Điều này sẽ kích hoạt grecaptcha.execute() bên trong HTML bạn đã lưu trữ, và token sẽ được truyền trở lại Flutter qua WebView → _onTokenReceived.

Tổng Kết

Và đó là tất cả — ứng dụng Flutter của bạn giờ đây có thể tạo ra token Google reCAPTCHA v3!

✅ Những điểm chính cần nhớ:

• Biết liệu backend của bạn là Enterprise hay Standard.
• Luôn whitelist tên miền HTML trong bảng điều khiển của Google.
• Tự lưu trữ HTML để đảm bảo tính đáng tin cậy.

Với cấu hình này, bạn sẽ có một luồng reCAPTCHA v3 an toàn và mượt mà chạy nguyên bản trong ứng dụng di động Flutter của bạn.

Best Practices

• Nên kiểm tra kỹ lưỡng các token nhận được trước khi gửi đến backend.
• Cập nhật thường xuyên thư viện và gói liên quan để đảm bảo tính bảo mật và hiệu suất.

Common Pitfalls

• Không whitelist tên miền có thể dẫn đến việc token không hợp lệ.
• Sử dụng WebView không đúng cách có thể ảnh hưởng đến trải nghiệm người dùng.

Performance Tips

• Tối ưu hóa kích thước HTML để tải nhanh hơn.
• Giảm thiểu số lần gọi đến reCAPTCHA để tăng tốc độ ứng dụng.

Troubleshooting

• Nếu không nhận được token, kiểm tra lại URL HTML và đảm bảo nó đã được whitelist.

FAQ

1. reCAPTCHA v3 khác gì so với v2?
reCAPTCHA v3 không yêu cầu người dùng tương tác mà chỉ đánh giá hành vi của người dùng.

2. Làm thế nào để biết token có hợp lệ không?
Gửi token đến backend và kiểm tra nó với API của Google để xác minh.

3. Có thể sử dụng reCAPTCHA v3 với API không?
Có, reCAPTCHA v3 có thể được tích hợp dễ dàng với bất kỳ API nào.

Tài Nguyên Tham Khảo

• Tài liệu chính thức về Google reCAPTCHA
• Thư viện Flutter cho reCAPTCHA

Hy vọng bài viết này sẽ giúp bạn tích hợp reCAPTCHA v3 thành công vào ứng dụng Flutter của mình!