Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Integrating Unity into Android applications

Integrate the Unity Runtime Library into Android applications.
Read time 3 minutesLast updated 10 days ago
Integrate the Unity Runtime Library into Android applications using the Unity as a Library feature.
You can use this feature to include Unity-powered features, such as 3D/2D Real-Time Rendering, AR Experience, 3D model interaction, or 2D mini-games, into your application. The Unity Runtime Library exposes controls to manage the Unity runtime lifecycle within the application.
Important
The introduction of Unity as a Library in your project might require you to adapt native and managed plug-ins to work properly for Android. Plug-ins that make changes to Gradle manifests need to use the Gradle changes outlined in Using Unity as a library in native iOS/Android apps.

How it works

You don't need to do anything different when you build your Gradle project from Unity.

Android Gradle project structure

Every Android Gradle project that Unity generates has the following structure:
  • A library part in the unityLibrary module that you can integrate into any other Gradle project. This contains the Unity runtime and Player data.
  • A thin launcher part in the launcher module that contains the application name and its icons. This is a simple Android application that launches Unity. You can replace this module with your own application.

Integrate the unityLibrary module

To integrate Unity into another Android Gradle project, you must include the unityLibrary module of the generated Android Gradle project in your Android Unity project through the 
settings.gradle
file.
This repository contains example Projects and plug-ins that demonstrate how to integrate Unity into an Android app, along with further documentation.

Control the Player with Java APIs

To control a Player, relay an 
Intent
to launch the Unity activity and extend it if needed. For more information, refer to Android developer documentation on Intents and Intent Filters. You can also use the 
UnityPlayerForActivityOrService
or 
UnityPlayerForGameActivity
Java API, depending on the application entry point you have selected.
UnityPlayerForActivityOrService
is the main class for hosting the Unity runtime in your Android application. It extends the abstract 
UnityPlayer
base class and provides the concrete implementation for Activity-based or Service-based Unity integration.
UnityPlayerForGameActivity
is an alternative to 
UnityPlayerForActivityOrService
for applications that use Google's 
GameActivity
. It extends the abstract 
UnityPlayer
base class and works with the 
GameActivity
threading model. The corresponding entry point activity is 
UnityPlayerGameActivity
, which extends 
GameActivity
.

Unity Player lifecycle events

IUnityPlayerLifecycleEvents
provides a way to interact with three important lifecycle events of the Unity Player:
  • Load - The Unity runtime invokes 
    IUnityPlayerLifecycleEvents.onUnityPlayerLoaded
    when the Unity Player finishes initialization. This is a default method that does nothing unless you override it.
  • Unload - The Unity runtime invokes 
    IUnityPlayerLifecycleEvents.onUnityPlayerUnloaded
    when 
    Application.Unload
    , 
    UnityPlayerForActivityOrService.unload()
    , or 
    UnityPlayerForGameActivity.unload()
    unloads the Unity Player. This puts the Unity Player in a paused state where it unloads all Scenes, but keeps everything else loaded in the memory.
  • Quit - The Unity runtime invokes 
    IUnityPlayerLifecycleEvents.onUnityPlayerQuitted
    when the Unity Player quits. The process that was running Unity ends after this call.
You can pass an instance of 
IUnityPlayerLifecycleEvents
to the 
UnityPlayerForActivityOrService
or 
UnityPlayerForGameActivity
constructor. You can also override its methods in subclasses of 
UnityPlayerActivity
or 
UnityPlayerGameActivity
.

Limitations

Unity doesn't control the runtime lifecycle, so Unity as a Library might not work for all possible use cases. Known limitations include:
  • Unity as a Library only supports full-screen rendering. However, if you are a Unity Industry customer, the limitations and features might differ.
  • You can't load or integrate more than one instance of the Unity runtime.
  • You might need to adapt third-party plug-ins (both native and managed) to work with the Unity runtime.
  • Unity as a Library isn't compatible with the Xamarin app platform.
  • You can't integrate Unity Runtime Library as a dynamic module with Play Feature Delivery.

Additional resources