README.md

compas_xr_unity

COMPAS XR: Visualizer app for collaborative robotic assembly

Firebase Installations Quickstart

Requirements

1. Download and install Unity Hub and Unity 2023.3.10f1
2. Android Build Support (OpenJDK & Android SDK & NDK Tools)(when developing for Android) and iOS Build Support (if developing for iOS) - have to be ticked in the installation modules when installing Unity.

Alternatively, they can also be added post-installation from "Add Modules".

Firebase

Register your Android/iOS app with Firebase.

1. Create a Firebase account (https://console.firebase.google.com)

2. Create a new project in the Firebase console

3. Associate your project to a Unity app by clicking the Unity icon.

• Here you can add both an Android and an iOS app to your project.
• If you are using the Compas XR app that is already built and don't plan on making changes in Unity, use the following bundle identifier: ```com.ETHZ.cdf``
• If you are rebuilding the app in Unity, make sure that your bundle identifier is unique (a strict requirement for iOS app development). Maintain the same format: com.xxxx.yyyy

4. Download the google-services.json file associated with your Firebase project for Android and GoogleService-Info.plist for iOS. These files contain the information that you need to connect your app to the Firebase backend, and will need to be included either in the FirebaseInitialize script in the Unity project or at the start of the app, before initializing Firebase. You will need to look for the following parameters: app id, api key, database url, storage bucket, and project id.

• An example of these configurations is shown below:

// Your web app's Firebase configuration
// For Firebase JS SDK v7.20.0 and later, measurementId is optional
const firebaseConfig = {
  apiKey: "AIzaSyAO_YVROUIc866BqgWgcBpPxUe6SVG5O9g",
  authDomain: "cdf-project-f570f.firebaseapp.com",
  databaseURL: "https://cdf-project-f570f-default-rtdb.europe-west1.firebasedatabase.app",
  projectId: "cdf-project-f570f",
  storageBucket: "cdf-project-f570f.appspot.com",
  messagingSenderId: "641027065982",
  appId: "1:641027065982:web:20ca92f0a2326bc3dab02f",
  measurementId: "G-RZ5BVHNGK8"
};

5. Accessing Firebase config information afterwards

• In your Firebase console, navigate to Project Overview and click the gear icon.
• In the drop-down window select Project Settings
• In the Project Settings window under Your apps
• The required config information is listed under the section SDK setup and configuration - google-services.json for Android, respectively GoogleService-Info.plist for iOS

6. In the Project Overview, under All products click to add the following: Authentication, Realtime Database and Storage.

7. Create a Database

• In Project Overview, under Project shortcuts, click on Realtime Database
• Click on Create Database
• Set the Databse location according to your needs and Start in locked mode

8. Change the rules in Realtime Database to allow writing.

• In Project Shortcuts, under Realtime Database, click on Rules and change false to true and Publish

{
  "rules": {
    ".read": true,
    ".write": true
  }
}

*The following steps are specific to Android development if building from Unity:

9. Android apps must be signed by a SHA1 key, and the key's signature must be registered to your project in the Firebase Console. To generate a SHA1, first you will need to set the keystore in the Unity project.

• Go to Publishing Settings under Player Settings in the Unity editor.
• Select an existing keystore, or create a new keystore using the toggle.
• Select an existing key, or create a new key using Create a new key.
• Build an apk to be able to generate the SHA1 key (see below under Unity and Android build how to build)

10. Generate the SHA1 key and copy it into your Firebase project. - After setting the keystore and key, as well as building the app once, you can generate a SHA1 by running this command in CMD (admin):

```
keytool -list -v -keystore <path_to_keystore> -alias <key_name>
```

• Copy the SHA1 digest string into your clipboard.
• Navigate to your Android App in your Firebase console.
• From the main console view, click on your Android App at the top, and open the settings page.
• Scroll down to your apps at the bottom of the page and click on Add Fingerprint.
• Paste the SHA1 digest of your key into the form. The SHA1 box will illuminate if the string is valid. If it's not valid, check that you have copied the entire SHA1 digest string.

Unity

1. Open Unity Hub. In Projects, click on Open(MacOS) or ADD(Windows). Locate the folder you downloaded from GitHub compas_xr_unity on the drive and add it.

2. Open the Unity Project.

3. Update the Project Settings

• Select the File > Build Settings menu option.

• Select Android or iOS in the Platform list and click Switch Platform to set the target platform.

• Wait for the spinner (compiling) icon to stop in the bottom right corner of the Unity status bar.

• Select the active platform and click Player Settings.

• In the Player Settings panel adjust the following settings accordingly for Android, respectively iOS

  Unity - Android

  • In Player Settings, under the Android panel: scroll down to Identification / Override Default Package Name/ and update Package Name to the value of the Bundle Identifier you provided when you registered your app with Firebase.
  • In File > Build Settings, click Build and Run to build the project on an Android device. * In case the device is not a developer device, scroll at the bottom to the Turning Devices into Developer Devices section. Alternatively, one can just Build to obtain the apk and distribute it to Android devices.
  • If an error occurs, check player settings against default player settings depicted below:

Unity - iOS

• Once the target platform has been switched to iOS, Unity will try to install CocoaPods, an iOS resolver.

• Most likely it will fail and you will need to do the following fixes:

in Xcode:

• Make sure you have Xcode and the Developer Tools installed on your MacBook. If you don't, go to your MacBook's AppStore and install Xcode.
• Sign in with your Apple ID.

• Connect your iOS device to the laptop via a USB cable and unless your device is already in Developer Mode, scroll down and see the instructions for Turning Devices into Developer Devices.
• Install necessary modules in Xcode (e.g. iOS 17.2)

in Terminal:

• Set the export path for gems as follows: export PATH="/Users/username/.gem/ruby/2.6.0/bin:$PATH"
• Install gem active support: gem install activesupport -v 6.1.7.6 --user-install

back in Unity:

• Under Assets > External Dependency Manager > iOS resolver > Install CocoaPods
• Under Assets > External Dependency Manager > iOS resolver > Settings check that you have matching settings with the ones below:

in the Player Settings, under the iOS panel:

• Scroll down to Identification / Override Default Package Name/ and update Package Name to the value of the Bundle Identifier you provided when you registered your app with Firebase.
• Scroll down to Camera Usage Description and write a message describing the need to use the camera, such as "please allow camera use for AR".
• Scroll down to iOS version and pick the adequate version (min. 14 to support current project packages).
• If an error occurs, during a build, check player settings against default player settings depicted below:

Note - it is possible to build for iOS from a Windows computer, but the resulting folder needs to go through a MacBook with Xcode in order to be installed or distributed on an iOS device.

• Ideally one would Build or Build and Run the project from a MacBook that has Xcode installed.
• In File > Build Settings click on Build and select a folder location on your drive for the build. Ideally you should create a folder called Builds and within it, individual files for each build.

4. In Finder:

• Open the Builds folder and find the file with the last build on your computer, eg. 01
• Select the BuildName".xcworkspace file and open it with Xcode. Make sure you open the .xcworkspace and not the.xcodeproj

5. In Xcode:

• In Xcode click the file's name on the left column to open the Settings
• Under Signing and Capabilities > All, tick Automatically manage signing and confirm Enable Automatic

• Under Team, open the drop-down down and select the development team/individual.
• Optional: this is the last chance to adjust the Bundle Identifier and App Name before installing.
• At the top, make sure the iOS device is connected and click the play triangle to start building and installing on device.

• The first time you build with Xcode, it will ask for the MacBook's password for codesign. Click on Always Allow as many times as the pop up appears.

• You will be asked to unlock the device and the app will install and open automatically.

Turning Devices into Developer Devices

Android:

• Go to "Settings".
• Tap "About device" or "About phone".
• Tap “Software information”
• Tap “Build number” seven times.
• Enter your pattern, PIN or password to enable the Developer options menu.

iOS

• Connect your device to your MacBook via a USB cable.
• Open Xcode.
• On your device, go to the Settings app, and navigate to Privacy & Security > Developer Mode.
• Enable the toggle.
• You will receive a prompt from iOS to restart your device.
• Press Restart.
• Once again, go to the Settings app, and navigate to Privacy & Security > Developer Mode and check that the toggle is on.