Home

Awesome

unity-webview

unity-webview is a Unity 5 (and newer) plugin that overlays WebView components on Unity's rendering view. It supports Android, iOS, Unity Web Player, and Mac (Windows is not supported at this time).

This plugin is derived from keijiro-san's Unity WebView Integration.

Note: This plugin overlays native WebView/WKWebView views over Unity's rendering view and does not support these views in 3D. For alternative solutions, refer to this issue comment.

Getting Started

We recommend starting from the sample project (under the sample/ directory of the repo) as everything is already preconfigured :

  1. Clone this repo
  2. Open sample/Assets/Sample.unity to open the sample project in Unity (If you have a newer unity you will be warned that issues may occur but in general it is fine so click continue. You can also be warned that the project has issues but continue anyways because we will import the necessary packages).
  3. Double click on dist/unity-webview.unitypackage to open it in Unity and click on import to import the package to your Unity project (You can also use the package manager if you prefer). If you've imported unity-webview before, it might be easier to extract dist/unity-webview.zip.
  4. Click on the SampleWebView gameobject and put the url that you want to open by default (if http, refer to the cleartraffictext section).
  5. Select the platform you want to export to
  6. Build

If you want to make the webview fullscreen :

  1. Open Assets/Scripts/SampleWebView.cs
  2. Edit this line webViewObject.SetMargins(0, 0, 0, 0);

