Unity Ionic Integration (with Vuforia support)

This plugin is NO LONGER MAINTAINED by the author. It has been ~3 years since I've last used Ionic or tested this integration. The repository isn't archived for the sole purpose of keeping the Issues active (it is a community effort, I don't necessarily provide support myself). Please note that Unity's official Unity as a Library method might be more stable than this integration, though I haven't tested it myself.

This tutorial will show you how to integrate your Unity app into an Ionic app and send messages between them (optional). It is tested on a medium-scale commercial Unity project with Vuforia plugin (optional).

Before we start, I'd like to give credits to these other guides that helped me overcome some challenges I've faced along the way:

https://docs.google.com/document/d/1V8eh5Gh2O0fNc4gOvqdpLOwO9VvRrR0dP8EN2YAcb88/edit
https://github.com/keyv/iOSUnityVuforiaGuide
https://bitbucket.org/jack_loverde/unity-5-vuforia-6-and-ios-native-integration/src/418c4923eeac?at=master
https://the-nerd.be/2014/08/07/call-methods-on-unity3d-straight-from-your-objective-c-code/

Also, a special thanks to all who contributed to the development of this plugin :)

Discord: https://discord.gg/UJJt549AaV

GitHub Sponsors ☕

System Requirements

Android: Android Studio
iOS: Xcode
Ionic: tested on ionic info:

Cordova CLI: 6.5.0 
Ionic Framework Version: 3.3.0
Ionic CLI Version: 2.2.1
Ionic App Lib Version: 2.2.0
Ionic App Scripts Version: 1.3.7
ios-deploy version: 1.9.1 
ios-sim version: 5.0.13 
OS: macOS Sierra
Node Version: v6.9.5
Xcode version: Xcode 8.3.3 Build version 8E3004b

For future versions of Ionic, you may have to use ionic cordova platform add instead of ionic platform add, ionic cordova plugin add instead of ionic plugin add and so on.

If you are using Unity 2017.3.0+ and Vuforia, check out this topic for possible issues that you may encounter during the integration process: https://github.com/yasirkula/UnityIonicIntegration/issues/16

If you are using VideoPlayer component and it stops working after integration, check out this topic: https://github.com/yasirkula/UnityIonicIntegration/issues/18

Ionic-side Setup

First things first, you should import the plugin into your Ionic app using the following command: ionic plugin add https://github.com/yasirkula/UnityIonicIntegration.git
Now, you can launch Unity from your Ionic app using the following code snippet (TypeScript):

import ...

// Should put declare before any @Component's
declare let unityARCaller: any;

@Component({
  ...
})

export class ...
{
	constructor() {
		...
	}
	
	openUnity() {
		// It is possible to send a string message to Unity-side (optional)
		unityARCaller.launchAR( "my message for Unity-side", this.uReturnedFromUnity, this.uMessageReceivedFromUnity );
	}
	
	sendMessageToUnity() {
		// Send a message to Unity while Unity is still running
		unityARCaller.sendMessage( "Function name", "Optional parameter" );
	}
	
	uReturnedFromUnity = (param) => {
		// param:String is the (optional) message returned from Unity-side
		alert( param );
	};
	
	uMessageReceivedFromUnity = (message) => {
		// message:String is the message received from Unity-side
		// If you call a UI-blocking function here like 'alert', subsequent messages from Unity
		// will be queued by the OS and will only be received after returning to Ionic and
		// unblocking the UI
		console.log( "=========" + message + "=========" );
	};
}

NOTE: to access the plugin from Javascript, use window.unityARCaller.

All you have to do is call launchAR( parameter, onReturnedToIonicCallback, onMessageReceivedCallback ) function whenever you want to show Unity content. Here, parameter is the optional String parameter that is passed to Unity right after it is launched (see Unity-side Setup). Upon returning to Ionic from Unity, onReturnedToIonicCallback is triggered with an (optional) String parameter param that is returned from the Unity-side
Unity and Ionic can keep communicating even while Unity view/activity is active. You can call a function on Unity-side from Ionic using the unityARCaller.sendMessage( "Function name", "Optional parameter" ); function and, if you want, send a message back to Ionic (see Unity-side Setup) that triggers onMessageReceivedCallback

