Skip to main content

​
Frequently Asked Questions

Common questions and solutions for platform setup, authentication, errors, and integration with the Unity SDK.

​
Platform & Testing

Yes, you can test the SDK using the Unity Editor for Android and iOS on both Mac and Windows. However, the native Android and iOS WebViews cannot run in the editor. The macOS WebView is used for the Mac Unity Editor, and the Windows WebView is used for the Windows Unity Editor.
Testing StageEnvironmentPurpose
DevelopmentUnity EditorQuick iteration on logic
IntegrationAndroid/iOS EmulatorTest mobile WebView behavior
Final QAPhysical DeviceTest performance & real hardware
Set up emulators early in development. Editor testing alone will miss mobile-specific issues.
You’re attempting to run an Android/iOS game in the Unity Editor. Native Android/iOS WebViews cannot run in the Unity Editor—the Editor uses desktop WebView (macOS or Windows) instead.You must run your game through an Android/iOS emulator or device, or switch your build target to “PC, Mac & Linux Standalone” in File → Build Settings for Editor testing.
Always test on real devices before production. Emulators don’t catch all issues.
Our SDK doesn’t provide out-of-the-box support for IL2CPP on Windows. However, you can integrate a third-party Unity Windows WebView that supports IL2CPP, such as Vuplex.See our custom Windows WebView documentation for detailed instructions.
IL2CPP is supported on Android and iOS. Windows requires additional WebView integration.
The Immutable Game SDK supports only the regions that Immutable Passport supports.Passport is a globally available product. However, our wallet infrastructure is subject to the regulation of the US Department of the Treasury’s Office of Foreign Assets Control (“OFAC”). OFAC administers and enforces comprehensive and targeted economic and trade sanctions programs on multiple countries and regions.Users attempting to access Passport in any of the regions under OFAC sanction will have their access blocked and will be unable to use our product. Additionally, components of Passport’s infrastructure also rely on technology provided by Magic, which maintains further details regarding unsupported regions on their website here.

​
Authentication

This is not possible due to security reasons. Vendors like Google also block login through webviews because the hosting applications can steal credentials.
Never use WebView for authentication. It’s a security risk and violates OAuth best practices.
See Why is the in-app browser used for Passport login on mobile and not a webview? for more details.
The in-app browser is specifically designed for single sign-on (SSO) purposes, making it a much more secure option. This browser runs on a separate process from the hosting game, meaning the game cannot access it, modify any content, or inject malicious code.
FeatureIn-App BrowserWebView
Process isolation✅ Separate process❌ Same process as app
App can inject code❌ No✅ Yes (security risk)
App can intercept requests❌ No✅ Yes (security risk)
Designed for SSO✅ Yes❌ No
WebView gives the hosting game full control, allowing it to intercept requests and inject JavaScript. This is why OAuth providers like Google block WebView authentication.Platform implementations:
To securely implement PKCE, we must use ASWebAuthenticationSession, which shows an alert. This alert cannot be removed or modified as the operating system triggers it.
This is a security feature designed to protect users from unauthorized authentication attempts. Any attempt to bypass it will cause app rejection.
Learn more about ASWebAuthenticationSession
This error occurs because you are attempting to log in using a WebView instead of a browser. Google blocks authentication attempts from WebViews because they can be exploited to steal user credentials. The hosting app has full control over WebView content, including the ability to inject JavaScript and intercept requests.Use the system browser or in-app browser (SFSafariViewController/Chrome Custom Tabs) instead of WebView. The Unity SDK uses the system browser by default.Refer to Can I log in using a WebView instead of opening the browser? for more information.

​
Errors & Troubleshooting

If you encounter a TimeoutException, it indicates that the function you called took more than one minute to return a response. Although this is the default timeout value, the timeout can be customized using the SetCallTimeout function.
// Increase timeout globally
passport.SetCallTimeout(120); // 2 minutes

// For blockchain transactions
passport.SetCallTimeout(180); // 3 minutes
To identify the specific function that caused this exception, check the bottom of the stack trace or the logs generated before the exception was thrown.
For blockchain transactions, consider increasing timeout to 180 seconds (3 minutes) to account for network congestion.
Our SDK includes a post-process script that copies an index.html file required to run the SDK.This error could be because the files weren’t copied correctly to the build. Check if you got the message “Successfully copied Passport files” in the console output during build.Another reason for this error could be that the path to the index.html file is unexpected. We try to cover all the possible cases in our SDK, but if you suspect this is the problem, please create a GitHub issue.
These errors are usually caused by missing large files stored in Git Large File Storage (Git LFS). Make sure Git LFS is installed before cloning the repository.Versions later than v1.36.9 no longer bundle a fork of Unity Web Browser (UWB). Instead, Windows embedded WebView support is provided either by Vuplex WebView or by an optional integration with the official Unity Web Browser packages.You will usually see this error when you’re using an older SDK version that still expects bundled UWB binaries and those .dll files are missing (for example because Git LFS wasn’t installed), or when you’ve installed Unity Web Browser as an optional dependency but one or more of its engine packages / assemblies are missing or misconfigured.
We strongly recommend upgrading to the latest version of the Unity SDK to avoid Git LFS issues entirely.
If using latest SDK:
  • If you want to use UWB for Windows desktop, follow the WebView Setup docs
  • Otherwise, rely on Vuplex WebView for embedded flows