If you want to make the webview transparent (the background is the Unity scene) :

  1. Open Assets/Scripts/SampleWebView.cs
  2. Uncomment(or add in the webViewObject.Init function if it doesn't exist) this line transparent: true
  3. Add and remove a comma accordingly to the code

Note: For Android, the current implementation uses Android Fragment to enable the file input field. This might cause new issues. If you don't need the file input field, you can use dist/unity-webview-nofragment.unitypackage or dist/unity-webview-nofragment.zip. Issues If you have a blank white page, please make sure to see the clearTraffictext section of this README

Package Manager

For Unity 2019.4 or later, import the plugin using the Package Manager by adding the following entry to your Packages/manifest.json:

{
  "dependencies": {
    "net.gree.unity-webview": "https://github.com/gree/unity-webview.git?path=/dist/package"
  }
}

For the variant without Fragment:

{
  "dependencies": {
    "net.gree.unity-webview": "https://github.com/gree/unity-webview.git?path=/dist/package-nofragment"
  }
}

Note: Importing with the Package Manager does not work well for WebGL. Refer to the instructions for dist/unity-webview.unitypackage.

General Notes

If you start from the sample project, most of the time you just have to comment and uncomment to make the webview fit your needs.

Please also note that the Init function of the Assets/Plugins/Editor/UnityWebViewPostprocessBuild.cs has a lot of parameters and can be quite long.

If you have a blank screen, it is most likely that you used HTTP (instead of HTTPS) or self signed certificates. In this case, please refer to the use Cleartext Traffic section of this README.

You can call JS functions via Unity with the webViewObject.EvaluateJS() function even if your JS is served by a server. However, you cannot launch Unity functions from JS. To do this, you will either have to use this repo or to create a JS->Server->Unity. If you create a fork that allows a remote Unity to JS communication, feel free to fork this repo, add the functionality and submit your changes via a clear and well described Pull Request

Warning : Carefully look at the #if and #endif because they make parts of the code run or not run depending on the platform and the Editor version. You sometimes have to look at them to be sure that the code you add or edit will be executed.

Platform-Specific Notes

Mac (Editor)

macOS Version

The implementation uses WKWebView’s takeSnapshotWithConfiguration to capture an offscreen WebView image. macOS 10.13 (High Sierra) or later is required.

App Transport Security

Since Unity 5.3.0, Unity.app is built with ATS (App Transport Security) enabled, which does not permit non-secured (HTTP) connections. To open HTTP URLs in the Unity Mac Editor, update /Applications/Unity5.3.4p3/Unity.app/Contents/Info.plist as follows:

--- Info.plist~  2016-04-11 18:29:25.000000000 +0900
+++ Info.plist   2016-04-15 16:17:28.000000000 +0900
@@ -57,5 +57,10 @@
  <string>EditorApplicationPrincipalClass</string>
  <key>UnityBuildNumber</key>
  <string>b902ad490cea</string>
+ <key>NSAppTransportSecurity</key>
+ <dict>
+   <key>NSAllowsArbitraryLoads</key>
+   <true/>
+ </dict>
 </dict>
 </plist>

Alternatively, execute the following terminal command:

/usr/libexec/PlistBuddy -c "Add NSAppTransportSecurity:NSAllowsArbitraryLoads bool true" /Applications/Unity/Unity.app/Contents/Info.plist
References

Separate Mode

Specify separated: true to open WebView in a separate window:

webViewObject = (new GameObject("WebViewObject")).AddComponent<WebViewObject>();
webViewObject.Init(
#if UNITY_EDITOR
    separated: true
#endif
    ...);

This allows the use of the Safari debugger, based on pull request #161.

iOS

Enable WKWebView

WKWebView is supported but disabled by default. Enable it with:

webViewObject = (new GameObject("WebViewObject")).AddComponent<WebViewObject>();
webViewObject.Init(
    ...
    enableWKWebView: true);

cf.

This flag has no effect on platforms without WKWebView (e.g., iOS7 and Android) and should be set to true for iOS9 or later.

WKWebView Only Implementation for iOS9 or later

Apple now warns against using UIWebView APIs :

ITMS-90809: Deprecated API Usage - Apple will stop accepting submissions of apps that use UIWebView APIs . See https://developer.apple.com/documentation/uikit/uiwebview for more information.

The plugin includes two variations: Assets/Plugins/iOS/WebView.mm and Assets/Plugins/iOS/WebViewWithUIWebView.mm. Use WebView.mm for iOS9 or later. Modify #if __IPHONE_OS_VERSION_MIN_REQUIRED < __IPHONE_9_0 in these files if needed.

NOTE: WKWebView is available since iOS8 but was largely changed in iOS9, so we use ___IPHONE_9_0 instead of __IPHONE_8_0 NOTE: Several versions of Unity themselves also have the ITMS-90809 issue (cf. https://issuetracker.unity3d.com/issues/ios-apple-throws-deprecated-api-usage-warning-for-using-uiwebview-when-submitting-builds-to-the-app-store-connect )./

XMLHttpRequest for File URLs

WKWebView doesn't allow to access file URLs with XMLHttpRequest. This limitation can be relaxed by allowFileAccessFromFileURLs/allowUniversalAccessFromFileURLs settings. Those are however private APIs so currently disabled by default. For enabling them, please define UNITYWEBVIEW_IOS_ALLOW_FILE_URLS.

cf. https://github.com/gree/unity-webview/issues/785 cf. https://github.com/gree/unity-webview/issues/224#issuecomment-640642516

Android

Since Assets/Plugins/src is deprecated in recent Unity versions, we switched to .aar files (Android Archive Library). If you need to edit some AndroidManifest.xml files :

  1. Opening the pluginfolder of this repo in Android Studio
  2. Make somes changes (most of the time edit the plugin/Android/webview/src/main/AndroidManifest.xml).
  3. Build the app
  4. You will see your aar file in build/outputs/aar/
  5. Move this file to Assets/Plugins/Android/

File Input Field

The Android implementation uses Android Fragment for file input fields since here and may cause new issues that were not found before. If you don't need the file input field, you can install dist/unity-webview-nofragment.unitypackage or dist/unity-webview-nofragment.zip for selecting the variant without Fragment.

To enable file input fields, set the following permissions:

Set android.permission.WRITE_EXTERNAL_STORAGE in Player Settings/Other Settings/Write Permission and android.permission.CAMERA by defining UNITYWEBVIEW_ANDROID_ENABLE_CAMERA. (cf. Camera/Audio Permission/Feature).

Hardware Acceleration

Ensure the main activity has android:hardwareAccelerated="true":

Uses Cleartext Traffic

To allow cleartext traffic for API level 28 or higher, define UNITYWEBVIEW_ANDROID_USES_CLEARTEXT_TRAFFIC so UnityWebViewPostprocessBuild.cs adds android:usesCleartextTraffic="true".

Camera/Audio Permissions

To enable camera and microphone access:

For allowing camera access (navigator.mediaDevices.getUserMedia({ video:true })), please define UNITYWEBVIEW_ANDROID_ENABLE_CAMERA so that Assets/Plugins/Editor/UnityWebViewPostprocessBuild.cs adds the followings to AndroidManifest.xml,

  <uses-permission android:name="android.permission.CAMERA" />
  <uses-feature android:name="android.hardware.camera" />
  <queries>
    <intent>
      <action android:name="android.media.action.IMAGE_CAPTURE" />
    </intent>
  </queries>

and call the following on runtime.

        webViewObject.SetCameraAccess(true);

For allowing microphone access (navigator.mediaDevices.getUserMedia({ audio:true })), please define UNITYWEBVIEW_ANDROID_ENABLE_MICROPHONE so that Assets/Plugins/Editor/UnityWebViewPostprocessBuild.cs adds the followings to AndroidManifest.xml,

  <uses-permission android:name="android.permission.MICROPHONE" />
  <uses-feature android:name="android.hardware.microphone" />
  <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
  <uses-permission android:name="android.permission.RECORD_AUDIO" />

and call the following on runtime.

        webViewObject.SetMicrophoneAccess(true);

Details for each Unity version are the same as for hardwareAccelerated. Please also note that it is necessary to request permissions at runtime for Android API 23 or later as below:

diff --git a/sample/Assets/Scripts/SampleWebView.cs b/sample/Assets/Scripts/SampleWebView.cs
index a62c1ca..a5efe9f 100644
--- a/sample/Assets/Scripts/SampleWebView.cs
+++ b/sample/Assets/Scripts/SampleWebView.cs
@@ -24,6 +24,9 @@ using UnityEngine;
 using UnityEngine.UI;
 using UnityEngine.Networking;
 #endif
+#if !UNITY_EDITOR && UNITY_ANDROID
+using UnityEngine.Android;
+#endif
 
 public class SampleWebView : MonoBehaviour
 {
@@ -31,8 +34,29 @@ public class SampleWebView : MonoBehaviour
     public GUIText status;
     WebViewObject webViewObject;
 
+#if !UNITY_EDITOR && UNITY_ANDROID
+    bool inRequestingCameraPermission;
+
+    void OnApplicationFocus(bool hasFocus)
+    {
+        if (inRequestingCameraPermission && hasFocus) {
+            inRequestingCameraPermission = false;
+        }
+    }
+#endif
+
     IEnumerator Start()
     {
+#if !UNITY_EDITOR && UNITY_ANDROID
+        if (!Permission.HasUserAuthorizedPermission(Permission.Camera))
+        {
+            inRequestingCameraPermission = true;
+            Permission.RequestUserPermission(Permission.Camera);
+        }        
+        while (inRequestingCameraPermission) {
+            yield return new WaitForSeconds(0.5f);
+        }
+#endif
         webViewObject = (new GameObject("WebViewObject")).AddComponent<WebViewObject>();
         webViewObject.Init(
             cb: (msg) =>

(cf. https://github.com/gree/unity-webview/issues/473#issuecomment-559412496) (cf. https://docs.unity3d.com/Manual/android-RequestingPermissions.html)

navigator.onLine

Enable navigator.onLine by defining UNITYWEBVIEW_ANDROID_ENABLE_NAVIGATOR_ONLINE. The plugin will check Application.internetReachability and update WebView's setNetworkAvailable().

Margin Adjustment for Keyboard Popup

This plugin adjusts the bottom margin temporarily when the keyboard pops up to keep the focused input field displayed. This adjustment is however disabled for some cases (non-fullscreen mode or both portrait/landscape are enabled) to avoid odd behaviours (cf. https://github.com/gree/unity-webview/pull/809 ). Please define UNITYWEBVIEW_ANDROID_FORCE_MARGIN_ADJUSTMENT_FOR_KEYBOARD to force the margin adjustment even for these cases.

How to build WebViewPlugin-*.aar.tmpl

UnityWebViewPostprocessBuild.cs will select one of WebViewPlugin-*.aar.tmpl depending on EditorUserSettings.development. You can build these files as below:

  1. Install Unity 2019.4.40f1 with Android Build Support by Unity Hub.
  2. Open Terminal (mac) or Git Bash (windows), cd plugins/Android, and invoke ./install.sh.

If successful, you should find build/Packager/Assets/Plugins/Android/WebViewPlugin-*.aar.tmpl. install.sh has the following options:

Usage: ./install.sh [OPTIONS]

Options:

  --nofragment		build a nofragment variant.
  --development		build a development variant.
  --zorderpatch		build with the patch for 5.6.0 and 5.6.1 (except 5.6.1p4)

WebGL

NOTE: for Unity 2020.1.0f1 or newer, please use unity-webview-2020 instead of unity-webview below.

After importing dist/unity-webview.unitypackage or dist/unity-webview.zip, please copy WebGLTemplates/Default/TemplateData from your Unity installation to Assets/WebGLTemplates/unity-webview. If you utilize Unity 2018.4.13f1 for example,

$ cp -a /Applications/Unity/Hub/Editor/2018.4.13f1/PlaybackEngines/WebGLSupport/BuildTools/WebGLTemplates/Default/TemplateData Assets/WebGLTemplates/unity-webview

Then in Project Settings/Player/Resolution and Presentation, please select unity-webview in WebGL Template.

Star History

Star History Chart]