While Google Cardboard has support for iOS, the VR experience is less than ideal, especially on older iPhones, since Apple has put a software limitation in place which limits the maximum playable video resolution to 1080p. Hardly enough pixels for a realistic looking VR video.
Apple just seems to have the unfortunate habit of making the life of an app developer fairly difficult. That’s why we decided to create this detailed tutorial describing in detail how to publish a Google Cardboard app for iOS to the App Store. Besides this tutorial, I also recommend you read through the Google Cardboard iOS SDK documentation.
First and foremost you will need an Apple Developer account, so sign up now if you don’t have one yet. Apple charges a $99 annual fee for their Developer Program, but enrolling is fairly simple. The only thing that can take a couple of days to process is the D-U-N-S number they require.
Certificates, IDs & Profiles
Now that you have your Developer account, let’s go ahead and use it straight away! Go to https://developer.apple.com/account/ to view what hidden treasures your $99 investment has unlocked. To make sure the app you are trying to submit to the App Store is actually coming from you and not from some random, Apple uses so called Signing Certificates and Provisioning Profiles to identify apps and their creators. They can be tricky to work with, so let me try to explain.
Creating a Signing Certificate
To create a Signing Certificate, click Certificates, IDs & Profiles in the sidebar and then the big + icon on the next page. You now have to choose the type of certificate you want to create, the main options being iOS App Development and App Store and Ad Hoc. The former is used to build your app to your own iPhone for example, while the latter is used to create an app that is ready to be submitted to the App Store or distributed outside of the app store to clients and testers. You want to create both of these certificates, but let’s focus on the App Store and Ad Hoc one for the sake of this tutorial. Select it and press Continue at the bottom.
You are now asked to create a Certificate Signing Request (CSR)… As I said, Apple does not make it easy for you. Luckily there are clear step-by-step instructions shown on the page, so on your Mac – yes, unfortunately you’re not able to submit iOS apps using Windows – open Keychain Access, follow the instructions shown on the Apple Developer page, and then press Continue again.
On the next page, select the CSR file you just saved to your Mac, press Continue again and then press Done to finish up this step of the process. We’ll use this certificate later on in this tutorial.
Creating an App ID
An App ID is a unique name for your specific app, which is required by the App Store to identify your app. To create one, click on App IDs under Identifiers and then on the + sign. Give your App ID a name. This name is only used by you to recognize what it is for, so it’s probably best to fill in the app title here.
Since we want to submit an app to the App Store, select Explicit App ID and then fill in the bundle ID of your app in the Bundle ID field. Beware, this bundle ID has to be 100% identical to the bundle ID of your actual app, including punctuation and capitals. It usually comes in the following form:
In Headjack you can find your bundle ID on the Edit Your App page. After you’ve filled in the Bundle ID, click Continue and then Register to finalize this step.
Creating a Provisioning Profile
After creating your App ID, click on All under the header Provisioning Profiles in the sidebar and then on the big + sign again. This time you have to choose the type of Provisioning Profile you want to create. Your main options are:
iOS App Development
With this Profile you can sign an iOS app which you can then install on your local iPhone for testing purposes
With this profile you can sign an iOS app for the App Store
With this profile you can sign an iOS app which you can then distribute to other people, like clients or beta testers, outside of the App Store
For the purpose of this tutorial, select App Store and then click Continue. On the next page, select the App ID you just created from the dropdown menu and then click Continue again. Now select the App Store distribution certificate you created earlier on and click Continue. Fill in a Profile Name and press continue for the final time.
That’s all we need to do in the Apple Developer portal!
The next portal we’re going to visit is iTunes Connect. You can also find the link to iTunes Connect in the sidebar of the Account page in the Apple Developer portal. iTunes Connect is the place where you manage all your App Store info, like app description, preview images etc.
So log in, then click My Apps > + > New App. In the popup window, select iOS as platform, fill in your app name as it will appear on the App Store, and select the Bundle ID we registered earlier in the Apple Developer portal. SKU can be anything, really. Finally press Create and you’ll be redirected to the App Information page. Here, select the category of your app, then move on to the Pricing and Availability page to select if you want your app to be free or paid, and in which countries it should be available.
The next page is the Prepare for Submission page, where you fill in your app description, contact information, and screenshots of your app in a plethora of different resolutions for each of Apple’s i-devices… I usually take some hi-res screenshots on an iPhone 6 and then scale them down in Photoshop to accommodate the lower resolutions. To make your life a bit easier, click here to download a pack of .psd files with the correct dimensions. Also make sure you upload an app icon without transparency or rounded corners, since Apple takes care of this.
You also see a heading called Build. However, before you can select your build, you first need to upload one. In the next section I’ll explain how.
Building your app
As mentioned before, Apple does not make your life as a developer easy. Luckily Headjack takes care of a lot of the hassle, but there are still a couple steps you need to take to build your app.
Remember the Signing Certificate we created earlier in this tutorial? You’ll have to download it from your Apple Developer account onto your Mac, and then doubleclick the certificate file. When asked if you want to add this certificate to your Keychain, click Add.
We now have to perform one more magic trick to transform this newly installed certificate into a so called Personal Information Exchange, or .p12 file. To do this, follow these steps:
- Open Keychain Access
- Click login under Keychains header
- Click Certificates under Category
- Right-click your certificate, then select Export
- Select Personal Information Exchange (.p12) as file format
- Click Save
- Fill in a password for your .p12 file, then click OK
- Finally, fill in the password of your Mac, then click Allow
You are now the proud owner of a .p12 file! Now login to Headjack and go to Settings > App Signing and click + Add signing files. Fill in a title and then select Cardboard iOS from the dropdown and Store as distribution channel. Finally, upload your .p12 certificate, as well as the Provisioning Profile we created earlier. When done, press Save.
Click to build!
Now go to Apps in the Headjack sidebar, and then open your app. In the top-right Build section, select Cardboard iOS, then Store, and finally select the signing credentials you just uploaded. For security reasons we do not store the passwords of your Signing Certificate, that’s why you are asked to fill it in each time you’re about to start a new build. So please enter your password and then click Build to start the build process of your app!*
You can check the status of your build on the Builds page. You will automatically receive an email with a download link as soon as your app is ready. Your app comes in the form of a .ipa file. This is your compiled app which can be uploaded to iTunes Connect.
* The build process usually takes between 10 to 40 minutes to complete, based on how busy Unity Cloud Build is, which is the platform we use to build Headjack apps with.
If you built your iOS app natively or in Unity, you end up with an Xcode project.
If you’re building your app in Unity, go to Build Settings and switch platform to iOS, then go to Player Settings. There, set your company name, Bundle ID, version number, build number, and a default icon. Set Scripting Backend to IL2CPP, Architecture to Universal, and select Auto Graphics API. In Build Settings, select Run in Xcode as Release and click Build to compile the Unity project to Xcode. Unfortunately you’re not able to simply upload your Xcode project to iTunes Connect, we’ll first have to create a build of this project.
For that, you’ll need an Apple device with the latest version of Xcode installed. Now click on the Unity-iPhone.xcodeproj file to open the project in Xcode. The first thing we need to do now is import all the Signing Certificates and Provisioning Profiles we created earlier into Xcode. To do this, click on Xcode > Preferences. If you haven’t already added your developer account to Xcode, click on the + to add it. Now select your team, click on View details and finally click Download all to download all the certificates and profiles from the Apple Developer portal into Xcode.
Exit out of the preferences and click on the Build Settings tab. There, search for Enable Bitcode under Build Options and set it to No. If you created an iOS App Development Certificate and Provisioning profile, you can connect your iPhone to your Mac and then press the big Play button in the top left of Xcode to build a test version of your app to your device. Test and make sure everything is functioning as it should, then return to Xcode.
Go to the General Settings tab and select your iOS Distribution team from the dropdown menu. Then go to the Build Settings tab and set, under the Code Signing heading, all Code Signing Identities to iOS Distribution. Now click Product > Clean and then Product > Archive. Now get a cup of tea while you wait for the archiving of your project to finish. Once finished, Xcode shows your archived project in the Organizer window.
Refrain from pressing the very enticing big blue button saying Upload to App Store, and instead click Export, then Save for iOS App Store Deployment. Click Next, select your iOS Distribution team again from the dropdown, click Choose, and then Export. Give your file a name and click Export once more. Xcode will now generate a .ipa file, which is your compiled app which can be uploaded to iTunes Connect.
To upload your .ipa file, go to Xcode > Open Developer Tools > Application Loader. Make sure you are signed in with your Apple Developer account, then click Choose, select the .ipa file we just created, and then click Next and finally Send. Once your app has been uploaded, it takes up to 30 minutes before it appears in iTunes Connect.
In iTunes Connect, on the Prepare for Submission page under Builds, you now see Select a build before you submit your app. Click on that link, select the build you just uploaded, and then click Done. Save the page and feel the relief now that you are fi-na-lly able to press the Submit for Review button in the top-right corner. Apple now asks you some questions related to Third Party Content, fill these in and then press Submit.
Congratulations!! You just successfully submitted your iOS app!! 🙂
You can now take a few days off, because Apple takes up to two weeks to review your app submission, although you usually hear back from them within a week. Once they approve your app, it will automatically show up in the App Store, unless you selected that you want to manually release the app after approval.
As I said before, Apple does not make it easy for developers, but hopefully this tutorial clears up some of the confusion. It took me days upon days of frustration to figure all of this stuff out. Some of the main causes of the problems I encountered were:
- Not having created or selected the correct Certificates and Provisioning Profiles in Xcode
- Having Bitcode enabled
- Having an incorrect Bundle Identifier or version/build number
- Having files in the project that were not meant for iOS (like a Windows .dll file)
- Having iOS try to automatically backup app files to iCloud, which we had to fix using UnityEngine.iOS.Device.SetNoBackupFlag in Unity
- Not following the Google Cardboard SDK documentation to the letter
I hope that this step-by-step tutorial will save you many precious hours! If you still have questions, please let me know in the comments.