Mobile implementation
Turnstile is designed to run in a standard browser environment, which includes mobile devices. On native mobile applications, Turnstile can be used with WebViews. This applies to native web applications for iOS and Android. When implementing Turnstile for mobile, ensure you address the common issues below to avoid integration problems.
Any modifications to the environment, such as the User Agent, Content Security Policy settings, or domain allowlisting, can disrupt the successful completion of Turnstile challenges. To ensure compatibility, it is recommended to start with a default, unmodified environment and gradually introduce changes, validating Turnstile’s functionality after each adjustment.
Turnstile requires specific WebView settings to function properly. For Android implementations, refer to setJavaScriptEnabled ↗ to tell the WebView to enable JavaScript execution and setDomStorageEnabled ↗ to enable the DOM storage API.
These settings ensure that the mobile WebView can properly load and execute the Turnstile challenge. If these configurations are missing, Turnstile may malfunction.
In addition to ensuring proper WebView settings, if you have allowed origins configured, it is essential to update the list to include:
challenges.cloudflare.com, about:blank, about:srcdocWithout this, Turnstile challenges might fail to load. WebView should also be configured to allow insecure connections (http and https).
When implementing Turnstile with WebViews, the user agent must stay consistent as changing the user agent will cause the challenges to fail.
When using clearance cookies with Turnstile, make sure that it is executed in the same environment where the challenges will occur, including the same browser and device configuration. The cf_clearance cookie will be only accepted in the same configured domain for Turnstile widget with the corresponding zone. Domains configured with the Turnstile widget must match the Cloudflare zone that issues challenges via the WAF.
If pre-clearance is done in a different environment, the clearance cookie may become invalid and lead to more issued challenges.
For developers using Flutter ↗, Turnstile is compatible and tested with Flutter’s WebView implementation. Refer to the official Flutter WebView package for more details and usage.