Building for Mobile
Tutorial
Beginner
30 Mins
Overview
Overview
Summary
This tutorial describes how to build a Unity project to an iOS or Android device for testing.
Topics we'll cover
Language
English
Recommended Unity Versions
5.3
Tutorial
Building for Mobile
1.
Building your Unity game to an iOS device for testing
This tutorial was last tested on 18 May 2016, using Unity 5.3.4 and Xcode 7.3

Introduction

In this lesson, we’re going to build a sample Unity project to an iOS device for testing.
This lesson doesn’t cover building a game for distribution to other devices, or submitting a game to the App Store.
Since the release of Xcode 7 in 2015, it has been possible to build apps - including games made with Unity - using a free Apple ID. Prior to this, only members of the paid Apple Developer Program could do so. The free option is limited: you can’t use services such as Game Center or In-App Purchases, and you can’t submit your game to the App Store. However, you can test your game on an iOS device using a free Apple ID.
This lesson assumes that you will be using a free Apple ID and are not enrolled in the Apple Developer Program. If you’re enrolled in the Apple Developer Program, you can still follow this lesson - however, you will probably wish to use the Apple Developer Portal to configure your certificates, provisioning profiles and devices rather than allowing Xcode to do it automatically, as we will do in this lesson.

What you will need

To follow this lesson, you will need:
  • A Mac computer running running OS X 10.11 or later
  • The latest version of Xcode (available from the Mac App Store)
  • The latest version of Unity (available here)
  • An iOS device
  • The Simple Mobile Placeholder project (available from the Asset Store)

Setting up the Simple Mobile Placeholder project

First, let’s take a quick look at the Simple Mobile Placeholder project. As the name suggests, this is an intentionally minimal project - it was created simply to test the build process. As such, it’s very easy to test that it has built correctly and that it runs as expected on your device.
  • Open Unity and create a new project.
  • Name the project "SimpleMobilePlaceholder".
  • Choose a location to save it to.
  • Ensure that "3D" is selected to use the Unity Editor in 3D mode.
  • Click the Create project button to create the project.
 
  • Using the top menu, go to Window > Asset Store.
  • Search for "Simple Mobile Placeholder".
  • Download and import this project by navigating to the project page and clicking Download then Import.
  • You will see a warning that importing a complete project will overwrite your project settings. This is fine, as we have just created a blank project. Click Import to continue.
 
An import window will appear, showing which files are included in the project.
  • Click Import to import the project.
  • In the Project window, navigate to Scenes and then double click the Main scene to open it.
You should now see a red cube in the Scene View. Enter Play Mode to test the project. The cube should spin. When you click the cube, it should spin in the opposite direction and a message will appear in the Console window.
 
That’s it! Now that we know how the project works, let’s get ready to build it to a device.

Adding your Apple ID to Xcode

Before we can build to a device, we need to set up an Apple ID and add it to Xcode.
If you don’t yet have an Apple ID, obtain one from the Apple ID site.
Once you have obtained an Apple ID, you must add it to Xcode.
  • Open Xcode.
  • From the menu bar at the top of the screen choose Xcode > Preferences. This will open the Preferences window.
  • Choose Accounts at the top of the window to display information about the Apple IDs that have been added to Xcode.
  • To add your Apple ID, click the plus sign at the bottom left corner and choose Add Apple ID.
 
  • A popup will appear, requesting your Apple ID and password. Enter these.
  • Your Apple ID will then appear in the list. Select your Apple ID to see more information about it.
  • Under the heading Team, you will see a list of all Apple Developer Program teams that you are a part of. If you’re using a free Apple ID that isn’t enrolled in the Apple Developer Program, you will see your name followed by "(Personal Team)".
 
In the Apple Developer Program, teams are how you organise who has access to a project, what permissions they have and so on. When you use a free Apple ID, Apple creates what is known as a Personal Team for your Apple ID that only has you on it. Don’t worry about it for now - it’s just one of the steps needed to test your app.
More information on managing accounts and teams in Xcode can be found in this Apple documentation.

Preparing your Unity project for building to iOS

We now need to return to Unity and switch platforms so that we can build our game for iOS.
  • Within Unity, open the Build Settings from the top menu (File > Build Settings).
  • Highlight iOS from the list of platforms on the left and choose Switch Platform at the bottom of the window.
 
