Setting up the Entitlements.plist file in Xcode

The process of distributing your iPhone app to the testers (doing an ad hoc distribution) can be a bit confusing to say the least. I will write about generating certificates, App Ids and provisioning profiles later (I always start writing these blogs late at night, when I don't have much time and I'm not fully awake! I don't know why) however, right now I want to talk about a specific part of the distribution that nearly made me lose my mind, namely the "Entitlements" file.

In order to be able to distribute your application you need a code signing file called "Entitlements.plist" (which was not included in my project by default) so how do we add it and configure it?

1 - In your Xcode project, click on "Resources"in the Groups & Files left side pane. Then click on File -> New File
2 - Select the Code Signing section, and then select Entitlements and hit next.

3 - Name the file "Entitlements.plist" and make sure the targets you want to use for your distributions are selected and then hit Finish. You may have just one, here I have two because my ad hoc distribution is slightly different (it includes a iTunesArtwork file which is not required to be included in package for App Store, but allows your iTunes artwork to show up in your testers' iTunes. I will write about this in another post).

4 - Then select the "Entitlements.plist" file in your Resources. An important thing here is that there should be a key in the Root of your Entitlements called "get-task-allow" and its value should be false. HOWEVER, my Entitlements file didn't have that. If this is your case as well, select application-identifier and click on the + sign on the right. This will create a new key under the Roots. Type "get-task-allow" as the key and change its type to Boolean. Then make sure the check box value is not selected.

5 - Now the important part, the "application-identifier" key. If you mess this up you will get the dreadful "Entitlements are not valid" message when your tester tries to install the app in the device (and I'm assuming that you will have problems with your App Store distribution as well maybe something like "Your bundle identifier is incorrect").

The "application-identifier" should be the exact App Id that you see when you sign in the iOS Provisioning Portal in developer.apple.com. In Provisioning Portal you have to click on App IDs tab and then select the App Id you have selected for your application and add that as the "application-identifier". This includes the ten character bundle seed ID that Apple adds automatically to your bundle ID. So it would have a form similar to xxxxxxxxxx.com.your-company-name.application-name.

Now you can also create an App Id with a wildcard, and it should still work, and in your Entitlements file you should still put the ten character bundle seed ID of the App Id followed by a dot followed by your bundle identifier; however, since I didn't use wildcard in my App Id I can't really say it will work for sure.

6 - Another thing you need to do is to make sure you specify the location of the Entitlements in your project settings.

Go to Project->Edit Project Settings. Click on the "Build" tab. Make sure the configuration is set to the "Release" mode. Then scroll down to the "Code Signing" part. Enter "Entitlements.plist" in the "Code Signing Entitlements" section. Also expand "Code Signing Identity" node and change the value to the appropriate provisioning profile that you have created in the iOS Provisioning Profile.

And that should be it.

Anyways, if you have any suggestions or questions please leave a comment.