Adding a framework

In this example we are going to add the Accelerate.framework to our project. Unity does not allow you to add additional built in frameworks to your build, but egoXproject makes it only a few clicks away.

Open the Xcode Project Editor

Press the “+” button in the Add Frameworks section

Select the Accelerate.framework from the Framework Browser

Build the project

If you place a custom framework or bundle in the Assets folder, Unity adds a host of meta files to their file structure. Instead place them outside of your Assets folder

Integrating iVersion (Adding source files, bundles, and enabling ARC)

In this example we shall be using the excellent iVersion by Nick Lockwood. This consists of 3 files: iVersion.h; iVersion.m; iVersion.bundle. iVersion requires ARC, but Unity iOS builds do not use ARC, so on every build you would either have to add in a build flag to enable ARC support on that file or not include iVersion until the final build. Both are undesirable options. Also, if you need multiple language support you need the bundle, which Unity also does not support. EgoXproject allows us to achieve and automate all of this.

First, place the files outside of the Assets folder. This will stop Unity adding meta files to the bundle, and causing them to be added to the shipping build! If you don’t need the bundle, you can place the source files in the Assets folder, just don’t put them in a Plugins/iOS folder. We don’t want Unity to automatically include them, as egoXproject will be managing the files instead.

Open the Xcode project editor.

Add the three files using the “+” button in the Add Files section.

Add in -fobjc-arc to the compile options of iVersion.m

In this case it does not matter whether they are linked or are copied into the project folder. Your choice.

Build.

If you place a custom framework or bundle in the Assets folder, Unity adds a host of meta files to their file structure. Instead place them outside of your Assets folder

Automatically including Debug or Release versions of libraries

If you are including an external native library or additional source files, you may want to build with a Debug version while developing and a Release version when distributing. With EgoXproject it is trivial to implement.

Open the Xcode Project Editor

Create a change file for the Debug changes

Add the debug files

Create a change file for the Release changes

Add the release files

Under the configuration section add two configurations, Debug, and Release. Only enable the debug change file in the Debug configuration and only enable the release change file in the Release configuration.

Making builds faster by disabling DSym generation

Prior to Unity 4.5 Unity sets up the Xcode project to generate a DSym (Debugging Symbols) file. This is not really very useful during most build iterations, and greatly slows down the build process. Turn it off by adding the DEBUG_INFORMATION_FORMAT build setting and setting its value to DWARF in the Xcode Project Editor. However, it is useful when distributing builds and getting symbolicated crash reports from services like Crashlytics. In this case set its value to DWARF with dSYM File.

Take advantage of egoXproject’s multiple configurations feature to have a Debug change file that disables DSym generation, and a Release change file that enables it. Create two configurations, one for Release and one for Debug. Enable only the appropriate changes file in each configuration.

Now all you need to do if select the desired configuration before you build.

Crashlytics is a great addition to any app. If and when your app crashes Crashlytics will notify you, and provide a detailed crash report allowing you to see where the app crashes. Crashlytics provide an app to add the Crashlytics framework to your app, but it does not cope well with projects that get auto-generated, like Unity projects. Instead set it up once using their installer to get all of the required values, and then use EgoXproject to make the required modifications on future builds.

Crashlytics is now part of Fabric, so this changes how you go about adding Crashlytics. If you are not using Fabric, and instead using the original Crashlytics app, then follow the first tutorial below. If you are using the Fabric based Crashlytics, follow the second tutorial.

Original Crashlytics without Fabric

If you have not used Crashlytics before, we suggest doing a manual integration first, and trying out their service. Here is a quick guide to doing this:

Create a Crashlytics account

Download and install their app

Build your Unity App

Use the Crashlytics menu bar app to add Crashlytics to your project. This involves adding a post build run script, dragging in the framework, and adding some code to the UnityAppController.mm file.

That’s great until you have to rebuild your iOS project, and lose all these manual changes. Instead lets automate this using egoXproject, and a little Objective-C coding.

Create a folder in your project folder, but not in your Assets folder. Otherwise Unity will add meta files throughout the framework.

Copy the Crashlytics framework from your iOS project to this new folder.

Enable DSym generation by adding the DEBUG_INFORMATION_FORMAT build setting and setting its value to DWARF with dSYM File.

Add the post build script from your iOS project to the scripts section

Build and run

The build script should look something like this:

./Crashlytics.framework/run API_KEY BUILD_SECRET

You can find your API_KEY and BUILD_SECRET under your organisation on the Crashlytics website.

The EgoCrashlytics class uses the Objective-C +load() function to allow us to automatically initialise Crashlytics without having to manually edit the Unity project or make calls from our C# code. You need to edit this file and replace API_KEY with your key.

A final detail is that Crashlytics requires the DSym file to be generated each build. This is slow, and quite often unwanted during development. Instead create a second configuration that does not set up Crashlytics, and instead disables the DSym generation. Use this configuration during development, and switch to the Crashlytics one for Ad Hoc and Release builds.

Enable DSym generation by adding the DEBUG_INFORMATION_FORMAT build setting and setting its value to DWARF with dSYM File.

Add the post build script from your iOS project to the scripts section

Now we need to modify the Info.plist. Open the Info.plist Editor

Create a new change file and call it Release

Add the following keys:

Dictionary with the key Fabric

Add a string to this dictionary with the key APIKey and the value of your API_KEY

Add an array to the dictionary with the key Kits

To the Kits array add a dictionary.

Add a new string entry to this dictionary with the key KitName and the value Crashlytics

Alternatively, see the screenshot below.

Build and run

The build script should look something like this:

./Fabric.framework/run API_KEY BUILD_SECRET

You can find your API_KEY and BUILD_SECRET under your organisation on the Fabric website.

The EgoFabric class uses the Objective-C +load() function to allow us to automatically initialise Crashlytics without having to manually edit the Unity project or make calls from our C# code.

A final detail is that Crashlytics requires the DSym file to be generated each build. This is slow, and quite often unwanted during development. Instead create a second configuration that does not set up Crashlytics, and instead disables the DSym generation. Use this configuration during development, and switch to the Crashlytics one for Ad Hoc and Release builds.

Info.plist change file for Fabric based Crashlytics and the resulting changes to the Info.plist