INTEGRITY Dokumentace

← Cloudflare Turnstile / turnstile / get-started

Implementace na mobilních zařízeních

Turnstile vyžaduje prostředí prohlížeče, protože výzvy v JavaScriptu spouští přímo v prohlížeči návštěvníka. Na mobilních zařízeních funguje v mobilních prohlížečích bez další konfigurace.

V nativních mobilních aplikacích Turnstile nativně neběží. Místo toho načtete stránku s widgetem Turnstile pomocí WebView, tedy komponenty prohlížeče vložené do vaší nativní aplikace.

Integrace ve WebView

WebView vkládá do nativní aplikace jádro prohlížeče, takže v ní můžete zobrazovat webové stránky, formuláře i obsah založený na JavaScriptu, například widgety Turnstile.

Požadavky

Aby Turnstile ve WebView fungoval správně, musí být splněny tyto požadavky.

Podpora JavaScriptu

Přístup k síti

Konzistence prostředí

Implementace pro konkrétní platformy

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,
        ),
      ),
    );
  }
}

Časté problémy při implementaci

Konzistence hlavičky User Agent

Pokud se během relace změní User Agent, ověření Turnstile selže: pravost návštěvníka se posuzuje podle neměnných vlastností prohlížeče. Změnu User Agentu uprostřed relace proto Turnstile vyhodnotí jako možné bezpečnostní riziko a ověření odmítne.

// 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)

Striktní Content Security Policy může Turnstile bránit v načtení potřebných skriptů i v navázání síťových spojení. Dochází k tomu, když hlavičky nebo meta značky CSP blokují přístup k doménám a prostředkům, které Turnstile ke správné funkci potřebuje.

<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;
"
/>

Konfigurace domény

Bezpečnostní omezení WebView mohou zabránit přístupu k doménám, které Turnstile ke svému fungování potřebuje. Některé WebView jsou nastavené tak, že povolují jen vybrané domény nebo blokují určité typy spojení. Turnstile pak nemusí načíst výzvy ani navázat komunikaci se servery Cloudflare.

Vyřešíte to tak, že mezi povolené originy ve WebView přidáte všechny domény, které Turnstile potřebuje:

Konkrétní postup se liší podle platformy, princip je ale vždy stejný: výslovně povolit síťový přístup k těmto doménám.

Pokud se cookies a local storage mezi relacemi neuchovávají, Turnstile může selhat: právě na těchto mechanismech staví udržování stavu a sledování chování návštěvníka. Typicky k tomu dochází, když je nastavení úložiště ve WebView příliš přísné nebo když aplikace úložiště mezi relacemi maže. Zkontrolujte, že váš WebView umí s cookies a local storage správně pracovat.

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