Creating an iOS Ad Hoc Distribution Application

This article assumes that you have properly set up an iOS development app in Xcode and have successfully implemented push notifications by following our iOS implementation documentation

For for more information on the role of an ad hoc distribution app in the development process, please see Best Practices for Testing and Submitting iOS apps

 

This article will walk through the following steps to create an Ad Hoc build:

  1. Create the proper push certificate.
  2. Create a production application 
  3. Create a Production Ad Hoc Distribution Certificate
  4. Create the Ad Hoc Provisioning Profile.
  5. Open the project in Xcode 
  6. Checks
  7. Compile and Send a Test Message

Step 1: Create the Push Certificate

 To do this, begin by logging into the Apple Developer Member Center.

 

1. Click on Certificates, Identifiers & Profiles:

 membercenter.png


2. Click Identifiers:

identifiers.png

 

3. Under the Identifiers list on the left side, click on the App IDs sub tab. 

AppId.png

 

4. Click on the application for which you would like to create the Ad Hoc build and click Edit.

EditApp.png

 

5. Scroll down to the bottom of the page and find the Push Notifications option.  Under Production SSL Certificate (NOT under Development SSL Certificate) click Create Certificate...:

 createCert.png

 

6. After clicking Create Certificate, you will see the Add iOS Certificate Assistant. Follow the instructions under Create a CSR file in the assistant to create a Certificate Signing Request (CSR):

AddCertAssistant.png

 

7. Generate the Certificate by uploading the CSR File you saved out in the previous step:

genCert.png

 

 8. After the certificate is generated, click the Download button to download the certificate to your Apple computer:

downloadCert.png

 

9. Double-click on the .cer file to import the certificate into your keychain.

If you have trouble with creating your iOS Distribution SSL Certificate, see our documentation on how to Get your Certificate from Apple.  

Step 2: Create a production application 

Next, you will need to create a production application on your Urban Airship account and use the file you just downloaded to set the application up with the APNS push service.

1. Make a copy of your app and make sure you select "In production, connecting to real push servers". For more information please see Production vs Development Apps in Urban Airship

2. Follow the steps under Configure APNS Service with Urban Airship

Step 3: Create a Production Ad Hoc Distribution Certificate

1. Back in the Apple Developer Member Center, under the Certificates list on the left side, click on Production, then click on the + button in the top right corner as shown below. Under Production, select  App Store and Ad Hoc from the list of choices, and then click Next:


2. Follow the directions in the Add iOS Certificate wizard to create a Certificate Signing Request, upload it to the Apple website, and generate an iOS Distribution Certificate. After the certificate is generated, click the Download button to download the certificate to your computer. Double-click on the file to import the certificate into your keychain.

Step 4: Create the Ad Hoc Provisioning Profile.

1. Go back to the Apple Developer Center, click the Done button.

2. In the left menu, under the Provisioning Profiles, click Distribution, then click on the button in the upper right corner. When asked for the type of provisioning profile you need created, select the Ad Hoc option and click Next.



3. Select the app ID that you wish to create an Ad Hoc distribution build with, and click Next.

4. Select the iOS Distribution Certificate you created in the previous step, and click Next.

5. Add the iOS device you will be testing the Ad Hoc build with to the list of devices, and click Next.

6. Follow the directions given from the Add Provisioning Profile wizard to create a Certificate Signing Request, upload it to the Apple website, and generate an Ad Hoc Provisioning Profile.

7. After the profile is generated, click the Download button to download the profile to your Apple computer

8. Double-click on the file to import the profile into Xcode. 

Step 5: Open the project in Xcode 

1. Open your project in Xcode and change the code signing identity and provisioning profile of the desired configuration. Verify that the project and each target are all set to the certificate and provisioning profile you just downloaded.

 

If you do not see your profile or certificate in the list, go to Xcode > Preferences. Under the Accounts tab, select your Developer Portal account. If your Developer Portal Apple ID is not in the list, you will need to add it to the Accounts list. Afterwards, click on the Advanced button, and click Refresh. Then, close and relaunch Xcode. The information should be refreshed.


Step 6: Checks

1. Open your AirshipConfig.plist file and double-check that the correct App keys and App Secrets are in the correct builds of the file.

2. If you are using the inProduction flag, make sure that it is set to YES.

3. If you are not using an AirshipConfig.plist file to set up your application for push notifications, make sure that the UAConfig options are set properly in your code.

4. Lastly, verify that the bundle ID of the application matches the Bundle Identifier you used to create your provisioning profile and SSL Certificate.

Step 7: Compile and Send a Test Message

1. Compile your app with a release build.

2. Enable push notifications on your device.

3. Send a test message to it.

Troubleshooting

If, after following the directions above, your push notification did not arrive, or if Xcode is flagging any code signing identity or provisioning profile errors, double-check the following items:

1. Verify that you opted-in for push notifications on your application.

2. Verify that your AirshipConfig.plist file or UAConfig explicit code implementation is correct. Make sure that it is linking to the correct App Keys and App Secrets. If you are using the inProduction flag, make sure that it is set to YES.

3. Make sure that you are compiling a Release build in Xcode, and that the correct provisioning profiles and code signing identities are set. If this does not resolve the issue, log into your Apple Developer account and verify that your provisioning profile is associated with the correct Application Bundle ID, Test Device, and Distribution Certificate. 

If any certificate or identity information is missing, incorrect, or not associated with the correct bundle ID, push notifications will not arrive to your device.

If you find any mistakes, make the necessary changes and replace the files in your keychain and follow the next step below to update your Urban Airship account to receive push notifications with the correct information.

4. Verify that your Urban Airship production application is properly set up for APNS push notifications. Export and upload a new .p12 file if you found any mistakes in step 3 above.

Related Content: