Tips and tricks for using WebGL on desktop and mobile (tested up to 2021.3.11f1)

[doctorpangloss]

@Sakuwwz

Hey Hi, anyone know how to detect closing the tab or browser?

$(document).blur(... unityInstance.sendMessage(...) ...) my dude, from https://api.jquery.com/blur/ and https://docs.unity3d.com/Manual/webgl-interactingwithbrowserscripting.html

[Sakuwwz]

@doctorpangloss

$(document).blur(... unityInstance.sendMessage(...) ...) my dude, from https://api.jquery.com/blur/ and https://docs.unity3d.com/Manual/webgl-interactingwithbrowserscripting.html

Thanks. Let me try and give an update first. Do you know how to close popup window, browser tab from the game instead of redirecting to a blank page?

[doctorpangloss]

@Sakuwwz

Thanks. Let me try and give an update first. Do you know how to close popup window, browser tab from the game instead of redirecting to a blank page?

That’s more of a general Javascript question. “You can’t close any tab via JavaScript. ‘This method (window.close) is only allowed to be called for windows that were opened by a script using the window.open method.’ In other words, you can only use JavaScript to close a window/tab that was spawned via JavaScript.”

[Sakuwwz]

@doctorpangloss

That’s more of a general Javascript question. “You can’t close any tab via JavaScript. ‘This method (window.close) is only allowed to be called for windows that were opened by a script using the window.open method.’ In other words, you can only use JavaScript to close a window/tab that was spawned via JavaScript.”

So, as I understood is, I need to call JS function from the script when player terminates the game. Isn’t it?

[BTrinity]

@doctorpangloss

Hi friends,

Here are some tips and tricks I’ve used to get great mobile WebGL builds that are fully compatible with mobile devices:

• InputField not being supported on mobile: I ended up making an on-screen keyboard in Unity, and it works fine! Don’t overthink it. Authoring a jslib that calls the javascript prompt works fine too. It has been mentioned elsewhere here a bajillion times.

