INTEGRITY Документация

← Cloudflare Turnstile / turnstile / get-started

Реализация на мобильных устройствах

Turnstile требует браузерного окружения, так как выполняет проверки на JavaScript в браузере посетителя. На мобильных устройствах Turnstile работает в мобильных браузерах без дополнительной настройки.

В нативных мобильных приложениях Turnstile не работает напрямую. Вместо этого используется WebView, встроенный в приложение компонент браузера, который загружает веб-страницу с виджетом Turnstile.

Интеграция с WebView

WebView встраивает браузерный движок в нативное приложение, поэтому в нём можно показывать веб-страницы, формы и содержимое на JavaScript, например виджеты Turnstile.

Требования

Чтобы Turnstile корректно работал в WebView, должны выполняться следующие требования.

Поддержка JavaScript

Доступ к сети

Единообразие окружений

Реализация для конкретных платформ

Android WebView

WebView webView = findViewById(R.id.webview);
WebSettings webSettings = webView.getSettings();

// Required: Enable JavaScript
webSettings.setJavaScriptEnabled(true);

// Required: Enable DOM storage
webSettings.setDomStorageEnabled(true);

// Recommended: Enable other web features
webSettings.setLoadWithOverviewMode(true);
webSettings.setUseWideViewPort(true);
webSettings.setAllowFileAccess(true);
webSettings.setAllowContentAccess(true);

// Load your web content with Turnstile
webView.loadUrl("https://yoursite.com/protected-form");

iOS WKWebView (Swift)

import WebKit

class ViewController: UIViewController {
    @IBOutlet weak var webView: WKWebView!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Configure WebView
        let configuration = WKWebViewConfiguration()
        configuration.preferences.javaScriptEnabled = true

        // Load your web content with Turnstile
        if let url = URL(string: "https://yoursite.com/protected-form") {
            webView.load(URLRequest(url: url))
        }
    }
}

React Native WebView

import { WebView } from "react-native-webview";

export default function App() {
	return (
		<WebView
			source={{ uri: "https://yoursite.com/protected-form" }}
			javaScriptEnabled={true}
			domStorageEnabled={true}
			allowsInlineMediaPlayback={true}
			mediaPlaybackRequiresUserAction={false}
		/>
	);
}

Flutter WebView

import 'package:flutter_inappwebview/flutter_inappwebview.dart';

class WebViewScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return InAppWebView(
      initialUrlRequest: URLRequest(
        url: Uri.parse('https://yoursite.com/protected-form')
      ),
      initialOptions: InAppWebViewGroupOptions(
        crossPlatform: InAppWebViewOptions(
          javaScriptEnabled: true,
          useShouldOverrideUrlLoading: false,
        ),
        android: AndroidInAppWebViewOptions(
          domStorageEnabled: true,
        ),
        ios: IOSInAppWebViewOptions(
          allowsInlineMediaPlayback: true,
        ),
      ),
    );
  }
}

Частые проблемы при внедрении

Постоянство User Agent

Если User Agent меняется в течение сессии, проверки Turnstile завершаются неудачей: подлинность посетителя подтверждается по неизменным характеристикам браузера. Смену User Agent посреди сессии Turnstile считает возможной угрозой безопасности и отклоняет проверку.

// Android - Set consistent User Agent
webSettings.setUserAgentString(webSettings.getUserAgentString());
// iOS - Maintain default User Agent
webView.customUserAgent = webView.value(forKey: "userAgent") as? String

Content Security Policy (CSP)

Строгий Content Security Policy могут помешать Turnstile загрузить нужные скрипты и установить необходимые сетевые соединения. Так происходит, когда заголовки CSP или мета-теги закрывают доступ к доменам и ресурсам, без которых Turnstile не работает.

<meta
	http-equiv="Content-Security-Policy"
	content="
  default-src 'self'; 
  script-src 'self' challenges.cloudflare.com 'unsafe-inline'; 
  connect-src 'self' challenges.cloudflare.com;
  frame-src 'self' challenges.cloudflare.com;
"
/>

Настройка доменов

Ограничения безопасности WebView могут закрыть доступ к доменам, которые нужны Turnstile для работы. Некоторые WebView настроены так, что разрешают только определённые домены или блокируют отдельные типы соединений. Из-за этого Turnstile не сможет загрузить проверки и связаться с серверами Cloudflare.

Чтобы это исправить, добавьте в список разрешённых источников вашего WebView все домены, которые нужны Turnstile:

Конкретный способ настройки зависит от платформы, но принцип один: явно разрешить сетевой доступ к этим доменам.

Если cookie и local storage не сохраняются между сеансами, Turnstile может давать сбой: он опирается на эти механизмы, чтобы хранить состояние и отслеживать поведение посетителя. Обычно причина в слишком строгих настройках хранилища WebView или в том, что приложение очищает хранилище между сеансами. Убедитесь, что ваш WebView настроен на корректную работу с cookie и local storage.

// Android - Enable cookies
CookieManager.getInstance().setAcceptCookie(true);
CookieManager.getInstance().setAcceptThirdPartyCookies(webView, true);
// iOS - Configure cookie storage
webView.configuration.websiteDataStore = WKWebsiteDataStore.default()