Switching platforms sets the build target of our current project to iOS. This means that when we build, Unity will create an Xcode project. Switching platforms also forces Unity to reimport all assets in the project. This doesn’t take long on a small project like this, but be aware that on a larger project this may take some time.
Next, we need to enter the bundle identifier for our game. A bundle identifier is a string that identifies an app. It’s written in what is known as reverse-DNS style, following the format com.yourCompanyName.yourGameName. Allowed characters are alphanumeric characters, periods and hyphens. We need to change the bundle identifier from the default setting in order to build.
It is important to note that at the time of writing, once you have registered a bundle identifier to a Personal Team in Xcode the same bundle identifier cannot be registered to another Apple Developer Program team in the future. This means that while you are testing your game using a free Apple ID and a Personal Team, you should choose a bundle identifier that is for testing only - you won’t be able to use the same bundle identifier to release the game. An easy way to do this is to add "Test" to the end of whatever bundle identifier you were going to use - for example, com.yourCompanyName.yourGameNameTest.
There are other restrictions on bundle identifiers. When you release an app, its bundle identifier must be unique to your app, and cannot be changed after your app has been submitted to the App Store. For more information on bundle identifiers on iOS, see this Apple documentation.
  • Open the Player Settings in the Inspector panel (Edit > Project Settings > Player).
  • Expand the section at the bottom called Other Settings, and enter your chosen bundle identifier where it says Bundle identifier.
 
Now we’re ready to build!

Building an Xcode project using Unity

Building your game to an iOS device involves two steps. First, Unity builds an Xcode project. Then, Xcode builds that project to your device. Once you’ve set everything up, Unity can trigger both of these steps for you - however, the first time you build a project to your device involves a little extra work and you must do both steps separately.
The reason for the extra work is security. Apple uses a technique called code signing to ensure that apps come from known sources and haven’t been tampered with, and this needs to be set up before you can build. For more information on code signing, see this Apple documentation.
First, we’re going to get Unity to build the Xcode project.
  • Open the Build Settings from the top menu (File > Build Settings).
  • Click Add Open Scenes to add the Main scene to the list of scenes that will be built.
  • Click Build to build.
 
You will be prompted to choose where to build your Xcode project. A good place to do this is in a dedicated builds folder within your project folder. We’ll make one now.
  • Click the down arrow in the top right of the prompt to expand it, and then click New Folder.
  • When prompted to choose a name, enter "Builds" and click Create. This will create a new folder called “Builds” in the root directory for your project.
  • In the text input field marked Save As, enter "iOS" and click Save.
 
Unity will now create an Xcode project called "iOS" in the “Builds” folder.
An Xcode project is all the files and information required to build an app using Xcode, organised into folders containing code, image assets and so on. For more information on the Xcode project that Unity creates, see the Unity Manual Xcode Project Structure page.

Building the sample project to your device using Xcode

Once Unity has built the Xcode project, a Finder window will open at the project’s location.
  • Double click the .xcodeproj file to open the project with Xcode.
  • In the top left, select Unity-iPhone to view the project settings. It will open with the General tab selected.
  • Under the topmost section called Identity, you may see a warning and a button that says Fix Issue. This warning doesn’t mean we’ve done anything wrong - it just means that Xcode needs to download or create some files for code signing.
  • Click the Fix Issue button.
 
  • A popup will appear, showing details of any teams that have been added to Xcode.
  • Make sure that the correct team is shown in the dropdown - if you’re using a free Apple ID, it should be your name followed by "(Personal Team)".
  • Click Choose to instruct Xcode to download any required certificates and generate a provisioning profile. The warning will then disappear.
 
Certificates and provisioning profiles the files required for code signing. You don’t need to worry about what they do at the moment - but if you’d like to know more about them, see this Apple documentation.
Now connect your device to your computer using a USB cable. If it’s the first time you’ve connected this device, you may see a message that says that Xcode is "processing symbol files" - this means that Xcode is getting information from the device that will allow you debug apps on this device. Wait for this to complete. Once it has finished processing the symbol files, the message will disappear and your device will be ready to use.
The final step before we build to the device is to make sure that the device is unlocked, because Xcode can’t launch apps on a device that is locked with a passcode. If your device is set to lock with a passcode, it’s best to change this setting before you build to your device and then change it back after you have finished testing.
  • On your device, go to Settings > Display & Brightness > Auto-Lock.
  • To disable locking, select Never.
It is worth noting that when in Low Power Mode, the Auto-Lock settings cannot be changed until Low Power Mode is turned off.
  • To turn off Low Power Mode, go to Settings > Battery > Low Power Mode and set this to "Off".
Now it’s time to build to your device.
  • In the top left of the Xcode interface, click Run (the "play" button).
 
If you haven’t used your Mac to develop for iOS or OSX before, you may see a popup at this point asking if you would like to enable Developer Mode. Enabling Developer Mode will mean that you won’t be prompted for your password when carrying out common development tasks.
  • Enable Developer Mode by choosing Enable, and enter your password when prompted.
 
