These examples are for egoXproject 1.x. For egoXproject 2.x examples go here.

Modifying the Info.plist

There are many additional things you may need to add to an Info.plist. Here are a few examples. Open the Info.plist Editor and add a change file if needed.

  1. Enable iTunes File Sharing by adding the following key, type and value

UIFileSharingEnabled, Boolean type, Yes

  1. Add additional capability restrictions

UIRequiredDeviceCapabilities, Array Type
Add the following values to the array:

    • video-camera
    • accelerometer
    • gyroscope
    • opengles-2
  1. Add your app’s Facebook app ID

FacebookAppID, String type, ID Number

Changes to make to the Info.plist

Changes to make to the Info.plist

Modified Info.plist file

Modified Info.plist file

Back to top

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.

  1. Open the Xcode Project Editor
  2. Press the “+” button in the Add Frameworks section
  3. Select the Accelerate.framework from the Framework Browser
  4. 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
Add the Accelerate framework

Add the Accelerate framework

Accelerate Framework added to Xcode

Accelerate Framework added to Xcode

Back to top

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.

  1. Open the Xcode project editor.
  2. Add the three files using the “+” button in the Add Files section.
  3. Add in -fobjc-arc to the compile options of iVersion.m
  4. In this case it does not matter whether they are linked or are copied into the project folder. Your choice.
  5. 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
Changes to add iVersion to Xcode

Changes to add iVersion to Xcode

iVersion automatically added to Xcode

iVersion automatically added to Xcode

Back to top

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.

  1. Open the Xcode Project Editor
  2. Create a change file for the Debug changes
  3. Add the debug files
  4. Create a change file for the Release changes
  5. Add the release files
  6. 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.
  7. Select the configuration required for the current build
  8. Build.
Change file for adding the debug version of a library

Change file for adding the debug version of a library

Debug version of library added to Xcode

Debug version of library added to Xcode

Change file for adding the release version of a library

Change file for adding the release version of a library

Release version of library added to Xcode

Release version of library added to Xcode

Back to top

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.

Make iOS builds build faster

Make iOS builds build faster

Debug Information Format set to DWARF for faster builds

Debug Information Format set to DWARF for faster builds

Back to top

Integrating Crashlytics (Adding build scripts, source files and third party frameworks)

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:

  1. Create a Crashlytics account
  2. Download and install their app
  3. Build your Unity App
  4. 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.

  1. Create a folder in your project folder, but not in your Assets folder. Otherwise Unity will add meta files throughout the framework.
  2. Copy the Crashlytics framework from your iOS project to this new folder.
  3. Download these two files, EgoCrashlytics.h and EgoCrashlytics.m, and place them in the folder with Crashlytics.framework.
  4. Edit the EgoCrashlytics.h file and add in your API_KEY.
  5. In Unity, open the Xcode Project Editor.
  6. Create a new change file, and call it Release.
  7. Add the Crashlytics framework and set its add method to Copy.
  8. Add the EgoCrashlytics.h file.
  9. Add the EgoCrashlytics.m file.
  10. Enable DSym generation by adding the DEBUG_INFORMATION_FORMAT build setting and setting its value to DWARF with dSYM File.
  11. Add the post build script from your iOS project to the scripts section
  12. 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.

Changes required to add Crashlytics to Xcode

Changes required to add Crashlytics to Xcode

Crashlytics automatically added to Xcode

Crashlytics automatically added to Xcode

Back to top

Fabric Crashlytics

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

  1. Create a Fabric account
  2. Download and install their app
  3. Build your Unity App
  4. Use the Fabric menu bar app to add Crashlytics to your project. This involves adding a post build run script, dragging in the frameworks, 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.

  1. Create a folder in your project folder, but not in your Assets folder. Otherwise Unity will add meta files throughout the framework.
  2. Copy the Crashlytics and Fabric frameworks from your iOS project to this new folder.
  3. Download these two files, EgoFabric.h and EgoFabric.m, and place them in the folder with Crashlytics and Fabric frameworks.
  4. In Unity, open the Xcode Project Editor.
  5. Create a new change file, and call it Release.
  6. Add the Crashlytics framework and set its add method to Copy.
  7. Add the Fabric framework and set its add method to Copy.
  8. Add the EgoFabric.h file.
  9. Add the EgoFabric.m file.
  10. Enable DSym generation by adding the DEBUG_INFORMATION_FORMAT build setting and setting its value to DWARF with dSYM File.
  11. Add the post build script from your iOS project to the scripts section
  12. Now we need to modify the Info.plist. Open the Info.plist Editor
  13. Create a new change file and call it Release
  14. Add the following keys:
    1. Dictionary with the key Fabric
    2. Add a string to this dictionary with the key APIKey and the value of your API_KEY
    3. Add an array to the dictionary with the key Kits
    4. To the Kits array add a dictionary.
    5. Add a new string entry to this dictionary with the key KitName and the value Crashlytics
    6. Alternatively, see the screenshot below.
  15. 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

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

