Flutter云安全与服务管理插件cloudflare_turnstile的使用

Flutter Cloudflare Turnstile

Cloudflare Turnstile 是一个免费的 CAPTCHA 替代方案，它为网站访客提供无挫感、无 CAPTCHA 的网页体验 - 只需简单的一段免费代码。此外，Turnstile 可以阻止滥用行为并确认访问者的真实性，而不会产生数据隐私问题或糟糕的用户体验。

⚠️ 请注意，此软件包是非官方的，并未得到 Cloudflare 的认可。请自行决定是否使用。

安装

在您的 Flutter 项目中添加 cloudflare_turnstile 插件：

flutter pub add cloudflare_turnstile

示例

下面是一个快速示例，展示了如何将 Cloudflare Turnstile 小部件添加到您的 Flutter 应用程序中：

基本示例

import 'package:flutter/material.dart';
import 'package:cloudflare_turnstile/cloudflare_turnstile.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // Turnstile widget configuration
    final TurnstileOptions options = const TurnstileOptions(
      size: TurnstileSize.normal,
      theme: TurnstileTheme.light,
      language: 'ar',
      retryAutomatically: false,
      refreshTimeout: TurnstileRefreshTimeout.manual,
    );

    return Scaffold(
      body: Center(
        child: CloudflareTurnstile(
          siteKey: '3x00000000000000000000FF', //Change with your site key
          baseUrl: 'http://localhost/',
          onTokenReceived: (token) {
            print(token);
          },
        ),
      ),
    );
  }
}

对于 Android 和 iOS 平台，您需要提供 baseUrl 参数，该参数必须与创建小部件时的域名列表中的 URL 相同。

使用 Turnstile 隐藏模式

以下是如何使用 Cloudflare 的隐藏 Turnstile 模式，在后台自动解决挑战：

import 'package:cloudflare_turnstile/cloudflare_turnstile.dart';

class TurnstileService {
  /// 获取 CloudFlare Turnstile token 使用隐藏模式。
  static Future<String?> get token async {
    // 初始化一个隐藏模式的 Cloudflare Turnstile 实例，使用您的站点密钥
    final turnstile = CloudflareTurnstile.invisible(
      siteKey: '1x00000000000000000000BB', // 替换为您的实际站点密钥
    );

    try {
      // 获取 Turnstile token
      final token = await turnstile.getToken();
      return token; // 成功时返回 token
    } on TurnstileException catch (e) {
      // 处理 Turnstile 失败
      print('Challenge failed: ${e.message}');
    } finally {
      // 确保正确释放 Turnstile 实例
      turnstile.dispose();
    }

    // 如果无法生成 token，则返回 null
    return null;
  }
}

⚠️ 重要提示：当不再需要时，请务必调用 dispose() 方法来释放 CloudflareTurnstile 实例。这可以确保资源被正确清理，防止潜在的内存问题。

完整示例代码

以下是一个完整的示例代码，包含刷新和验证 token 的功能：

import 'package:flutter/material.dart';
import 'package:cloudflare_turnstile/cloudflare_turnstile.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final TurnstileController _controller = TurnstileController();
  final TurnstileOptions _options = TurnstileOptions(
    size: TurnstileSize.normal,
    theme: TurnstileTheme.light,
    refreshExpired: TurnstileRefreshExpired.manual,
    language: 'en',
    retryAutomatically: false,
  );

  String? _token;

  @override
  void dispose() {
    super.dispose();
    _controller.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: Builder(
        builder: (context) => Scaffold(
          body: Center(
            child: SingleChildScrollView(
              padding: const EdgeInsets.all(16.0),
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  ConstrainedBox(
                    constraints: const BoxConstraints(maxWidth: 700),
                    child: _token != null
                        ? SelectableText(_token!)
                        : const CircularProgressIndicator(),
                  ),
                  const SizedBox(height: 48.0),
                  Align(
                    alignment: Alignment.center,
                    child: CloudflareTurnstile(
                      siteKey: '3x00000000000000000000FF',
                      options: _options,
                      controller: _controller,
                      onTokenReceived: (token) {
                        setState(() {
                          _token = token;
                        });
                      },
                      onTokenExpired: () {},
                      onError: (error) {
                        ScaffoldMessenger.of(context).showSnackBar(
                          SnackBar(
                            content: Text(
                                'Turnstile challenge failed:\n${error.message}'),
                          ),
                        );
                      },
                    ),
                  ),
                  const SizedBox(height: 48.0),
                  Row(
                    mainAxisAlignment: MainAxisAlignment.center,
                    children: [
                      ElevatedButton(
                        onPressed: () async {
                          setState(() {
                            _token = null;
                          });

                          await _controller.refreshToken();
                        },
                        child: const Text('Refresh Token'),
                      ),
                      const SizedBox(width: 16.0),
                      ElevatedButton(
                        onPressed: () {
                          _controller.isExpired().then((isExpired) {
                            ScaffoldMessenger.of(context).showSnackBar(
                              SnackBar(
                                content: Text(
                                    'Token is ${isExpired ? "Expired" : "Valid"}'),
                              ),
                            );
                          });
                        },
                        child: const Text('Validate Token'),
                      ),
                    ],
                  ),
                ],
              ),
            ),
          ),
        ),
      ),
    );
  }
}

这个完整的示例展示了如何在应用程序中集成 Cloudflare Turnstile，并提供了刷新和验证 token 的按钮。希望这些信息对您有帮助！如果有任何问题或建议，请随时提问。