After a moment, you’ll see a message in the bar at the top centre of Xcode that says "Build succeeded", and the app will load on your device. We’re almost done!
You may receive a warning prompt on the device with the title "Untrusted Developer", or a popup in Xcode that says “Could not launch [your app name]”. If you see either of these, it means the that there’s one last step left: you need to set your device to trust your Apple ID.
  • On your device, go to Settings > General > Device Management > Developer App > [your app name].
  • Choose your Apple ID, and then choose Trust.
As long as you have at least one app built using that Apple ID on your device, your device will allow content built with that Apple ID to run. If you ever remove all of the apps built with that Apple ID from your device, you’ll need to go back to this setting and choose to trust it again.

Testing the game on your iOS device

The game has now been built to your device. If you disconnect your phone from your computer, the game will still be there. To play the game on your device, tap its icon on the home screen - the same way you would launch any app on the device.
Our game works! The cube spins, and tapping it causes it to change direction.
Simply playing your game on a device is one way of testing it. It’s a good way of checking things like whether the controls work. However, if you want more information - if you’d like to see Unity’s logs while you play, for example - you’ll need to build and run the app while the device is still connected to Xcode.
Let’s do this now.
  • Connect your device to your computer.
  • Open the Xcode project by double clicking the .xcodeproj icon, as before.
  • In Xcode, choose Run (the "play" button).
Xcode will now build the game to your device and begin a debugging session.
 
If you look to the bottom right of Xcode while your game is running, you’ll see the Xcode debug console. This contains all of the information that you’d see in the Unity console, along with debug information about other things that are happening in the OS. You can use this in the same way that you use the console within Unity, to help you debug your game.
 
Try tapping the cube and looking at the debug console. You will see the same log message as you would see in Unity, along with some additional information.
Using the console to get information is just one of the ways that Xcode can help you test, profile and debug your game. It’s a complex subject and we won’t cover all of the options here, but this post on the Unity blog about profiling is a great start.

Conclusion

In this lesson, we learned how to build a Unity game to an iOS device for testing. We learned how to switch build targets in Unity, what a bundle identifier is, how to use Xcode to build your Unity game to your device for testing, and how to debug your Unity game on your iOS device using the console in Xcode.

2.
Building your Unity game to an Android device for testing

Introduction

In this lesson, we’re going to build a sample Unity project to an Android device for testing.
This lesson doesn’t cover building a game for distribution to other devices, or submitting a game to the Google Play Store.

What you will need

To follow this lesson, you will need:
  • The latest version of Unity (available here)
  • An Android device running the latest version of Android
  • The Simple Mobile Placeholder project (available from the Asset Store)

Setting up the Simple Mobile Placeholder project

First, let’s take a quick look at the Simple Mobile Placeholder project. As the name suggests, this is an intentionally minimal project - it was created simply to test the build process. As such, it’s very easy to test that it has built correctly and that it runs as expected on your device.
  • Open Unity and create a new project.
  • Name the project "SimpleMobilePlaceholder".
  • Choose a location to save it to.
  • Ensure that "3D" is selected to use the Unity Editor in 3D mode.
  • Click the Create project button to create the project.
 
  • Using the top menu, go to Window > Asset Store.
  • Search for "Simple Mobile Placeholder".
  • Download and import this project by navigating to the project page and clicking Download then Import.
  • You will see a warning that importing a complete project will overwrite your project settings. This is fine, as we have just created a blank project. Click Import to continue.
 
An import window will appear, showing which files are included in the project.
  • Click Import to import the project.
  • In the Project window, navigate to Scenes and then double click the Main scene to open it.
You should now see a red cube in the Scene View. Enter Play Mode to test the project. The cube should spin. When you click the cube, it should spin in the opposite direction and a message will appear in the Console window.
 
That’s it! Now that we know how the project works, let’s get ready to build it to a device.

Setting up the Android SDK Tools

The first thing we need to install is the Java Development Kit (known as the JDK).
  • Go to the Java site to download the most recent JDK. It’s labelled as "Java Platform (JDK)". Choose the one with the highest version number.
  • Simply run the installer and follow instructions in the wizard to install it.
Next, we need to install the Android SDK Tools.
  • Go to the Android Developer site.
  • Download the Android SDK Tools (also referred to on the site as "the command line tools"), rather than the full download of Android Studio.
  • Unzip the downloaded file. The resulting directory is the directory that contains the Android SDK Tools.
  • Put the directory in a memorable, accessible location - you’ll need to tell Unity where this is directory later.
  • Open the directory that contains the Android SDK Tools, and navigate to tools.
  • Double click the file called android to run it.
A popup will appear, showing a list of packages that can be installed. By default, the core packages for building and the package for the latest version of the Android OS are selected.
 