NOTE: on Android platform, if device runs out of memory while running the Unity activity, the Ionic activity is stopped and then automatically restarted by Android OS upon returning to Ionic from Unity. In that case, unfortunately, onReturnedToIonicCallback can not be called.

Unity-side Setup

Import IonicComms.cs script (available in files directory of this git repo) into your project. You don't have to attach this script to any GameObject but feel free to do it if you want to assign some references to it through Inspector. Just be aware that there can only be a single living instance of IonicComms component at a time and if you want to attach it manually to a GameObject, you must do it in the first scene of your project
If you had passed a String message from Ionic to Unity in launchAR function, it will be available in the OnMessageReceivedFromIonic function in IonicComms.cs
You can call functions that you define inside IonicComms.cs from Ionic with unityARCaller.sendMessage function. Although the parameter passed to sendMessage is optional, your C# function must have the following signature: public void FunctionName( string message );
You can send messages from Unity to Ionic runtime using IonicComms.SendMessageToIonic( "my message" )
When you want to return to Ionic from Unity-side, just call IonicComms.FinishActivity() function (or, optionally, IonicComms.FinishActivity( "return value" ) to send back a return value)
SO, DO NOT USE Application.Quit() ANYMORE!
for Vuforia users: disable Auto Graphics API in Player Settings and remove everything but OpenGLES2
for Android: open Build Settings and set Build System to Gradle (New). Then, select the Export Project option and click Export button to export your Unity project as a Gradle project to an empty folder
for iOS: put uIonicComms.mm file found in files directory of this repo into Assets/Plugins/iOS folder of your Unity project (create the Plugins and iOS folders, if they do not exist)
for iOS: in Player Settings, set Scripting Backend to IL2CPP and then simply build your project to an empty folder

Android Steps

NOTE: see the following topic if your Unity Android project has any gradle dependencies and the Android Studio steps below yield a Failed to resolve: error: https://github.com/yasirkula/UnityIonicIntegration/issues/21

Build your Ionic project using ionic build android (use ionic platform add android, if Android platform is not added yet)
Open platforms/android folder inside your Ionic project's path with Android Studio
Open settings.gradle and insert the following lines (don't forget to change the path in the second line!):

include ':UnityProject'
project(':UnityProject').projectDir = new File('C:\\absolute path\\to your\\unity export folder')

Open build.gradle of android module and insert the following line into dependencies, where all the other compile command(s) are located at:

compile project(':UnityProject')

Click Sync now (top-right) and wait until Android Studio yields an error
In build.gradle of UnityProject module, change apply plugin: 'com.android.application' to apply plugin: 'com.android.library'
Inside jniLibs folder of android module, delete unity-classes.jar, if exists
Click Sync now again and wait for another error
If you receive the message "Error: Library projects cannot set applicationId..." inside build.gradle of UnityProject module, delete the line applicationId 'com.your_unity_bundle_identifier' and click Sync now again
Inside manifests folder of android module, open AndroidManifest.xml and switch to Merged Manifest tab
Click on the "Suggestion: add 'tools:replace="android:icon"' to <application> element at AndroidManifest.xml to override" text
Open AndroidManifest.xml of UnityProject module and switch to Text tab
Remove the <activity>...</activity> with the following intent:

<intent-filter>
	<action android:name="android.intent.action.MAIN" />
	<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>

Now you can Run the android module

If you receive a "Could not find method compile()" error, see: https://github.com/yasirkula/UnityIonicIntegration/issues/52

NOTE: if you are able to build your Ionic project successfully the first time but not the second time, remove the Android platform using ionic platform remove android and add it again using ionic platform add android.

About 64-bit ARM, x86 and x64 Android Devices

As of now, Unity has a native library for 32-bit ARM and x86 architectures only. However, Unity applications do run on 64-bit ARM and x64 architectures as 64-bit ARM architecture natively supports 32-bit ARM applications and x64 architecture natively support x86 applications. This is valid as long as there are no 64-bit ARM or x64 plugins in your project and all your plugins have both 32-bit ARM and x86 libraries. Otherwise, you will receive a "Failure to initialize! Your hardware does not support this application, sorry!" error while launching Unity content. To avo

UnityIonicIntegration

Install / Use

README