search

yasirkula / UnityIonicIntegration

A guide to integrating Unity 3D content into an Ionic app and sending messages between them (for Android & iOS)(tested with Vuforia plugin)
104 stars 32 forks source link
ar cordova cordova-plugin integration ionic plugin unity vuforia

readme

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:

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

Discord: https://discord.gg/UJJt549AaV

GitHub Sponsors ☕

System Requirements

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

// 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](#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](#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')


![](images/android1.png?raw=true "")

- 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:
```xml
<intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
</intent-filter>

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 avoid this issue, you must ensure the following criteria:

If you want consistency for your app, go with the second option.

Troubleshooting

See: https://github.com/yasirkula/UnityIonicIntegration/issues/61

Disable Strip Engine Code in Player Settings (source).

iOS Steps

IMPORTANT NOTICE: make sure that the paths to your Ionic project and Unity build directory do not contain any space characters.

NOTE: if you encounter an error like "cordova/cdvviewcontroller.h' file not found" while building, try adding "$(OBJROOT)/UninstalledProducts/$(PLATFORM_NAME)/include" to Header Search Paths in Build Settings (do this for PROJECT and the TARGETS)