Games in Unity
Unity Game on Android TV

27min
An AirConsole app for AndroidTV is available on the Google Play store. Unfortunately, the AndroidTV cannot run the WebGL versions of Unity games that we have in the AirConsole store. In order to run your Unity-made AirConsole games on Android TV, you need to create a native Android Build instead of the regular WebGL build. Some adjustments may have to be made to your game project, as detailed in this guide.
When you switch platforms to Android and export your game to an AndroidTV, the AirConsole Plugin creates a webview that shows AirConsole content within your AndroidTV App.
Following this guide will give you an APK file which can then be uploaded to the Google Play Store. If you are thinking about porting your AirConsole game to AndroidTV, please contact us beforehand.
We have additional Unity version specific information at the end of this guide. Make sure to read it to avoid problems with your build process.
Tools
You want to make sure your Unity Version is the latest Unity LTS version suitable for your game to be compatible with AndroidTV requirements:
2022.3
2021.3
Make sure your AirConsole Plugin version is 2.11 or higher.
Install the Unity SDK and NDK that can be installed as part of the Android Module in Unity Hub.
﻿
Platform
Before you start working on your AndroidTV Port, it's important that you have uploaded a .zip of your WebGL build to airconsole.com/developers and create the Game ID which we will need for the next steps. Read the "Publish your game" guide which explains how to upload your game.
In File→Build Settings, choose 'Android'. Reimporting assets for the platform might take a moment.

﻿
BundleID
Go to Edit→Project Settings→Player.
In the Other Settings tab, you'll find the parameter Bundle Identifier. For your AndroidTV build to work, this needs to be identical with the Game ID that you've given your game on airconsole.com/developers. N.B: It can also be called "Package Name" on some unity versions.
ATTENTION:
The Bundle Identifier can not include com.airconsole.*.
﻿
﻿
Configuring the Android platform
Starting with Unity LTS 2021, Unity no longer includes OpenGL ES2 in builds with Auto Graphics API enabled in the Android Player Settings. You need to disable Auto Graphics API and manually add it back.
﻿
Screen and Controller Data
In order for your exported game to be able to access the controller and all necessary JavaScript and image files, you need to:
Have a WebGL build with all needed screen and controller Data uploaded to airconsole.com/developers﻿
Copy the Game upload version number of your game.
﻿
Paste the number into the Android TV Game Version field on the AirConsole GameObject in your Scene.
﻿
Save your scene and create an Android build. The gameName.apk file you get can be deployed to your AndroidTV device.
OnReady / OnGameEnd
Users can return to the AirConsole store by selecting 'Change Game' on their phone without leaving your Android App. Because of that, you need to mute all sound in your game in the OnGameEnd event, like you would in the OnAdShow event. Pause / stop as much of your game as you can to make sure no unnecessary computation is happening behind the web view after users have chosen to 'Change Game'.
Similarly, only start playing your game's sound/music in the OnReady event, not on Start / Awake / Scene Loaded.
Loading Screen Sprite
You can choose a custom loading screen logo to be displayed when your game starts on Android TV. If there is none, a default AirConsole logo will be displayed.
﻿
UI
On AndroidTV, the AirConsole Default UI bar will be laid over the game.The Default UI shows the AirConsole Logo, the session code and connected players' portraits and connection statuses.
To make sure your UI is displayed correctly despite the cutoff at the top, the AirConsole Object offers three options on how to deal with Canvases.
﻿
No Resizing
Your UI is left as it is, but the Default UI is laid over. If you choose this option you can either:
Manually adjust your UI so that nothing important will be cut off at the top.

Resize Camera
The height of the default UI is subtracted from the MainCamera's pixelRect. On your Canvas, set RenderMode to Screen Space - Camera. Now, if your UI elements' RectTransforms are correctly anchored, they will not be cut off by the default UI. Resizing the Camera will change its aspect ratio.

Resize Camera and Reference Resolution
The camera is resized as described in option 2). In addition, the Reference Resolution of your Canvas Scalers is adjusted to keep the aspect ratio it had before. This will ensure that UI elements are placed correctly in relation to the 3D elements in your game scene. It means, however, that your canvas is narrower than your Camera.
Execution Order: The resizing happens in the OnLevelWasLoaded event. Do not depend on the order of OnLevelWasLoaded being before or after the OnEnable/Awake/Start Events.
Nested Canvases: We recommend not using nested canvases (i.e. a canvas as child of another canvas). Using nested canvases can lead to issues with some of the resizing options.
Performance
Even if your game is already well-optimized for Web, you may run into performance issues on AndroidTV. To test and improve performance, we recommend implementing an FPS counter in your game and testing on the targeted hardware frequently.
Testing: If you do not own an Android TV device for testing, we recommend testing on an android phone instead. Once you have a working build, send it to us and we will test it on our Android TV devices. This is especially useful for testing UI adjustments and camera resizing.
If your games performance is insufficient and the Unity mobile optimisation tips were insufficient for Android TV, we have the following additional advise:
Use multiple quality levels for your game driven by SystemInfo.GraphicsDeviceType:

