The iTunesMetadata.plist File in Xamarin.iOS Apps

Article
03/19/2017

This article covers the iTunesMetadata.plist file used to provide information to iTunes about an iOS application using Ad Hoc distribution for either testing or Enterprise deployment.

When an iOS application is created in iTune Connect (either for sale or free release from the iTunes App Store), the developer can specify information such as the application's genre, sub genre, copyright notice, supported iOS devices and required device capabilities. For iOS applications that are delivered either to testers or Enterprise user via ad hoc distribution, this information is missing.

To supply the missing information to an Ad Hoc distribution, an optional iTunesMetadata.plist file can be created and included in the applications IPA file. This plist file is a specially formatted XML file (see Apple's Property List Programming Guide for more information) that contains key/value pairs defining information about a given iOS application.

The iTunesMetadata.plist Contents

The following is an example of typical iTunesMetadata.plist file used to define the iTunes information for an Ad Hoc distribution:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>UIRequiredDeviceCapabilities</key>
    <dict>
        <key>armv7</key>
        <true/>
        <key>front-facing-camera</key>
        <true/>
    </dict>
    <key>artistName</key>
    <string>Company, Inc.</string>
    <key>bundleDisplayName</key>
    <string>App Name</string>
    <key>bundleShortVersionString</key>
    <string>1.5.1</string>
    <key>bundleVersion</key>
    <string>1.5.1</string>
    <key>copyright</key>
    <string>© 2015 Company, Inc.</string>
    <key>drmVersionNumber</key>
    <integer>0</integer>
    <key>fileExtension</key>
    <string>.app</string>
    <key>gameCenterEnabled</key>
    <false/>
    <key>gameCenterEverEnabled</key>
    <false/>
    <key>genre</key>
    <string>Games</string>
    <key>genreId</key>
    <integer>6014</integer>
    <key>itemName</key>
    <string>App Name</string>
    <key>kind</key>
    <string>software</string>
    <key>playlistArtistName</key>
    <string>Company, Inc.</string>
    <key>playlistName</key>
    <string>App Name</string>
    <key>releaseDate</key>
    <string>2015-11-18T03:23:10Z</string>
    <key>s</key>
    <integer>143441</integer>
    <key>softwareIconNeedsShine</key>
    <false/>
    <key>softwareSupportedDeviceIds</key>
    <array>
        <integer>9</integer>
    </array>
    <key>softwareVersionBundleId</key>
    <string>com.company.appid</string>
    <key>subgenres</key>
    <array>
        <dict>
            <key>genre</key>
            <string>Puzzle</string>
            <key>genreId</key>
            <integer>7012</integer>
        </dict>
        <dict>
            <key>genre</key>
            <string>Word</string>
            <key>genreId</key>
            <integer>7019</integer>
        </dict>
    </array>
    <key>versionRestrictions</key>
    <integer>16843008</integer>
</dict>
</plist>

The values for the individual keys will be covered in detail below.

UIRequiredDeviceCapabilities

The UIRequiredDeviceCapabilities key lets iTunes know which device specific features an iOS application requires before it can be installed on a given iOS device. It is provided as a dictionary (<dict>...</dict>) of features (<key>...</key>) and a boolean value for each feature. If the value of a feature is true, then that feature must be present. If it is false the feature must not be present on the device. For example:

<key>UIRequiredDeviceCapabilities</key>
<dict>
    <key>armv7</key>
    <true/>
    <key>front-facing-camera</key>
    <true/>
</dict>

Specifies that the iOS device must support the ARM7 instruction set and have a front-facing camera before this application can be installed on the device. For a complete list of allowed values, please see Apple's UIRequiredDeviceCapabilities documentation.

artistName and playlistArtistName

Use the artistName and playlistArtistName keys to define the name of the company that created the iOS application that will be displayed in iTunes. Example:

<key>artistName</key>
<string>Company, Inc.</string>
...
<key>playlistArtistName</key>
<string>Company, Inc.</string>

bundleDisplayName, itemName, and playlistName

Use the bundleDisplayName, itemName, and playlistName keys to define the name of the iOS application that will be displayed inside of iTunes. Example:

<key>bundleDisplayName</key>
<string>App Name</string>
...
<key>itemName</key>
<string>App Name</string>
...
<key>playlistName</key>
<string>App Name</string>

bundleShortVersionString and bundleVersion

Use the bundleShortVersionString and bundleVersion keys to define the iOS application version number that will be displayed in iTunes. Example:

<key>bundleShortVersionString</key>
<string>1.5.1</string>
<key>bundleVersion</key>
<string>1.5.1</string>

softwareVersionBundleId

Use the softwareVersionBundleId key to specify the Bundle ID for the iOS application. Example:

<key>softwareVersionBundleId</key>
<string>com.company.appid</string>

copyright

Use the copyright key to define the copyright notice that is displayed in iTunes. Example:

<key>copyright</key>
<string>© 2015 Company, Inc.</string>

releaseDate

Use the releaseDate key to provide a release date for the iOS application that will be displayed in iTunes. Example:

<key>releaseDate</key>
<string>2015-11-18T03:23:10Z</string>

softwareIconNeedsShine

Use the softwareIconNeedsShine key to tell iTunes if the iOS Application's icon requires a shine highlight for iOS 6 (and prior). Example:

<key>softwareIconNeedsShine</key>
<false/>

gameCenterEnabled and gameCenterEverEnabled

Use the gameCenterEnabled and gameCenterEverEnabled keys to tell iTunes is this iOS application supports Apple's Game Center. Example:

<key>gameCenterEnabled</key>
<false/>
<key>gameCenterEverEnabled</key>
<false/>

genre, genreId, and subgenres

Use the genre and genreId keys to tell iTunes what genre the iOS application belongs to. Example:

<key>genre</key>
<string>Games</string>
<key>genreId</key>
<integer>6014</integer>

Optionally the subgenres key can be used to further define up to two sub genres for the iOS application. Example:

<key>subgenres</key>
<array>
    <dict>
        <key>genre</key>
        <string>Puzzle</string>
        <key>genreId</key>
        <integer>7012</integer>
    </dict>
    <dict>
        <key>genre</key>
        <string>Word</string>
        <key>genreId</key>
        <integer>7019</integer>
    </dict>
</array>

For iOS applications, Apple currently defines the following genres and genre IDs:

Genre ID	Genre Name
6000	Business
6001	Weather
6002	Utilities
6003	Travel
6004	Sports
6005	Social Networking
6006	Reference
6007	Productivity
6008	Photo & Video
6009	News
6010	Navigation
6011	Music
6012	Lifestyle
6013	Health & Fitness
6014	Games
6015	Finance
6016	Entertainment
6017	Education
6018	Books
6020	Medical
6021	Newsstand
6022	Catalogs

Games (6014) sub-genres:

Genre ID	Genre Name
7001	Action
7002	Adventure
7003	Arcade
7004	Board
7005	Card
7006	Casino
7007	Dice
7008	Educational
7009	Family
7010	Kids
7011	Music
7012	Puzzle
7013	Racing
7014	Role Playing
7015	Simulation
7016	Sports
7017	Strategy
7018	Trivia
7019	Word

Newstand (6021) sub-genres:

Genre ID	Genre Name
13001	News & Politics
13002	Fashion & Style
13003	Home & Garden
13004	Outdoors & Nature
13005	Sports & Leisure
13006	Automotive
13007	Arts & Photography
13008	Brides & Weddings
13009	Business & Investing
13010	Children’s Magazines
13011	Computers & Internet
13012	Cooking, Food & Drink
13013	Crafts & Hobbies
13014	Electronics & Audio
13015	Entertainment
13017	Health, Mind & Body
13018	History
13019	Literary Magazines & Journals
13020	Men’s Interest
13021	Movies & Music
13023	Parenting & Family
13024	Pets
13025	Professional & Trade
13026	Regional News
13027	Science
13028	Teens
13029	Travel & Regional
13030	Women’s Interest

softwareSupportedDeviceIds

Use the softwareSupportedDeviceIds key to tell iTunes what iOS devices this iOS application supports. Example:

<key>softwareSupportedDeviceIds</key>
<array>
    <integer>9</integer>
</array>

Where the following values are available:

1 – Classic iPhones
2 – iPod Touch
4 – iPad
9 – Modern iPhones

Standard Keys

The following keys are included in all iTunesMetadata.plist files for iOS applications and always have the same values:

<key>drmVersionNumber</key>
<integer>0</integer>
<key>fileExtension</key>
<string>.app</string>
...
<key>kind</key>
<string>software</string>
...
<key>s</key>
<integer>143441</integer>
...
<key>versionRestrictions</key>
<integer>16843008</integer>

When working with an iTunesMetadata.plist file in Visual Studio for Mac, you have two options:

Create and maintain the file using Visual Studio for Mac's visual plist editor.
Create and maintain the file in a plain text editor.

Both options will be covered in detail below.

Using the Visual Plist Editor

Do the following:

In the Solution Explorer, right-click the Xamarin.iOS project file and select Add > New File...
From the New File Dialog, select iOS > Property List:
Enter iTunesMetadata for the Name and click the New button.
Double-click the iTunesMetadata.plist file in the Solution Explorer to open it for editing:
Click the green + to create a new entry and enter UIRequiredDeviceCapabilities as the key name:
Click on the String value type and select Dictionary from the popup list:
Click the turndown at the left of the Property's name to reveal the dictionary's entries:
Click on the Add new entry text, then click the green + to add an entry to the dictionary:
Enter armv7 for the key name, select a type of Boolean and enter Yes as the value:
Repeat the steps above until you have filled out the iTunesMetadata.plist file with all of the key/value pairs required (see the The iTunesMetadata.plist Contents section above for more details).
Save the changes to the plist file.

Using a Plain Text Editor

Do the following:

In a plain text editor, create a new text file and name it iTunesMetadata.plist.
Copy the example contents from the The iTunesMetadata.plist Contents section above.
Paste the contents in the file and edit them as required.
Save the file and return to Visual Studio for Mac.
In the Solution Explorer, right-click on the Xamarin.iOS project file and select Add > Existing Files....
In the Open File Dialog, select the iTunesMetadata.plist file that was created above and click the OK button.
Leave the Build Action of this file set to None.

The Xamarin plugin for Visual Studio only supports a visual editor for Info.plist and Entitlement.plist files, so you'll need to create your iTunesMetadata.plist file in a standard text editor and manually include it in your Xamarin.iOS project.

Do the following:

In a plain text editor, create a new text file and name it iTunesMetadata.plist.
Copy the example contents from the The iTunesMetadata.plist Contents section above.
Paste the contents in the file and edit them as required.
Save the file and return to Visual Studio.
In the Solution Explorer, right-click on the Xamarin.iOS project file and select Add > Existing Files....
In the Open File Dialog, select the iTunesMetadata.plist file that you created above and click the Open button.
Leave the Build Action of this file set to None.

Later, select this iTunesMetadata.plist file when you prepare to build your IPA in the IDE.

Summary

This article has covered the iTunesMetadata.plist file that can be used to tell iTunes about an ad hoc delivered iOS application. It has discussed the standard key in the plist file and how to create and maintain the file in Visual Studio and Visual Studio for Mac.

Share via

The iTunesMetadata.plist File in Xamarin.iOS Apps

The iTunesMetadata.plist Contents

UIRequiredDeviceCapabilities

artistName and playlistArtistName

bundleDisplayName, itemName, and playlistName

bundleShortVersionString and bundleVersion

softwareVersionBundleId

copyright

releaseDate

softwareIconNeedsShine

gameCenterEnabled and gameCenterEverEnabled

genre, genreId, and subgenres

softwareSupportedDeviceIds

Standard Keys

Creating an iTunesMetadata.plist File

Using the Visual Plist Editor

Using a Plain Text Editor

Summary

Additional resources

Share via

The iTunesMetadata.plist File in Xamarin.iOS Apps

The iTunesMetadata.plist Contents

UIRequiredDeviceCapabilities

artistName and playlistArtistName

bundleDisplayName, itemName, and playlistName

bundleShortVersionString and bundleVersion

softwareVersionBundleId

copyright

releaseDate

softwareIconNeedsShine

gameCenterEnabled and gameCenterEverEnabled

genre, genreId, and subgenres

softwareSupportedDeviceIds

Standard Keys

Creating an iTunesMetadata.plist File

Using the Visual Plist Editor

Using a Plain Text Editor

Summary

Related Links

Additional resources