If using older SDK (< v1.36.9):
  • Install Git LFS before cloning the repository so that the UWB .dll files are downloaded correctly
  • If the issue persists, reinstall Git LFS and try a fresh clone
This error is commonly caused by using an incompatible Application Entry Point. The Immutable SDK only supports Activity, not GameActivity.Try the following:
  1. Set your Application Entry Point to Activity in Project Settings → Player → Android → Other Settings → Configuration → Application Entry Point
  2. Open your AndroidManifest.xml file and remove the UnityPlayerGameActivity activity block, keeping only the UnityPlayerActivity block
Unity 6 changed the default Application Entry Point to GameActivity. You must manually change it back to Activity for Immutable SDK compatibility.
If this doesn’t resolve the issue, please raise an issue in the Immutable Unity SDK repository.
Android minification can obfuscate SDK classes, breaking authentication. Please refer to this section of our documentation for the required ProGuard configuration.
Always test with minification enabled before production to catch ProGuard issues early.
Please try the following items to see if the issue goes away:
  1. Before starting your game, check the Task Manager for Chrome Embedded Framework (CEF) and kill it if it’s running. Our code handles this, but you may need to do it manually.
  2. Restart your computer.
  3. Increase the engine start-up timeout in the Passport.Init function here.
Our code attempts to kill CEF automatically, but you may need to do it manually in some cases.
This error indicates that Unity Web Browser’s Chrome Embedded Framework (CEF) engine is not installed correctly or cannot be found at runtime.To fix this, ensure that you have installed the correct Unity Web Browser packages for Windows:
  • dev.voltstro.unitywebbrowser
  • dev.voltstro.unitywebbrowser.engine.cef
  • dev.voltstro.unitywebbrowser.engine.cef.win.x64 (for 64-bit Windows builds)
After installing these packages, re-open your project so Unity can import the assets and regenerate any required configuration.
UWB is an optional, Windows-only dependency. If it is not installed, Passport will fall back to using the system browser or any custom IWindowsWebBrowserClient implementation you provide.

​
Getting Started & Integration

Check out our tutorial on how to integrate Immutable zkEVM into a Unity game in our Build a game with Unity series.Additional resources:
You can use the zkEVM Send Transaction function in the Unity SDK to call your smart contract crafting function.
// Example: Call crafting contract function
string txHash = await passport.ZkEvmSendTransaction(new TransactionRequest
{
    To = craftingContractAddress,
    Data = craftingFunctionData  // Encoded function call
});
For an example of how to perform crafting in a Unity game, you can refer to our Unity sample game.
Crafting typically involves calling a smart contract that burns input NFTs and mints a new crafted NFT.
It is possible to adapt the architecture and implementation of our SDK for use in your custom engine. There are two main aspects you need to understand:
  1. Communication between the Game SDK and the TypeScript SDK packages
  2. Presentation of the PKCE flow on Android, iOS, and macOS
Game SDK and TypeScript SDK packages
ComponentDescription
Index fileThe index file serves as a bridge between the Game SDK and the TypeScript SDK. The game-bridge package enables the Game SDK to interact with the necessary TypeScript SDK packages (e.g. passport, config, x-provider) using string-based communication. For Unity, the required TypeScript SDK packages and the game-bridge package are bundled into an HTML file. This index file is then loaded into an invisible WebView within the Game SDK.
Invisible WebViewThe invisible WebView loads the index file in the Game SDK. The implementation varies across platforms: Android uses Android native WebView; iOS and macOS use Apple native WKWebView; Windows uses Unity Web Browser (UWB) when installed, or any custom Windows WebView that implements IWindowsWebBrowserClient.
PKCE flow presentationAn in-app browser is used for the PKCE flow as it is designed for single sign-on (SSO) purposes:Native code (Android, iOS, macOS) is written for each platform to launch the in-app browser from the Game SDK and handle deep linking into the game.Adapting for Your Custom Engine
  • Reuse the Index File: You can reuse our index file, but you may need to rewrite how it communicates with the WebView. This involves modifying the callbackToGame() function in the TypeScript SDK’s game-bridge/index.ts file. After making your changes, you must bundle and generate the index file (refer to our README).
  • Reuse WebView Implementation: You can reuse most of our WebView implementations as they are written in the platform’s native languages. However, you must adapt the communication between your custom engine and the WebView.
  • Reuse PKCE Implementation: Similar to the WebView implementations, most PKCE implementations can be reused as they are written in the platform’s native languages. However, you must adapt the communication between your custom engine and the native code.
The Game SDK is lightweight—essentially a wrapper around the TypeScript SDK. Most complexity is in the bridge and WebView communication.

​
Still Need Help?

Unity SDK

Complete Unity SDK documentation

GitHub Issues

Report Unity SDK issues

Support

Contact support team

Documentation

Browse all documentation