A low quality for hardware that is used when the device only supports OpenGL ES2. Limit the maximum shader quality level / use low end mobile optimized approximations of the shaders, disable shadows, limit pixel lights to 1 and Anti-Aliasing to None or MSAAx2, limited or no anisotropic texture filtering.
A higher quality level based on OpenGL ES3 or Vulkan that can use more pixel lights, some amount of shadows, MSAAx4 and AA filtered textures.

The hardware can support a maximum of 400 pure static batches / draw calls.

Ensure that all textures are compressed to reduce load time and memory usage while improving performance. Optimally you would want ETC1 or distinct assetbundle/addressable levels for low end Android TV devices and the other platforms.

Disable post-processing and visual effects on your camera if you detect that you are on a low performance device.

Reduce transparent geometry, avoid using big, transparent sprites or dense particle effects.

Reducing the resolution of your game with Screen.SetResolution() can be a solution to performance issues. If you do resize your game, call SetResolution in a Start event, not in Awake.

Avoid using the Unity Scriptable RenderPipeline (URP, LWRP): It is not optimized for OpenGL ES2 creating significant performance problems. 

Make use of the UnityEngine.Profiling.ProfilerRecorder with Memory Markers and Rendering Markers to identify runtime performance in release build.
- If you need more detail, make development builds with the Autoconnect Profiler option enabled and see what has impact on performance
We recommend trying out one of these optimizations at a time and see which have impact, if necessary.
Release Build
Once your game is ready for release, there are a few more things to consider:
Debug Build
Make sure the build you send is not a DEBUG build. Make sure to uncheck the Development Build checkbox in your Unity Build settings.
Key & Key Store
You need to sign your APK for release. To do so, you can create a new keystore in the Player Settings.
Version
﻿
Versions are used to determine the version of the build. This versions is very important on the Android store listings and for our QA to review and activate the respective game.
Please always increase the version if you create a new version for review.
Bundle Code
The Bundle Code is an integer that is used to determine whether one version is more recent than another, with higher numbers indicating more recent versions. You must increase the number by one every time you release a new version - the same bundle code cannot be used twice.
Note: A bundle number may count as 'used' even when the build was not actually released publicly. To be on the safe side, increase your bundle code every time you send us a new build during the release process.
Android Manifest
The Android Manifest is an .xml file that provides essential information about your app to the Android system, which the system must have before it can run any of the app's code.
In the manifest, you also determine which devices your game supports. The default AirConsole Android Manifest that we include in our plugin assumes you want your game to appear only on Android TV systems (which use the “leanback” Android UI) and not on Android Tablets.
If you want your AirConsole game to be playable on Android Tablets as well, simply remove the following lines from the Android Manifest:
<uses-feature
android:name="android.software.leanback"
android:required="true" />

<category android:name="android.intent.category.LEANBACK_LAUNCHER" />
Screen Orientation
On some devices, the screen orientation needs to be set explicitly. Make sure Screen Orientation is set to "landscape" in your Android Manifest: android:screenOrientation="landscape". More information here﻿
Target API
To support a wide range of devices, the minimum API Level has to be set down to API Level 22 and the target API Level to API Level 33 (at least).
﻿
Build for Android 13 with Unity
To support Android 13 (API level 34), the package visibility element was added to the AirConsole Unity plugin (v2.6 or later).
Unity version specific configuration gradle configurations
Instructions for supported versions of Unity are listed in the following sections. Versions of Unity that do not support customization of Gradle are unable to target Android 13 (API level 34) (Target API level 34) directly from a Unity build.
Unity 2021 and newer
Go to Project Settings > Player > Android tab > Publishing Settings > Build, and select both:
﻿Custom Main Gradle Template﻿
﻿Custom Launcher Gradle Template﻿
﻿
Apply the following changes to both generated files:
﻿Assets/Plugins/Android/mainTemplate.gradle﻿
﻿Assets/Plugins/Android/launcherTemplate.gradle﻿
If present because the project was upgraded from an older Unity version, remove any block similar to the following commonly at the beginning of the file:
Please note: The AirConsole SDK Version 2.11 and before also provided these in its template, so when upgrading the AirConsole Unity SDK you need to remove these blocks from the templates.
      buildscript {
          repositories {
              google()
              jcenter()
          }
          dependencies {
              // Must be Android Gradle Plugin 3.6.0 or later. For a list of
              // compatible Gradle versions refer to:
              // https://developer.android.com/studio/releases/gradle-plugin
              classpath 'com.android.tools.build:gradle:3.6.0'
          }
      }

      allprojects {
         repositories {
            google()
            jcenter()
            flatDir {
              dirs 'libs'
            }
         }
      }
