Before you will be able to test your iOS app or submit it to the app store, you will be required to create a set of certificates.
The requirements are different for debugging and releasing an app, as well as using push notifications. We’ll make as clear as possible in this article.
Before getting started, you’ll need to make sure to have:
- An Apple computer
- An approved iOS developer account
A Visual Guide
Before we get into the step-by-step tutorial, here is a bird’s eye view of the process.
Every app needs an ID, certificate, and a provisioning profile to work on a device or to be added to the app Store.
- Create an app ID
- Request and download a certificate
- Export the certificate with key into a .p12 file
- Using the app ID and certificate from above, create a provisioning profile
- Build the app using the .p12 file and provisioning profile
Note: If your app uses push notifications, you will need one additional certificate. We’ll cover that a bit later in this article.
Before we proceed, let’s clear up some terminology.
As you are going through this process, you will have the option to create Development or Production certificates. The process is virtually identical, other than a couple of checkboxes.
A Development certificate is required to test your app on a device before submitting it to the app store. It is only good for testing and cannot be used when submitting your app to the app store. Likewise, Production certificates can not be used for testing.
A tip for development vs. production certificates
For developing apps, we suggest creating a single Development certificate and provisioning profile using a wildcard app ID. This will allow you to use the same certificate for testing all of your apps. Then, when you’re ready to submit to the app store, you simply create a Production certificate specifically for the app using a unique app ID.
If this all sounds Greek to you still, have no fear. We’ll explain as we go along. Let’s get started.
In order to test a development build of your app on your device, you have to register your device. If you want to test the app on multiple devices, register them all prior to creating your provisioning profile, otherwise you’ll need to regenerate the provisioning profile and rebuild the app.
To start, login to your developer account at developer.apple.com.
Next, connect your device to your computer with a USB cable and open iTunes. Click on your device icon in the toolbar. Under Summary, you will be shown your phone’s Capacity, Phone Number and Serial Number. Click on the Serial Number and you will then be shown the phone’s UDID. Right-click on the UDID string to copy it to your clipboard.
In your browser, click the “Certificates, Identifiers & Profiles” box.
On the left nav bar, click Devices -> All. This will show you a list of all the devices you’ve registered so far. If this is your first time here, the list will be blank. Click the button with a plus (+) button in the top-right corner next to where it says “All Devices”.
Enter a name and the UDID for your device. Here’s how to find your UDID: https://www.innerfence.com/howto/find-iphone-unique-device-identifier-udid
Suggestion: When naming your device, use something identifiable like “John’s iPhone 6 Plus” and “Scott’s iPad Mini”. This way, if you upgrade your devices, you’ll know exactly which devices can be removed safely in the future.
The Development Certificate
Earlier we talked about creating a wildcard app ID that can be used for all apps you develop. We’re going to do that next. Once created, this certificate can be reused, so you only have to do this process once.
Wildcard App ID
In your developer account, click on Identifiers -> App IDs. Click the plus button in the top-right corner next to where it says “iOS App IDs”.
Give your app ID a description. Then, in the App ID Suffix section choose Wildcard App ID and enter an asterisk (*) for the Bundle ID. The rest of the fields can be ignored.
Note: push notifications don't work with wildcard app IDs. If you need to test push notifications, you need an explicit app ID.
When finished, your app ID list should look like this:
On the left nav bar, click Certificates -> Development. Click the plus button in the top-right corner next to where it says “iOS Certificates (Development)”.
In the Development section, select iOS App Development and then click Continue.
On the next screen, you’ll see an explanation of the Certificate Signing Request (CSR) process along with the steps needed to create the CSR. Those steps are:
In the Applications folder on your Mac, open the Utilities folder and launch Keychain Access.
Within the Keychain Access drop down menu, select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.
- In the Certificate Information window, enter the following information:
- In the User Email Address field, enter your email address.
- In the Common Name field, create a name for your private key (e.g., John Doe Dev Key).
- The CA Email Address field should be left empty.
- In the "Request is" group, select the "Saved to disk" option.
- Click Continue within Keychain Access to complete the CSR generating process.
Once you’ve saved the CSR to your hard drive, click continue in your browser. You will be taken to the Generate your certificate page.
Click the “Choose File” button, find the CSR you just created and click continue to generate your certificate.
Your certificate is now ready. Click the Download button to save your CSR to your computer.
Note about CSRs: You only have to do this once, then you can use the same CSR for all of your iOS certificates. There is no need to generate multiple CSR files.
Convert to .p12 file
Next you’ll need to export the certificate as a .p12 file. To do that, double-click the certificate you saved to your computer in the previous step. That will open the certificate in the Keychain Access app. Click on My Certificates on the left to view a list of your certificates.
Click the grey arrow next to the newly created certificate to reveal your private key. If you do not see an arrow, something when wrong. You either aren’t an authorized developer, or you didn’t generate the right type of certificate and should start the process over.
Select both items:
Right click (or option click) and select “Export 2 items.”
You will be prompted to save the file. Make sure you name it something like dev-yourcertname-certexpirationdate.p12. This will help later on when you have multiple certs. You will also need to create a password. Make sure you keep a record of this password so you can find it later.
That's it, you now have your development .p12, which you can use to build your app for testing. The last item we need is a provisioning profile.
The Provisioning Profile
On the left nav bar, click Provisioning Profiles -> Development. Click the plus button in the top-right corner next to where it says “iOS Provisioning Profiles (Development)”.
In the development section, choose “iOS App Development” and click continue.
From the dropdown, select the wildcard app ID you created in the previous step and click continue.
Select the certificate that was created in the process above and click continue.
Select all of the devices where you plan to install the app for testing then click continue.
Give your profile a name. Make sure to call it “Wildcard Dev Scott’, or something that tells you exactly what it is at a glance. This will help when you start making other profiles.
Your provisioning profile is ready. Download the profile to your computer and you’re ready to go.
You can now use this provisioning profile along with the .p12 file you created to build your app on Phonegap Build, or other platforms.
- Make sure you've already created your app ID, certificate, and added devices before creating the provisioning profile.
- The certificate you choose with the provisioning profile must be the same one as the .p12 you are using.
- Don't mix up development and production profiles/certs. They have to both be the same, either both dev or both production.
The development certificate and profile you just created can be re-used for testing all of your apps. To submit to the app stores (or test push notifications) you will need to create a production certificate with an explicit app ID.
Let's look at how to do that.
The Production Certificate
If you've already created your development certificate, the production one is easy. It's the same exact process, but we just tweak a couple of things.
- We use an explicit app ID, not a wildcard (com.mything.app)
- We choose "Production" for our certificate, not development
- We choose "Distribution" for our provisioning profile, not development
Everything else is the same, including creating the .p12 and provisioning profile.
Production App ID
Go to Identifiers->App IDs, and create a new one by clicking the plus button.
This time, choose Explicit App ID, and make up a reverse domain name like com.mycompany.myapp. It's not important what it is, but it's a good idea to use a naming convention like I did.
Ignore the other options and save.
This is the same exact process as creating a development certificate, except you choose "App Store and Ad Hoc" instead of Development.
You can use the same Certificate Signing Request you created before, generate and download the certificate. Convert it to a .p12 the same way as before.
That's it for your certificate, now we just need an App Store provisioning profile.
Distribution Provisioning Profile
Under Provisioning Profiles, click Distribution, then click the plus button to add a new one.
This process is exactly the same as before, except we choose App Store.
When going through the profile options:
- Choose the explicit app ID you created above.
- Then choose the production certificate you created in the last step.
- Generate your profile and download, that's it! Make sure to give it a good name like 'Appname App Store Certname'
You now have your production .p12 and distribution provisioning profile, you can build your app with those 2 things and it's ready to submit to the app store!
There's one last thing we need to deal with, and that's an app with push notifications.
An app built with push notifications has a couple extra requirements. You still need a production .p12 and provisioning profile like we did above, but you also need an extra SSL certificate.
Here are the steps we are going to take:
- Do everything under Production Certificate above
- Create push notifications SSL certificate
Assuming you've already done the steps under Production Certificate above for your app, let's create the SSL certificate.
Push Notifications SSL Certificate
Push notifications require a server that sends a notification to Apple's servers, then Apple sends that notification out to the app. That means you need to use your own server for this, or use a 3rd party service.
I won't go into how to set that all up, we are just going over how to create the certs. You can read this article if you are curious about setting up your own push server.
The SSL certificate is installed on the server that is sending pushes to Apple, which then go to your app. Let's create this certificate now.
First, go to your App IDs, and click on your app's ID, then click the Edit button.
Scroll down to the box that says Push Notifications. Check the box beside it.
Next, under Production SSL Certificate, click Create Certificate. (Some services allow you to use a development certificate for testing push, but for a live app you need to use production)
You will be prompted for a Certificate Signing Request, use the same one you created before, then generate the certificate. Download it, and you're done!
This certificate is used on the server you send push notifications from, it is not used to build the app.
Some services need this certificate, and some require you to create a .p12 file out of it. Follow the directions at your push notifications provider.
Testing Push NotificationsTesting push can be tricky. First, you must be on a real device, not in an emulator. Second, you always have to use an explicit app ID, not a wildcard app ID. If you are using Phonegap Build, you must use an explicit app ID, production certificate, and ad hoc provisioning profile to test push. You cannot use a development certificate to test. Some push notifications providers have a sandbox mode that you can use to test, follow their provided instructions if that is the case.
Creating these certificates can go wrong very quickly.
If something isn't working right, the only thing you can really do is delete everything and start over. Hopefully you won't have to do that, here are some tips to keep you out of trouble.
- Don't mix someone else's certs or profiles with your own. Make everything on your machine at the same time.
- All certs and profiles have to match up, all development or all production/distribution, and all for the same app ID.
- Make sure you are a registered developer on the account, it won't work if you're not.
- Use the same certificate signing request for all certs
- Keep everything organized on your machine in folders, with good names
- Keep track of your .p12 passwords, you'll need them later
- Certs only last for one year. Your apps won't stop working when they expire, but you'll need to create new ones if you want to make new apps or resubmit.
Hopefully that helps you submit your app to Apple without too many forehead bleeds from banging your head against your desk.
Further documentation can be found in the PhoneGap Build documentation.