If the device you’re building to runs the latest version of Android, you don’t need to select anything else. If the device you’re building to runs an earlier version of Android, scroll down the list of packages and select the version you need.
  • Click Install [x] packages to start the installation process. You will be prompted to accept the licenses for these packages.
  • For each package that you wish to install, select the license on the left, select Accept License, and then click Install to proceed.
A window will appear that shows the progress of the installation. The installation will take some time to complete, so it’s a good time to take a break.
 
  • You may see a popup telling advising you to restart the manager window - if this happens, click OK.
  • When the installation process has completed, close the window.

Preparing your Unity project for building to Android

We now need to return to Unity and switch platforms so that we can build our game for Android.
  • Within Unity, open the Build Settings from the top menu (File > Build Settings).
  • Highlight Android from the list of platforms on the left and choose Switch Platform at the bottom of the window.
 
Switching platforms sets the build target of our current project to Android. This means that when we build, Unity will create an .apk file. Switching platforms also forces Unity to reimport all assets in the project. This doesn’t take long on a small project like this, but be aware that on a larger project this may take some time.
Next, we need to enter the bundle identifier for our game. A bundle identifier is a string that identifies an app. It’s written in what is known as reverse-DNS style, following the format com.yourCompanyName.yourGameName. Allowed characters are alphanumeric characters, periods and hyphens. We need to change the bundle identifier from the default setting in order to build.
There are restrictions on bundle identifiers. When you release an app, its bundle identifier must be unique to your app, and cannot be changed after your app has been published to the Google Play Store. When we build our game for Android, the bundle identifier becomes what is known as the app’s package name. For more information on package names, see this Android documentation.
  • Open the Player Settings in the Inspector panel (Edit > Project Settings > Player).
  • Expand the section at the bottom called Other Settings, and enter your chosen bundle identifier where it says Bundle identifier.
 
Finally, we need to tell Unity where we installed the Android SDK Tools.
  • Using the top menu, navigate to Unity > Preferences (on OSX) or Edit > Preferences (on Windows).
  • When the Preferences window opens, navigate to External Tools.
  • Where it says Android SDK Location, click Browse, navigate to where you put the directory containing Android SDK Tools and click Choose.
 

Preparing your Android device

Next, we need to enable developer mode on our Android devices - this gives you access to various options related to building and debugging, and lets you test the game on your device.
  • On your Android device, navigate to Settings > About phone or Settings > About tablet.
  • Scroll to the bottom and then tap Build number seven times. A popup will appear, confirming that you are now a developer.
  • Now navigate to Settings > Developer options > Debugging and enable USB debugging.

Building an Android project using Unity

Now we’re ready to build!
  • Connect your Android device to your computer using a USB cable.
  • You may see a prompt asking you to confirm that you wish to enable USB debugging on the device. If so, click OK.
  • In Unity, open the Build Settings from the top menu (File > Build Settings).
  • Click Add Open Scenes to add the Main scene to the list of scenes that will be built.
  • Click Build And Run.
 
You will be prompted to choose where to build your .apk. A good place to do this is in a dedicated builds directory in the root of your project.
  • Create a directory called "Builds" in the root of your project (not within your Assets directory, but at the same level as it).
  • Select that directory as the location to build to.
  • In the text input field marked Save As, enter "Android" and click Save.
Unity will now create an .apk file called "Android" in the “Builds” folder, build that file to your device and run it.

Testing the game on your Android device

The game will now run on the connected device. It works! The cube spins, and tapping it causes it to change direction.
Simply playing your game on a device is one way of testing it. It’s a good way of checking things like whether the controls work. However, if you want more information - if you’d like to see logs from the device OS while you play, for example - you should use an application called Android Device Monitor.
Let’s do this now.
  • With the game still running on your device, return to your computer.
  • Navigate to the directory containing the Android SDK Tools.
  • Navigate to tools and double click the application called monitor.
 
Android Device Monitor will now open.
If you look to the bottom of Android Monitor, you’ll see the LogCat console. This contains all of the information that you’d see in the Unity console, along with information about other things that are happening in the OS. You can use this in the same way that you use the console within Unity, to help you debug your game.
The LogCat console contains a lot of information, so it can be useful to filter it.
  • Type "tag:Unity" in the textbox at the top of the LogCat console, and you’ll only see messages that relate to Unity.
 
Try tapping the cube on your device and looking at the debug console. You will see the same log message as you would see in Unity, along with some additional information.
Using the LogCat console to get information is just one of the ways that Android Monitor can help you test, profile and debug your game. It’s a complex subject and we won’t cover all of the options here, but this documentation on the Android site is a good start.

Conclusion

In this lesson, we learned how to build a Unity game to an Android device for testing. We learned how to switch build targets in Unity, what a bundle identifier is, build your Unity game to your device for testing, and how to debug your Unity game on your Android device using Android Monitor.