Replace the following block if it is present:
}**PACKAGING_OPTIONS****SPLITS**
with the following block:
**PACKAGING_OPTIONS****PLAY_ASSET_PACKS****SPLITS**
to enable Unity to work with Android AAB + PAD.
Unity 2019.3 and 2019.4
Note: The following customization is supported only by Unity 2019.3.7f1 or later.
Go to Project Settings > Player > Android tab > Publishing Settings > Build, and select both:
﻿Custom Main Gradle Template﻿
﻿Custom Launcher Gradle Template﻿
﻿
Apply the following changes to both generated files:
﻿Assets/Plugins/Android/mainTemplate.gradle﻿
﻿Assets/Plugins/Android/launcherTemplate.gradle﻿
If present, remove any block similar to the following which are leftover from Unity 2020 and before:
Please note: The AirConsole SDK Version 2.11 and before also provided these in its template, so when upgrading the AirConsole Unity SDK you need to remove these blocks from the templates.
buildscript {
repositories {
    google()
    jcenter()
}
dependencies {
    // Must be Android Gradle Plugin 3.6.0 or later. For a list of
    // compatible Gradle versions refer to:
    // https://developer.android.com/studio/releases/gradle-plugin
    classpath 'com.android.tools.build:gradle:3.6.0'
}
}

allprojects {
repositories {
  google()
  jcenter()
  flatDir {
    dirs 'libs'
  }
}
}
Replace the following block:
}**PACKAGING_OPTIONS****SPLITS**
with the following block:
**PACKAGING_OPTIONS****PLAY_ASSET_PACKS****SPLITS**
to enable Unity to work with Android AAB + PAD.
Unity 2018.3 or earlier, including 2017
Gradle customizations are not supported on these versions of Unity and are not compatible with the necessary changes to support Android 13 (API level 34).
Build deliverables
In order to be launched in the Google Play store, we need an AAB file (As small as possible) The non-data part may not be bigger than 150MB. If your AAB is bigger than 150MB and Unity can not address it by using Play Asset Distribution, it will inform you.
For more information, see Unity documentation on AAB and PAD support.
In order to be launched in the Amazon Appstore, we need an APK file (As small as possible). APKs may not be bigger than 100MB. If your APK is bigger than 100MB, it needs to be split into an APK and an OBB file. To split it, simply check theSplit Application Binarycheckbox in Player Settings --> Publishing Settings.
For more information, see Unity documentation on OBB support.
﻿
AirConsole is working with several distribution partners and not all systems support OBB files. If your APK's size exceeds 100MB, send us both the big, un-split APK as well as the split APK and corresponding OBB file.
Android Build System
In order for video ads to be displayed correctly, thehardwareAcceleratedparameter in the Android Manifest needs to be set to true. For the WebView's PostBuildProcess script to be able to overwrite the Manifest, your Android Build System needs to be set to Gradle (not to Internal). You can set the Android Build System in the Build Settings or the Android Publishing Settings.
If your game was built using the Internal Android Build System before, you may have to delete your project's Library folder to force an asset reimport.
Check your Android Manifest: You can use Apktool to unpack your APK after building and double check your Android Manifest. If hardwareAccelerated is set to false, we recommend closing your project, deleting your Library folder and making a new, clean Build using the Gradle Build System.
When Unity asks you if you want to upgrade the Android SDK to 34, accept this and download the SDK.
Known issues:
Android Studio error "Installed Build Tools revision 34.0.0 is corrupted"or Android Studio error "Installed Build Tools revision 34.0.0 is corrupted"
This error can be solved following the link: https://stackoverflow.com/a/68430992﻿
Force SDK 34 as target version if you previously hardcoded it
If for some reasons, you do not success in compiling to SDK 34 or in using the build tools version 34, you can edit Assets/Plugins/Android/launcherTemplate.gradle and Assets/Plugins/Android/mainTemplate.gradle and hardcode the values:
compileSdkVersion 34
buildToolsVersion '34.0.0'
Promo Graphics
Android TV Banner
In your Unity Player Settings, in the Icon tab of the Android export settings, check the'Enable Android Banner'checkbox and assign a cover art for your game. This will be the icon that users see when they download your game onto their Android TV.
Please use the TV banner graphic preset provided here to adorn your banner with the AirConsole logo.
Google Play visuals
Along with your APK, please provide the AirConsole team with the following promotional graphics:
High-Res Icon - Resolution: 512 x 512, format: 32-bit PNG (With transparency).
Feature Graphic - Resolution: 1024 x 500, format: JPG or 24-bit PNG (Without transparency).
TV Banner - Resolution: 1280 x 720, format: JPG or 24-bit PNG (no alpha).
Ingame Screenshots x3 - Resolution: 1920 x 1080, format: JPG or PNG.
Amazon Appstore visuals
Along with your APK, please provide the AirConsole team with the following promotional graphics:
App icon - Resolution: 1280 x 720, format: PNG (Without transparency).
Background image - Resolution: 1920 x 1080, format: JPG or PNG (Without transparency).
Promotional image - Resolution: 1024 x 500 (Landscape only), format: JPG or PNG.
Feature content background image - Resolution: 1920 x 720, format: JPG or PNG (Without transparency). Some content might be cut, or overlayed with icons, please have a look at the asset guidelines of Amazon: https://developer.amazon.com/docs/app-submission/asset-guidelines.html
Help needed?
If you are a developer and are experiencing issues with updating or implementing our SDK, please reach out to us at [email protected] for assistance. We are here to help and will do our best to resolve any issues you may be facing as quickly as possible.
Updated 27 Sep 2024
Did this page help you?
AirConsole Unity Plugin
Unity Custom Loading