• Use flexbox to layout your canvas, and build for a fixed size. I choose 375x635, since that’s the iPhone X layout, and my content is in the iPhone SE safe area of 320x568. Then, I use flexbox to position my canvas in the center, and a post-process step to replace the JSON’s background color. Grab my modified responsive template here. You can discover responsive design sizes by entering “Responsive Design Mode” in Safari (see https://imgur.com/a/AdrvUNa). Stop using stupid margin or padding or other dumb CSS tricks and get rid of all the crap that’s in the default frame. Just do the modern thing.

• Use asmdef to control what is Editor versus Player code. This improves your compile speed too.

• Always try to use a link.xml with high code stripping. There’s lots of documentation now about how link.xml works, but the overall jist is that the code stripper has a very hard time with static methods and third-party code. Be aggressive, don’t just give up and use Medium!

• Disable modules you don’t need in the Package Manager window. This will require modifying your external libraries.

• Use the Build Report Tool from the asset store to find assets and scripts you aren’t expecting to include in your build. For me, the biggest surprise was (1) System.Xml being referenced somewhere, and (2) plugins that pollute their Resources directory instead of using Editor Default Resources.

• Compile for both asm.js and wasm targets. iOS 13.0-13.1.2 do not work with WASM when the build is large, and iOS 12.1 and earlier do not work with Unity’s WASM at all, so you’ll need to always build asm.js for now.

• Use sprite atlases to fine-tune your 2D asset compression. They’re great for controlling which assets need alpha channels and which don’t, and which assets can use crunch compression and which can’t. You should set each sprite’s import settings to correspond to the import settings on the asset, or just use RGBA32 on the individual sprites. Otherwise, the atlas builder will use the compressed version as its input, which is obviously a UX smell but what can we do.

• Disable auto graphics and specify only WebGL 1.0. It’s the only engine supported by Safari for iOS, WebGL 2.0 as Unity implements it doesn’t work. There’s no point shipping around shaders or code for a WebGL 2.0 target you don’t really need.

• Use a UnityLoader.js and UnityLoader.min.js that doesn’t show a popup on mobile and switches to asm.js for iOS 12.1 and earlier. I modified them to fix this. You can copy the files from here into your /Applications/Unity/Hub/Editor/2018.3.13f1/PlaybackEngines/WebGLSupport/BuildTools directory or copy them using a post-processing step. Feel free to use your favorite diff tool to visualize what I changed. My minified version isn’t actually minified since it’s tricky to minify this code.

• Set Application.targetFramerate to -1. This ensures you use requestAnimationFrame to render your frames as quickly as possible.

• Use asm.js and the Profiler to pin down weird stuff. For example, I discovered that only on iOS, the first call to DateTime.Now took 2275ms! Since you don’t have deep profiling, you should familiarize yourself with Profiler.BeginSample and Profiler.EndSample. This is really slow and annoying but it is super informative for finding real issues.

• Native calls do not work in coroutines. They just don’t. A native call is one to a function with the [DllImport] attribute. That means if you use e.g. a websocket jslib and try to call a jslib declared method in the coroutine, it will silently fail.

• Enable demangling in your development builds. This gives you more useful stack traces: PlayerSettings.SetPropertyString("emscriptenArgs", "-s DEMANGLE_SUPPORT=1 -s ASSERTIONS=1 -s -Werror", BuildTargetGroup.WebGL);

• Use Unity’s native JSON. You really shouldn’t be using JsonFX/Newtonsoft/JsonObject, it will massively balloon your code size due to the compilation of generic specializations.

• Use WebAudio yourself, and activate it on a click. I use this for looping music. Contemporary browsers require you to .play() audio in a click. Set the handler using html onclick="playAudio()", otherwise the canvas will eat the clicks.

• Don’t be stupid with third party code. Asset store stuff is good because it works but it can be incredibly poorly written, accidentally referencing stuff like System.Xml, System.Data or System.Runtime and tank everything.

• Don’t be stupid with fonts. If you only need a single size and a single character set, configure it. If you can use Unity’s UGUI instead of TextMesh Pro, do it. But overall, avoid showing too much text in your game, since that’s what HTML is good for!

• Test on iOS devices. I know this scene is really big on Windows + Android but you gotta actually buy an iOS device and try it with your mobile site. You simply cannot reproduce the issues experienced by the ordinary user with the iOS Simulator that ships with XCode.

• Test for the appropriate Chrome build to test Android devices. My recommendation is Chrome 44, likely the oldest version of Chrome you’ll have to deal with in the real world that can actually play WebGL games distributed this way. I had to use a polyfill for enumerateDevices and fix the worker code in the 2018.3 loader to get it to work on this platform. Google how to download old Chromium builds. This platform doesn’t support WASM.

• Use a CDN, like CloudFront. You should definitely never serve directly from S3 or object buckets like that, because it’ll be way too slow over LTE.

• Use brotli compression. It’s so much better than GZip. If you plan to use CloudFront with an S3 origin, make sure to set the .unityweb file’s Content-Encoding to br, and use an https (with http redirect) configuration on your CDN because Chrome only decompresses br natively for you from TLS URIs. Executing this code from your project directory will fix the “Exception: Failed building WebGL player” you have

• Build with hashes. It’s imperative you build with hashes for simple setup with your CDN. Otherwise your assets will be perpetually mixed and buggy and you won’t really know why.

• For compatibility questions, use caniuse.com. This is helpful for platforms you don’t have. Unity3D needs localStorage and WebGL 1.0 in canvas support.

• Addressables is overrated. Since the content is decompressed and decoded on the main thread, your whole game will freeze, a worse experience that simply downloading the original content.

• Application.isMobilePlatform works. Use this to determine if you are on a mobile phone browser.

A 2017 iPhone X is extremely fast, and supports WASM in 12.2. Its graphics and CPU are significantly faster than a Nintendo Switch and any shipping Android device. I guarantee you can make a great-performing WebGL game in Safari as long as you don’t do anything stupid!

I tried following every step you did but i still cant to get the webgl working on any of my IOS mobile device . I tried with mac book / android phones / windows and etc works fine. but as for IOS mobile device the loading stuck at 90% even if i’m using Safari browser / chrome on Iphone X … anyone have any updates or solution on this ?

[ProtoTerminator]

@doctorpangloss

• Addressables is overrated. Since the content is decompressed and decoded on the main thread, your whole game will freeze, a worse experience that simply downloading the original content.

Addressables is exactly the same as Asset Bundles. The issue you speak of is solved by leaving the bundles uncompressed, then doing a gzip/brotli compression after they’re built. Then on your content server, set the headers as gzip/br and when it’s downloaded through addressables or assetbundles, the browser will automatically decompress them using whatever system resources it wants (off the main thread I think). Plus, once it’s decompressed, it will be stored in the indexedDB in an uncompressed state, thus improving your load times from cache (no need to decompresss).

[BogdanLysogora]

@BTrinity

I tried following every step you did but i still cant to get the webgl working on any of my IOS mobile device . I tried with mac book / android phones / windows and etc works fine. but as for IOS mobile device the loading stuck at 90% even if i’m using Safari browser / chrome on Iphone X … anyone have any updates or solution on this ?

Try select “asm.js” as a linker target for the build.

[De-Panther]

@De-Panther

Great post!

Regarding UnityLoader
I prefer to re-set the method that checks if mobile on the html page script, before calling UnityLoader.Instantiate, instead of editing UnityLoader.js, as I don’t want to rewrite the file in every install of new version of the engine

I guess it’s relevant here
https://gist.github.com/De-Panther/f08cb4902bd21ee403d579a12510be2c

[r8zbeh]

@doctorpangloss

• Compile for both asm.js and wasm targets. iOS 13.0-13.1.2 do not work with WASM when the build is large, and iOS 12.1 and earlier do not work with Unity’s WASM at all, so you’ll need to always build asm.js for now.

Hi @doctorpangloss
im aiming to build webgl for recent ios devices , do you still see that necessary to compile for asm.js ? my project with brotli compression format is about 250 MB, do you consider that as a large build ?( i havent had chance to upload it yet )
and as figures in https://caniuse.com/#feat=wasm , seems that wasm is now fully supported on all devices.

[ProtoTerminator]

@r8zbeh

Hi @doctorpangloss
im aiming to build webgl for recent ios devices , do you still see that necessary to compile for asm.js ? my project with brotli compression format is about 250 MB, do you consider that as a large build ?( i havent had chance to upload it yet )
and as figures in https://caniuse.com/#feat=wasm , seems that wasm is now fully supported on all devices.

If that’s the size of your build with everything in it, that’s huge! My entire project is about 190 MB, but most of that is assetbundles. The code is 3.6 MB and built-in assets are 2.0 MB. We just dynamically load our bundles as they are needed so that the initial load time is low.

iOS sucks! They “officially” support wasm, but that doesn’t mean it always works. iOS 12 worked with wasm, 13.0 and 13.1 broke wasm, and they “fixed” it with 13.2, but it still doesn’t load 100% of the time. I noticed a failure rate of ~10% when I was testing (not sure if it has gotten better since then, haven’t tested in a while). Asm seems to work 100% of the time, but is so slow, it’s unusable. What’s worse, with iOS 13, they started lying in the browser what device it is on iPads, so you can’t tell if it’s an iPad or a Mac to tell it to load wasm or asm.

[r8zbeh]

Thanks for your respond @ProtoTerminator

@ProtoTerminator

If that’s the size of your build with everything in it, that’s huge!.

huge to load or huge for ram? i assumed that in worst case it would occupy something like 2GB of ram, besides my projects are kinda light for cpu, mainly consist of textures

[eggtart]

I have been trying to make my webgl build work on ios mobile devices too, and it is really frustrating. Even on identical devices (say, 3 identical iPad Air 2), one will work and two got stuck at 90%. Sometimes it will depend on network speed, when I tried the ipads and iphones using the shop’s network, none will load. But if I connect them to my phone’s hotspot, all can load the app without any problem…

The build works great on desktop browsers and Android devices (interestingly, those devices can load fine though they are connected to the previouisly mentioned shop wifi network).

[r8zbeh]

@eggtart

one will work and two got stuck at 90%. .

this 90% stuck stems from low ram issue, how large is your build ? wasm or asm.js ?
try it on more recent ios devices

[eggtart]

My app is very small, the whole Build folder is only about 40MB. I am using the latest Unity version, so should be wasm.

I have tried on the latest ios devices (ipad, ipad air, iphone11, etc) and saw similar behavior. It is rather hit or miss. If network situation is good, then there is a higher chance of successfully loading the app. So strange…

[r8zbeh]

idont know exactly but as i tested a 40mb wasm build on my iphone6(1gb ram) , it stuck on 90% too.
i would try asm.js tomorrow but , its weird cuz safari officially supports wasm,and i read some unity testing benchmarks on safari three years ago , idk maybe its just doesnt work with ios safari !
just remember that if your gonno build as asm.js you should identify allocated ram too like : PlayerSettings.WebGL.memorySize = 256;

[eggtart]

Using the latest Unity version, no longer has the option to choose asm/wasm or to set memory size. Have tried on latest iOS models, still some can load and some cannot…

[r8zbeh]

its not in UI anymore because its deprecated but you can change it via editor script

using UnityEditor;
using UnityEngine;

[InitializeOnLoad]
class asm
{
    static asm()
    {
        PlayerSettings.WebGL.linkerTarget = WebGLLinkerTarget.Asm;
        PlayerSettings.WebGL.memorySize = 512;
    }
}

just put this script under Assets/Editor/
btw just keep that in mind that amount of ram which is gonno be occupied by your app isn’t defined by the build size actually ,it may differs so much based on your content , you could track it by Unity profiler under ram section/total ram allocated
as i own an iphone6 i can’t recommend my statistics to you ,but ill post here when i’m done to have a comprehensive
data to be comparable.
Just for everyone who may read this post in future i’m gonno post the memory allocation limit on ios devices :

device: (crash amount/total amount/percentage of total)

• iPad1: 127MB/256MB/49%
• iPad2: 275MB/512MB/53%
• iPad3: 645MB/1024MB/62%
• iPad4: 585MB/1024MB/57% (iOS 8.1)
• iPad Mini 1st Generation: 297MB/512MB/58%
• iPad Mini retina: 696MB/1024MB/68% (iOS 7.1)
• iPad Air: 697MB/1024MB/68%
• iPad Air 2: 1383MB/2048MB/68% (iOS 10.2.1)
• iPad Pro 9.7": 1395MB/1971MB/71% (iOS 10.0.2 (14A456))
• iPad Pro 10.5”: 3057/4000/76% (iOS 11 beta4)
• iPad Pro 12.9” (2015): 3058/3999/76% (iOS 11.2.1)
• iPad Pro 12.9” (2017): 3057/3974/77% (iOS 11 beta4)
• iPad Pro 11.0” (2018): 2858/3769/76% (iOS 12.1)
• iPad Pro 12.9” (2018, 1TB): 4598/5650/81% (iOS 12.1)
• iPad 10.2: 1844/2998/62% (iOS 13.2.3)
• iPod touch 4th gen: 130MB/256MB/51% (iOS 6.1.1)
• iPod touch 5th gen: 286MB/512MB/56% (iOS 7.0)
• iPhone4: 325MB/512MB/63%
• iPhone4s: 286MB/512MB/56%
• iPhone5: 645MB/1024MB/62%
• iPhone5s: 646MB/1024MB/63%
• iPhone6: 645MB/1024MB/62% (iOS 8.x)
• iPhone6+: 645MB/1024MB/62% (iOS 8.x)
• iPhone6s: 1396MB/2048MB/68% (iOS 9.2)
• iPhone6s+: 1392MB/2048MB/68% (iOS 10.2.1)
• iPhoneSE: 1395MB/2048MB/69% (iOS 9.3)
• iPhone7: 1395/2048MB/68% (iOS 10.2)
• iPhone7+: 2040MB/3072MB/66% (iOS 10.2.1)
• iPhone8: 1364/1990MB/70% (iOS 12.1)
• iPhone X: 1392/2785/50% (iOS 11.2.1)
• iPhone XS: 2040/3754/54% (iOS 12.1)
• iPhone XS Max: 2039/3735/55% (iOS 12.1)
• iPhone XR: 1792/2813/63% (iOS 12.1)
• iPhone 11: 2068/3844/54% (iOS 13.1.3)
• iPhone 11 Pro Max: 2067/3740/55% (iOS 13.2.3)

you could find the ongoing post here :
https://stackoverflow.com/questions/5887248/ios-app-maximum-memory-budget/15200855#15200855

• please post your experiences with mentioning your ios device model/ios version/build size/build format here to help others

[eggtart]

Seems not that related to the project size. When it can’t load, it can’t load and will stuck at 90%. Even for the latest model like the iPhone 11 Pro.

[r8zbeh]

@eggtart

Seems not that related to the project size. When it can’t load, it can’t load and will stuck at 90%. Even for the latest model like the iPhone 11 Pro.

may you do the same thing as i did in the post below with newest ios device you have and share the results
(just add few more maps to test the limit)
https://discussions.unity.com/t/788831
for me it run with 3 4k maps.and stuck on 4.

[LeFx_Tom]

@doctorpangloss

Hi friends,

• Application.isMobilePlatform works. Use this to determine if you are on a mobile phone browser.

First…thanks a lot for all the Infos…really strong and helpful stuff…
Unfortunately…this is seemingly not correct.

I deploy to IPads with iOS 13.3, 13.4, 13.5…it always responds with Application.isMobilePlatform = false (maybe because it’s not a Phone, but a Tablet?)

Anyway…so far, i haven’t found any solution to determine, whether i am running on iPad or Mac…because all the SystemInfo-Callbacks return crap as well (OS returns as MacOS, deviceType returns as Safari)

Any other recommendations to that?