Merge pull request #298 from immutable/feature/dx-3321-webgl-quickstart

[DX-3321]webgl quick start guide

Author: andrew-yangy

.github/workflows/linter.yml

@@ -57,7 +57,7 @@ jobs:
           VALIDATE_ALL_CODEBASE: true
           DEFAULT_BRANCH: main
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          FILTER_REGEX_EXCLUDE: (.*src/Packages/Passport/Runtime/ThirdParty/.*|.*src/Packages/Passport/Runtime/Resources/.*|.*Plugins/.*|.*src/Packages/Passport/Runtime/Assets/ImmutableAndroid.androidlib/.*|.*src/Packages/Orderbook|.*sample)
+          FILTER_REGEX_EXCLUDE: (.*src/Packages/Passport/Runtime/ThirdParty/.*|.*src/Packages/Passport/Runtime/Resources/.*|.*Plugins/.*|.*src/Packages/Passport/Runtime/Assets/ImmutableAndroid.androidlib/.*|.*src/Packages/Orderbook|.*sample|.*src/Packages/Passport/WebGLTemplates)
           VALIDATE_MARKDOWN: false
           VALIDATE_GITLEAKS: false
           VALIDATE_JSCPD: false

WebGL.md

@@ -0,0 +1,75 @@
+# Implementing Immutable Unity SDK for WebGL
+
+This guide provides focused instructions for implementing the Unity-Immutable-SDK in WebGL projects.
+
+For general information on the SDK, please refer to
+the [Immutable Unity SDK documentation](https://docs.immutable.com/sdks/zkEVM/unity).
+
+Live example can be found at https://immutable.github.io/unity-immutable-sdk/sample/webgl
+
+## WebGL Template Setup
+
+WebGL template is a configuration setting that lets you control the appearance of the HTML page, so that you can: test, demonstrate, and preview your WebGL application in a browser.
+
+A WebGL Template is always needed for creating a WebGL application and it will always be stored within **Assets > WebGL Templates** to be used. You can refer to [Unity: WebGL Templates](https://docs.unity3d.com/Manual/webgl-templates.html) for more information.
+
+A Custom WebGL Template is required to implement the Immutable Unity SDK in WebGL projects. The easiest way to create a new custom WebGL template is to make a copy of the built-in Default or Minimal templates, which are stored in corresponding subfolders under <Unity Installation> > PlaybackEngines > WebGLSupport > BuildTools > WebGLTemplates.
+
+Every Unity Project includes these templates by default. Copy a template and place it in your own **Assets > WebGLTemplates** folder, and rename it to something meaningful so you can identify your template later.
+
+Once you have created your own template, copy the following files from Passport package into the **Assets > WebGLTemplates** folder:
+   - `Packages/Immutable Passport/WebGLTemplates~/unity-webview.js`
+   - `Packages/Immutable Passport/WebGLTemplates~/callback.html`
+   - `Packages/Immutable Passport/WebGLTemplates~/logout.html`
+   - `Packages/Immutable Passport/Runtime/Resources/index.html` > `Passport/index.html`
+
+3. Add the following script tag to the `index.html` in WebGL Templates:
+   ```html
+   <script src="unity-webview.js"></script>
+   ```
+
+## PKCE Login and Logout Implementation
+> [!IMPORTANT]  
+> WebGL supports only PKCE flow.
+
+Follow these steps for implementation:
+> [!NOTE]
+> You can rename `callback.html` and `logout.html` to suit your project needs.
+1. Define a deep link scheme for your game:
+   - Redirect URL: https://game.domain.com/callback.html
+   - Logout URL: https://game.domain.com/logout.html
+
+2. Configure Immutable Hub:
+   - Login to [Immutable Hub](https://hub.immutable.com)
+   - Add these deep links to your client's Redirect URLs and Logout URLs
+
+3. Update Passport initialisation:
+```csharp
+using System.Collections;
+using System.Collections.Generic;
+using UnityEngine;
+using Immutable.Passport;
+
+public class InitPassport : MonoBehaviour
+{
+    private Passport passport;
+
+    async void Start()
+    {
+        string clientId = "YOUR_IMMUTABLE_CLIENT_ID";
+        string environment = Immutable.Passport.Model.Environment.SANDBOX;
+        string redirectUri = "https://game.domain.com/callback.html";
+        string logoutRedirectUri = "https://game.domain.com/logout.html";
+        passport = await Passport.Init(clientId, environment, redirectUri, logoutRedirectUri);
+    }
+}
+```
+
+## Building for WebGL
+1. Go to File > Build Settings
+2. Select WebGL as the target platform
+3. Click "Build And Run"
+4. Choose a directory for the build output
+Your WebGL application will open in your default web browser once the build is complete.
+
+For a complete working example, refer to the sample application in the SDK repository.

sample/Assets/WebGLTemplates.meta

@@ -41,8 +41,6 @@ var unityWebView =
 
         loadURL: function(name, url) {
             var baseUrl = window.location.origin + window.location.pathname.replace(/\/[^\/]*$/, "");
-            console.log(url, window.location.origin, window.location.pathname);
-            console.log(baseUrl);
             const host = window.location.origin.includes('localhost') ? window.location.origin : baseUrl;
             this.iframe(name).attr('loaded', 'false')[0].contentWindow.location.replace(host + url);
         },

sample/Assets/WebGLTemplates/unity-webview.meta

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en-us">
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <title>Unity WebGL Player | Immutable SDK Sample App</title>
+    <link rel="shortcut icon" href="TemplateData/favicon.ico">
+    <link rel="stylesheet" href="TemplateData/style.css">
+    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
+    <script src="unity-webview.js"></script>
+</head>
+<body>
+<div id="unity-container" class="unity-desktop">
+    <div id="unity-build-title">Logging in</div>
+</div>
+<script>
+    window.opener.postMessage({
+        type: 'callback',
+        url: window.location.href,
+    });
+    window.close();
+</script>
+</body>
+</html>

sample/Assets/WebGLTemplates/unity-webview/Passport.meta

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en-us">
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <title>Unity WebGL Player | Immutable SDK Sample App</title>
+    <link rel="shortcut icon" href="TemplateData/favicon.ico">
+    <link rel="stylesheet" href="TemplateData/style.css">
+    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
+    <script src="unity-webview.js"></script>
+</head>
+<body>
+<div id="unity-container" class="unity-desktop">
+    <div id="unity-build-title">Logging out</div>
+</div>
+<script>
+    window.opener.postMessage({
+        type: 'logout',
+        url: window.location.href,
+    });
+    window.close();
+</script>
+</body>
+</html>

sample/Assets/WebGLTemplates/unity-webview/Passport/index.html.meta

@@ -0,0 +1,70 @@
+var unityWebView =
+    {
+        loaded: [],
+
+        init: function(name) {
+            $containers = $('.webviewContainer');
+            if ($containers.length === 0) {
+                $('<div style="position: absolute; left: 0px; width: 100%; height: 100%; top: 0px; pointer-events: none;"><div class="webviewContainer" style="overflow: hidden; position: relative; width: 100%; height: 100%; z-index: 1;"></div></div>')
+                    .appendTo($('#unity-container'));
+            }
+            var $last = $('.webviewContainer:last');
+            var clonedTop = parseInt($last.css('top')) - 100;
+            var $clone = $last.clone().insertAfter($last).css('top', clonedTop + '%');
+            var $iframe =
+                $('<iframe style="position:relative; width:100%; height100%; border-style:none; display:none; pointer-events:auto;"></iframe>')
+                    .attr('id', 'webview_' + name)
+                    .appendTo($last)
+            $iframe.on('load', function () {
+                $(this).attr('loaded', 'true');
+
+                var js = `window.Unity = {
+                            call:function(msg) {
+                                        parent.unityWebView.sendMessage('${name}', msg);
+                                    }
+                            };`;
+
+                this.contentWindow.eval(js);
+
+                window.addEventListener('message', function(event) {
+                    if ((event.data.type === 'callback' || event.data.type === 'logout') && event.isTrusted) {
+                        unityInstance.SendMessage(name, 'CallOnAuth', event.data.url);
+                    }
+                }, false);
+            });
+            return $iframe;
+        },
+
+        sendMessage: function (name, message) {
+            unityInstance.SendMessage(name, "CallFromJS", message);
+        },
+
+        loadURL: function(name, url) {
+            var baseUrl = window.location.origin + window.location.pathname.replace(/\/[^\/]*$/, "");
+            const host = window.location.origin.includes('localhost') ? window.location.origin : baseUrl;
+            this.iframe(name).attr('loaded', 'false')[0].contentWindow.location.replace(host + url);
+        },
+
+        evaluateJS: function (name, js) {
+            $iframe = this.iframe(name);
+            if ($iframe.attr('loaded') === 'true') {
+                $iframe[0].contentWindow.eval(js);
+            } else {
+                $iframe.on('load', function(){
+                    $(this)[0].contentWindow.eval(js);
+                });
+            }
+        },
+
+        destroy: function (name) {
+            this.iframe(name).parent().parent().remove();
+        },
+
+        iframe: function (name) {
+            return $('#webview_' + name);
+        },
+
+        launchAuthURL: function(name, url) {
+            window.open(url, '_blank', 'width=460,height=660');
+        },
+    };