UniWebViewSafeBrowsing
Summary
UniWebView Safe Browsing provides a way for browsing the web content in a more browser-like way, such as Safari on iOS and Chrome on Android.
This class wraps SFSafariViewController on iOS and “Custom Tabs” on Android. Starting with iOS 11, this component no longer shares cookies with Safari in the same way as it did in iOS 9 or 10, due to design restrictions by Apple that cannot be bypassed. It still supports auto-fill completion and other data sharing with the browser on the device. Most permissions are also built-in. You can use this class for tasks that are limited for a normal web view, such as using Apple Pay or Progressive Web Apps (PWA).
You create a UniWebViewSafeBrowsing instance by calling the static UniWebViewSafeBrowsing.Create method with a destination URL. On iOS, the URL is fixed for the lifetime of the instance. On Android, you can change the target URL before calling Show by using ChangeUrl. To show the safe browsing, call Show on the instance. The web content will be displayed in full screen with a toolbar containing the loaded URL, as well as some basic controls like Go Back, Go Forward and Done.
Browsing web content in UniWebViewSafeBrowsing is only supported on iOS and Android. There is no such component in Unity Editor. Creating and showing a UniWebViewSafeBrowsing on Unity Editor will fall back to open the URL in external browser by using Unity's Application.OpenURL.
Properties Summary
Whether the safe browsing mode is supported in current runtime or not. | |
Uses the system default color scheme. | |
Forces a light color scheme for the Custom Tabs UI. | |
Forces a dark color scheme for the Custom Tabs UI. | |
Uses the default resize behavior decided by the Custom Tabs provider. | |
Allows the user to resize the partial Custom Tab. | |
Prevents the user from resizing the partial Custom Tab. |
Events Summary
Raised when user dismisses safe browsing by tapping the Done button or Back button. | |
Raised together with | |
Raised when the underlying browser starts loading a page in Safe Browsing mode. | |
Raised when the Safe Browsing page finishes loading successfully. | |
Raised when the Safe Browsing page fails to load. |
Methods Summary
Creates a new | |
Sets the preferred browsers for Custom Tabs in order of preference. | |
Shows the safe browsing content above current screen. | |
Dismisses the safe browsing component. | |
Releases the native Safe Browsing resources when you no longer plan to use this instance. | |
Sets the color for toolbar background in the safe browsing component. | |
Sets the Custom Tabs UI color scheme. | |
Changes the URL to be loaded before the tab is shown (useful for warmup/prefetch). | |
Sets the secondary/bottom toolbar color. | |
Sets the navigation bar color. | |
Sets the navigation bar divider color. | |
Sets the toolbar corner radius in dp for partial Custom Tabs. | |
Sets initial Custom Tab height in pixels for partial tabs and chooses how the sheet can resize. | |
Sets initial Custom Tab width in pixels (side sheet). | |
Enables or disables share menu items. | |
Enables hiding the URL bar on scroll. | |
Sends redirects to the system default handler when enabled. | |
Toggles side-sheet maximization for partial Custom Tabs. | |
Enables or disables the download button in the overflow menu. | |
Enables or disables the bookmarks button in the overflow menu. | |
Allows interaction with background apps when a partial Custom Tab is shown. | |
Warms up the Custom Tabs provider process to speed up later loads. | |
Uses Custom Tabs prefetch ( | |
Sets the color for toolbar controls in the safe browsing component. |
Properties
Whether the safe browsing mode is supported in current runtime or not.
If supported, the safe browsing mode will be used when Show is called on a UniWebViewSafeBrowsing instance. Otherwise, the system default browser will be used to open the page when Show is called.
This property always returns true on iOS runtime platform. On Android, it depends on whether there is an Intent can handle the safe browsing request. Usually this ability is provided by Chrome, but there are also other browser app might implement that. If there is no Intent can open the URL in safe browsing mode, or the handling app is set to disabled in Android system, this property returns false.
To use this API on Android when you set your Target SDK to Android 11 or later, you need to add the correct intent query explicitly in your AndroidManifest.xml, to follow the Package Visibility (https://developer.android.com/about/versions/11/privacy/package-visibility). Add queries as a subnode of the manifest tag:
Example
<manifest>
// ...
</application>
<queries>
<intent>
<action android:name="android.support.customtabs.action.CustomTabsService" />
</intent>
</queries>
</manifest>
// To use it:
if (UniWebViewSafeBrowsing.IsSafeBrowsingSupported) {
// Safe Browsing Mode is available on current device.
}
Uses the system default color scheme.
Forces a light color scheme for the Custom Tabs UI.
Forces a dark color scheme for the Custom Tabs UI.
Uses the default resize behavior decided by the Custom Tabs provider.
Allows the user to resize the partial Custom Tab.
Prevents the user from resizing the partial Custom Tab.
Events
Raised when user dismisses safe browsing by tapping the Done button or Back button.
The dismissed safe browsing instance will be invalid after this event being raised, and you should not use it for another browsing purpose. Instead, create a new one for a new browsing session.
NOTICE
This event will not happen in Unity Editor, because the whole UniWebViewSafeBrowsing will fall back to an external browser.
- UniWebViewSafeBrowsing browsing
The
UniWebViewSafeBrowsingobject raised this event.
Example
safeBrowsing.OnSafeBrowsingFinished += (browsing) => {
Debug.Log("UniWebViewSafeBrowsing closed.");
};
Raised together with OnSafeBrowsingFinished, but includes the metadata payload from the native safe browsing component.
- UniWebViewSafeBrowsing browsing
The
UniWebViewSafeBrowsingobject raised this event. - UniWebViewSafeBrowsingEventMetadata metadata
Structured metadata describing the native callback (timestamp, native source).
Example
safeBrowsing.OnSafeBrowsingClosed += (browsing, metadata) => {
Debug.Log($"Safe Browsing closed at {metadata.TimestampUtc} from {metadata.Source}");
};
Raised when the underlying browser starts loading a page in Safe Browsing mode.
NOTICE
This event is not raised on iOS/macOS because Safari does not expose a navigation-start callback.
- UniWebViewSafeBrowsing browsing
The
UniWebViewSafeBrowsingobject raised this event. - UniWebViewSafeBrowsingEventMetadata metadata
Structured metadata describing the native callback.
Example
safeBrowsing.OnSafeBrowsingNavigationStarted += (browsing, metadata) => {
Debug.Log($"Navigation started at {metadata.TimestampUtc}");
};
Raised when the Safe Browsing page finishes loading successfully.
- UniWebViewSafeBrowsing browsing
The
UniWebViewSafeBrowsingobject raised this event. - UniWebViewSafeBrowsingEventMetadata metadata
Structured metadata describing the native callback.
Example
safeBrowsing.OnSafeBrowsingNavigationFinished += (browsing, metadata) => {
Debug.Log($"Navigation finished at {metadata.TimestampUtc}");
};
Raised when the Safe Browsing page fails to load.
- UniWebViewSafeBrowsing browsing
The
UniWebViewSafeBrowsingobject raised this event. - UniWebViewSafeBrowsingEventMetadata metadata
Structured metadata describing the native callback.
Example
safeBrowsing.OnSafeBrowsingNavigationFailed += (browsing, metadata) => {
Debug.Log($"Safe Browsing error reported at {metadata.TimestampUtc}");
};
Methods
Creates a new UniWebViewSafeBrowsing instance with a given URL.
- string url
The URL to navigate to. The URL must use the
httporhttpsscheme.
Example
var safeBrowsing = UniWebViewSafeBrowsing.Create("https://uniwebview.com");
Sets the preferred browsers for Custom Tabs in order of preference.
This allows developers to specify which browsers should be preferred when multiple Custom Tabs providers are available on the device. This setting affects both SafeBrowsing and AuthenticationSession functionality.
Browser Selection Priority (Android):
- User-defined preferred packages (highest priority) - checked in order
- Default browser if it's Chromium-based (Chrome, Edge, etc.)
- Default browser if it supports Custom Tabs (even non-Chromium)
- Any Chromium-based browser (only when no user preference is set)
- Any available Custom Tabs provider (last resort)
This prioritization helps avoid browsers with incomplete Custom Tabs implementations (such as Firefox, which may not trigger onNavigationEvent callbacks properly).
On iOS, this method has no effect as Safari is always used for safe browsing.
- string[] packages
Array of browser package names in order of preference. Common package names include:
- "com.android.chrome" (Chrome)
- "com.brave.browser" (Brave Browser)
- "com.opera.browser" (Opera Browser)
- "com.microsoft.emmx" (Microsoft Edge)
- "com.sec.android.app.sbrowser" (Samsung Internet)
Example
// Set Chrome and Brave as preferred browsers
UniWebViewSafeBrowsing.SetPreferredCustomTabsBrowsers(new string[] {
"com.android.chrome",
"com.brave.browser"
});
var safeBrowsing = UniWebViewSafeBrowsing.Create("https://uniwebview.com");
safeBrowsing.Show();
Shows the safe browsing content above current screen.
Example
var safeBrowsing = UniWebViewSafeBrowsing.Create("https://uniwebview.com");
safeBrowsing.Show();
Dismisses the safe browsing component.
This method only works on iOS. On Android, there is no way to dismiss the safe browsing component
Releases the native Safe Browsing resources when you no longer plan to use this instance.
Call this after Create if the business logic changes and you decide not to show the Safe Browsing UI. Android will unbind its Custom Tabs service, while iOS simply discards the underlying SFSafariViewController. When the UI is actually presented and the user closes it (Done/Back), cleanup runs automatically and you do not need to call this method.
Example
var safeBrowsing = UniWebViewSafeBrowsing.Create("https://uniwebview.com");
// Later we decide not to show Safe Browsing anymore.
safeBrowsing.Invalidate();
Sets the color for toolbar background in the safe browsing component.
The changes are ignored after Show method is called.
- Color color
The color to tint the toolbar.
Example
safeBrowsing.SetToolbarColor(Color.blue);
Sets the Custom Tabs UI color scheme. Ignored after Show.
Android only. This method does nothing on iOS.
- ColorScheme colorScheme
The desired color scheme (
System,Light, orDark).
Changes the URL to be loaded before the tab is shown (useful for warmup/prefetch). Ignored after Show.
Android only. This method does nothing on iOS.
- string url
The URL to switch to before calling
Show.
Sets the secondary/bottom toolbar color. Ignored after Show.
Android only. This method does nothing on iOS.
- Color color
Tint color for the secondary toolbar.
Sets the navigation bar color. Ignored after Show.
Android only. This method does nothing on iOS.
- Color color
Tint color for the navigation bar.
Sets the navigation bar divider color. Ignored after Show.
Android only. This method does nothing on iOS.
- Color color
Tint color for the divider.
Sets the toolbar corner radius in dp for partial Custom Tabs. Ignored after Show.
Android only. This method does nothing on iOS.
- int cornerRadiusDp
Corner radius in density-independent pixels.
Sets initial Custom Tab height in pixels for partial tabs and chooses how the sheet can resize. Ignored after Show.
Android only. This method does nothing on iOS.
- int initialHeightPx
Initial height in pixels.
- ActivityHeightResizeBehavior resizeBehavior
Resize behavior (
Default,Resizable, orFixed). Defaults toFixed.
Sets initial Custom Tab width in pixels (side sheet). Ignored after Show.
Android only. Requires AndroidX Browser 1.8.0+. This method does nothing on iOS.
- int initialWidthPx
Initial width in pixels.
Enables or disables share menu items. Ignored after Show.
Android only. This method does nothing on iOS.
- bool enable
Whether sharing buttons are enabled.
Enables hiding the URL bar on scroll. Ignored after Show.
Android only. This method does nothing on iOS.
- bool enable
Whether the URL bar hides when scrolling.
Sends redirects to the system default handler when enabled. Ignored after Show.
Android only. Requires AndroidX Browser 1.7.0+. This method does nothing on iOS.
- bool enable
Allow redirects to be handled externally.
Toggles side-sheet maximization for partial Custom Tabs. Ignored after Show.
Android only. Requires AndroidX Browser 1.8.0+. This method does nothing on iOS.
- bool enable
Whether the maximization button is enabled.
Enables or disables the download button in the overflow menu. Ignored after Show.
Android only. Requires AndroidX Browser 1.7.0+. This method does nothing on iOS.
- bool enable
Enable download button in overflow.
Enables or disables the bookmarks button in the overflow menu. Ignored after Show.
Android only. Requires AndroidX Browser 1.7.0+. This method does nothing on iOS.
- bool enable
Enable bookmarks button in overflow.
Allows interaction with background apps when a partial Custom Tab is shown. Ignored after Show.
Android only. Requires AndroidX Browser 1.7.0+. This method does nothing on iOS.
- bool enable
Allow background interaction while partial tab is visible.
Warms up the Custom Tabs provider process to speed up later loads. Can be called multiple times. Ignored after Show.
Android only. This method does nothing on iOS.
- bool enable
Whether to warm up the provider.
Uses Custom Tabs prefetch (mayLaunchUrl) before showing the tab. Ignored after Show.
Android only. This method does nothing on iOS.
- bool enable
Enable or disable prefetch.
- string alternativeUrl
Optional URL to prefetch instead of the current one.
Sets the color for toolbar controls in the safe browsing component.
The changes are ignored after Show method is called.
This method only works on iOS. On Android, the controls color is determined by system to keep a reasonable contrast, based on the toolbar background color you provided in SetToolbarColor.
- Color color
The color to tint the controls on toolbar.
Example
safeBrowsing.SetToolbarItemColor(Color.yellow);