Skip to main content

Mobile

When integrating Topper with a mobile app you can either open Topper on a user's browser (where no extra configuration is required), WebView or Safari View Controller.

Please ensure the following steps have been completed, depending on your integration scenario.

On WebView and Safari View Controller:

On WebView:

Query parameters are the preferred way to tell Topper which mobile context it is running in. However, for iOS and Android WebViews, Topper can also detect this context automatically as a fallback, by inspecting the browser's user agent when the corresponding query parameter hasn't been set. This does not change the recommended integration path of explicitly setting is_android_webview or is_ios_webview which still gives you the most predictable behavior, but it adds a safety net for cases where the parameter is missing.

Safari View Controller is the exception due to its user agent being indistinguishable from a regular Safari browser, so there's no reliable way for Topper to detect it automatically. Therefore is_safari_view_controller=1 must always be set for that scenario to be recognized.

Cloudflare Turnstile​

We use Cloudflare Turnstile to confirm users are real and to block unwanted bots without slowing down the experience. Please be sure to follow these Webview configurations, update the allowed origins to include challenges.cloudflare.com, about:blank, about:srcdoc, and enable https and http connections.

If you use the react-native-webview package, update your WebView originWhitelist to originWhitelist={['https://*', 'http://*', 'about:blank', 'about:srcdoc']}.

If you use Flutter, Turnstile is compatible and tested with Flutter’s WebView implementation.

Apple Single Sign-On​

Apple Single Sign-On opens appleid.apple.com in a pop-up window (window.open) and sends the result back to Topper through that pop-up. For the sign-in to complete, your app must open the pop-up inside the app, in a WebView linked to the one running Topper.

This only applies to appleid.apple.com. Other new windows opened by Topper (e.g. links to terms and policies) can keep opening wherever your app opens them today, such as Safari.

Apple Single Sign-On will not complete if your app:

  • Opens new windows in the system browser or in a Safari View Controller (e.g. calling UIApplication.shared.open or Linking.openURL when the page opens a new window).
  • Loads new windows in the same WebView that is running Topper.
  • Blocks new windows. On iOS, this is the default when no WKUIDelegate is set.

In these cases, users either can't open the Apple sign-in or complete it and return to Topper without being signed in.

iOS (WKWebView)​

  • Set a WKUIDelegate on the WebView.
  • In webView(_:createWebViewWith:for:windowFeatures:), when the request host is exactly appleid.apple.com, return a new WKWebView created with the provided configuration, presented inside your app. Creating it with a new configuration breaks the link between the pop-up and Topper.
  • Implement webViewDidClose(_:) to dismiss the pop-up when it closes itself.
  • If your app sends navigations to Safari in webView(_:decidePolicyFor:decisionHandler:), exclude appleid.apple.com and other apple.com pages. This applies to the main WebView and to the pop-up, if you give it the same navigation delegate.