Xcode project change file for Fabric based Crashlytics

Xcode project change file for Fabric based Crashlytics

Resulting Xcode Project Changes

Resulting Xcode Project Changes

Back to top

Performing command line builds (Pro Only)

Using egoXproject will require either no changes or very small changes to your build script if you require build time configuration.

  • If you only have a single configuration you do not need to do anything. EgoXproject will automatically apply your specified changes during the build
  • If you have multiple configurations you can set the active configuration ahead of time using the UI.
  • Or if you need to set the configuration at build time based on build parameters you can do this too.
Command line builds can only be done using Unity Pro

To set the active configuration during the command line build you need to add the following lines to your build configuration script.

To set the active Info.plist configuration add this line, and replace CONFIGURATION_NAME with the name of the configuration.

Egomotion.EgoXproject.InfoPlistConfiguration.ActiveConfiguration = CONFIGURATION_NAME;

To set the active Xcode project configuration add this line, and replace CONFIGURATION_NAME with the name of the configuration.

Egomotion.EgoXproject.XcodeProjectConfiguration.ActiveConfiguration = CONFIGURATION_NAME;

The following C# script shows an example of a command line build script.

using UnityEngine;
using UnityEditor;
using Egomotion.EgoXproject;

public static class EgoBuild
{
	public static void BuildAll()
	{
		DebugBuild();
		ReleaseBuild();
	}

	public static void DebugBuild()
	{
		CreateBuildsDir();

		EditorUserBuildSettings.SwitchActiveBuildTarget(BuildTarget.iPhone);

		InfoPlistConfiguration.ActiveConfiguration = "Debug";

		XcodeProjectConfiguration.ActiveConfiguration = "Debug";

		BuildPipeline.BuildPlayer(GetScenePaths(),
		                          "Builds/iOS-Debug",
		                          BuildTarget.iPhone,
		                          BuildOptions.None);
	}

	public static void ReleaseBuild()
	{
		CreateBuildsDir();

		EditorUserBuildSettings.SwitchActiveBuildTarget(BuildTarget.iPhone);

		InfoPlistConfiguration.ActiveConfiguration = "Release";

		XcodeProjectConfiguration.ActiveConfiguration = "Release";

		BuildPipeline.BuildPlayer(GetScenePaths(),
		                          "Builds/iOS-Release",
		                          BuildTarget.iPhone,
		                          BuildOptions.None);
	}

	static void CreateBuildsDir()
	{
		if (!System.IO.Directory.Exists("Builds")) {
			System.IO.Directory.CreateDirectory("Builds");
		}
	}

	static string[] GetScenePaths()
	{
		string[] scenes = new string[EditorBuildSettings.scenes.Length];

		for(int i = 0; i < scenes.Length; i++)
		{
			scenes[i] = EditorBuildSettings.scenes[i].path;
		}

		return scenes;
	}
}

The command line build is then performed with the following command

/Applications/Unity/Unity.app/Contents/MacOS/Unity -batchmode -executeMethod EgoBuild.BuildAll -quit

This builds two projects, one in Builds/iOS-Debug and one in Builds/iOS-Release.

Back to top

Performing Jenkins builds (Pro Only)

This requires no special changes to your build flow.

  1. Select the desired egoXproject configuration if you have more than one.
  2. Make sure your project is checked in with this selected configuration.
  3. Set up the project to build using Jenkins.
  4. Build.

If you require build time configuration, see the Performing command line builds tutorial for an example of how to do this.

Jenkins builds can only be done using Unity Pro

Back to top

Performing Unity Cloud Build builds

This requires no special changes to your build flow.

  1. Select the desired egoXproject configuration if you have more than one.
  2. Make sure your project is checked in with this selected configuration.
  3. Set up the project to build in Unity Cloud Build.
  4. Build.

If you require build time configuration, see the Performing command line builds tutorial for an example of how to do this.

Back to top