Installing Apps Wirelessly
iOS 4 supports over-the-air installation of enterprise applications, allowing you to distribute in-house software to your users without having to use iTunes or iPhone Configuration Utility.
Requirements
- A secure web server accessible by authenticated users
- In-house iOS app in .ipa file format
- An XML manifest file, described in this document
- A network configuration that allows the device to access an iTunes server at Apple
Installing the app is simple. Users download the manifest file from your website to their iOS 4 device, which instructs the device to download and install the apps referenced in the manifest.
You can distribute the URL for downloading the manifest file via SMS, email, or by embedding it in another enterprise app you’ve created.
It's up to you to design and host the website used to distribute apps. You need to make sure that users are authenticated, perhaps using basic auth or directory-based authentication, and that the website is accessible via your intranet or the Internet. The app and manifest can be placed in a hidden directory, or in any other location that's readable using HTTP or HTTPS.
Preparing an Enterprise App for Wireless Distribution
To prepare your enterprise app for wireless distribution, you build an archived version in the form of a .ipa file, and a manifest file that enables wireless distribution and installation of the app.
In Xcode, you create an app archive using the “Build > Build and Archive” menu item. Then, in the Archived Applications source in Xcode's Organizer, select the app and click the “Share Application…” button. Then click the “Distribute for Enterprise…” button. You’ll be asked to provide information for the manifest file, which Xcode creates. See below, for information about the manifest file. For more information about building and provisioning apps, see the iOS Dev Center.
About the Wireless Manifest
The manifest is a file in XML plist format. It's used by an iOS 4 device to find, download, and install apps from your web server. The manifest is created by Xcode, using information you provide when you share an archived app for enterprise distribution. See “Preparing an Enterprise App for Wireless Distribution”
A sample manifest plist is included at the end of this document. The following fields are required:
|
Item |
Description |
|
URL |
The fully qualified HTTP or HTTPS URL of the app (.ipa) file. |
|
display-image |
A 57 x 57 pixel PNG image that is displayed during download and installation. Specify the image's fully qualified URL. |
|
full-size-image |
A 512 x 512 pixel PNG image that represents the app in iTunes. |
|
bundle-identifier |
Your app's bundle identifier, as specified in your Xcode project. |
|
bundle-version |
Your app's bundle version, as specified in your Xcode project. |
|
title |
The name of the app, which is displayed during download and installation. |
Optional Keys
There are optional keys that you can use, which are described in the sample manifest plist. You can use the MD5 keys if your app file is large and you want to ensure download integrity beyond the error checking normally done during TCP communications.
Constructing your Website
Upload these items to an area of your website that your authenticated users can access:
- The app (.ipa) file
- The manifest (.plist) file
Your website design is up to you. It can be as simple as a single page that links to the manifest file. When users tap the web link, the manifest file is downloaded, which triggers the download and installation of the apps it describes.
Here is an example link:
|
<a href="itms-services://?action=download-manifest&url=http://example.com/
|
Don't add a web link to the archived app (.ipa). It's downloaded by the device when the manifest file is loaded. Although the protocol portion of the URL is itms-services, the iTunes Store is not involved in this process.
Setting Server MIME Types
It may be necessary to configure your webserver so that manifest and app file are transmitted correctly.
For Mac OS X Server, add the following MIME types to the MIME Types settings using Server Admin:
|
application/octet-stream ipa
|
|
text/xml plist
|
For IIS, add the MIME type in the Properties page of the server using IIS Manager:
|
.ipa application/octet-stream
|
|
.plist text/xml
|
Troubleshooting Wireless App Distribution
Here are some things to keep in mind regarding enterprise apps:
- If wireless app distribution fails with an unable to download message, check the following:
- Make sure the link to the manifest file is correct and that the manifest file is accessible to web users.
- Make sure that the URL to the .ipa (in the manifest file) is correct and that the .ipa is accessible to web users.
- Make sure the app is signed correctly. Test it by installing it on a device using iPhone Configuration Utility.
Network Configuration Requirements
If the devices are connected to a closed internal network, you should allow iOS devices to these sites.
|
URL |
Reason |
|
ax.init.itunes.apple.com |
The device obtains the current file size limit for downloading apps over the cellular network. If this site it not reachable, installation may fail. |
|
ocsp.apple.com |
The device contacts this site to check the status of the distribution certificate used to sign the provisioning profile. See “Certificate Validation.” |
Providing Updated Apps
Apps that you distribute yourself aren't automatically updated. When you have a new version for users to install, notify them of the update and instruct them to install the app. Consider having the app check for updates and notify the user when it opens. If you're using wireless app distribution, provide a link to the website or manifest file of the updated app. If you're using iTunes, provide them with a new app to install on their device. If you're using iPhone Configuration Utility, have them contact an IT administrator to install the new version. You will need to update all of your enterprise apps at least once a year, see“Certificate Validation.”
If you want users to retain data stored on their device, make sure the new version uses the same bundle-identifier as the one it's replacing and tell users not to delete their old version before installing the new one. The new version will replace the old one and retain data stored on the device, provided that the bundle-identifiers match.
Certificate Validation
The first time an application is opened on a device, the distribution certificate is validated by contacting Apple's OCSP server. Unless the certificate has been revoked, the app is allowed to run. Inability to contact or get a response from the OCSP server is not interpreted as a revocation. To verify the status, the device must be able to reach ocsp.apple.com. See “Network Configuration Requirements.”
The OCSP response is cached on the device for the period of time specified by the OCSP server; currently between 3 and 7 days. The validity of the certificate will not be checked again until the device has restarted and the cached response has expired. If a revocation is received at that time, the app will be prevented from running. Note that revoking a distribution certificate will invalidate all of the applications you have distributed.
An app will not run if the distribution certificate has expired. Currently, distribution certificates are valid for one year. A few weeks before your certificate expires request a new distribution certificate from the Dev Center, use it create create new distribution provisioning profiles, then recompile and distribute the updated apps to your users. See “Providing Updated Apps.”
Sample Manifest File
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <!-- array of downloads. --> <key>items</key> <array> <dict> <!-- an array of assets to download --> <key>assets</key> <array> <!-- software-package: the ipa to install. --> <dict> <!-- required. the asset kind. --> <key>kind</key> <string>software-package</string> <!-- optional. md5 every n bytes. will restart a chunk if md5 fails. --> <key>md5-size</key> <integer>10485760</integer> <!-- optional. array of md5 hashes for each "md5-size" sized chunk. --> <key>md5s</key> <array> <string>41fa64bb7a7cae5a46bfb45821ac8bba</string> <string>51fa64bb7a7cae5a46bfb45821ac8bba</string> </array> <!-- required. the URL of the file to download. --> <key>url</key> <string>http://www.example.com/apps/foo.ipa</string> </dict> <!-- display-image: the icon to display during download .--> <dict> <key>kind</key> <string>display-image</string> <!-- optional. indicates if icon needs shine effect applied. --> <key>needs-shine</key> <true/> <key>url</key> <string>http://www.example.com/image.57x57.png</string> </dict> <!-- full-size-image: the large 512x512 icon used by iTunes. --> <dict> <key>kind</key> <string>full-size-image</string> <!-- optional. one md5 hash for the entire file. --> <key>md5</key> <string>61fa64bb7a7cae5a46bfb45821ac8bba</string> <key>needs-shine</key> <true/> <key>url</key><string>http://www.example.com/image.512x512.jpg</string> </dict> </array><key>metadata</key> <dict> <!-- required --> <key>bundle-identifier</key> <string>com.example.fooapp</string> <!-- optional (software only) --> <key>bundle-version</key> <string>1.0</string> <!-- required. the download kind. --> <key>kind</key> <string>software</string> <!-- optional. displayed during download; typically company name --> <key>subtitle</key> <string>Apple</string> <!-- required. the title to display during the download. --> <key>title</key> <string>Example Corporate App</string> </dict> </dict> </array> </dict> </plist> |