Introduction

Overview

This document provides information on delivering Game Center metadata to your existing apps. For Game Center, you provide metadata for leaderboards and achievements, as well as providing localizations.

Metadata is delivered to the App Store in the App Store Package format. An App Store Package is a directory that contains the data necessary to describe and deliver an app product. The directory includes an XML file containing metadata about the Game Center assets, such as Achievement and Leaderboard images. Each package represents one app product within the App Store. For each app product, you can deliver multiple Game Center leaderboards and achievements in the same package.

Game Center leaderboards and achievements are delivered in one <software_metadata> element for a single app product as shown in Basic Game Center Metadata Example. For more details about delivery, see Package Format.

About This Release

Date/Version

Changes Made

July 25, 2021 - Version 6.0

Updated the XML schema to version 6.0.

Removed the basic app, basic in-app purchase, and interval pricing metadata.

What’s New in App Metadata Specification 6.0?

XML schema updates

App Metadata Specification 6.0 is a significant change to the XML schema. This schema change removes the following features:

  • Basic app metadata

  • In-app purchase metadata

  • Interval pricing metadata

With this change, schema version 5.12 is deprecated.

See the App Store Connect API for information on delivering app metadata.

Delivery & Formatting Guidelines

Package Format

You deliver Game Center metadata, which includes achievement and leaderboard images, in the App Store Package format (.itmsp) through Transporter. Each App Store package can contain up to 100 achievements and up to 25 leaderboards.

An App Store Package is a directory with the extension ".itmsp" that contains:

  • an XML file named metadata.xml that describes the delivered content using the structure documented in this specification

  • achievement and leaderboard images (can be localized) (if delivering Game Center achievements and/or leaderboards)

For example, if the vendor identifier (the app's SKU in App Store Connect) is CI0009, the package would consist of a directory named CI0009.itmsp, and would contain the files listed below for an app that includes Game Center achievements and leaderboards.

Note: The filenames listed below for images are sample filenames, not required filenames.

  • metadata.xml (xml-formatted metadata for a specific delivered app)

  • after_achievement1_image.png, after_achievement2_image.png, leaderboard_easy_image.png, leaderboard_medium_image.png, leaderboard_hard_image.png for each achievement and/or leaderboard. Can be localized for each <locale>.

The name for the package directory must match the <vendor_id> provided in the accompanying metadata file and should follow the format vendor_id.itmsp. (The <vendor_id> is the SKU in App Store Connect.) The names of the files within the package should correctly match the filenames provided in the accompanying XML. The metadata XML file must be immediately (at the top level) within the package directory.

See the Transporter User Guide for information on how to deliver the package.

Metadata Details

Character Encoding

All metadata files must use UTF-8 Unicode character encoding. UTF-8 efficiently encodes non-Roman characters and helps to ensure that metadata displayed in the store is the same as was intended by the repertoire owner. Your metadata file should not contain a byte-order mark (BOM) as it is not necessary for UTF-8 encoded data files nor is it supported by the App Store at this time. Incorrectly encoded metadata files or files that include a BOM will cause delays or may prevent your content from importing.

This specification defines character lengths in bytes. Japanese language characters are represented in 3 bytes so be sure not to exceed the character lengths when including these characters.

Note that simply including encoding="UTF-8" in your XML declaration is not sufficient. The file itself must also be correctly encoded for accented characters and punctuation to appear correctly in the App Store.

Checksums

All content files (such as the review screenshots) delivered to App Store must include an industry-standard MD5 checksum, a measure that helps to guarantee that the files received by the App Store are correct and complete. Once received, the MD5 checksum contained in the metadata file is compared against the actual screenshot file received by the App Store. If any differences are detected, the screenshot file and the entire corresponding package are rejected. See the Helpful Tools section of this document for tools that can generate MD5 checksums for your content.

Catalog Reports

Catalog reports provide information on Game Center leaderboards and achievements. You can request each type of catalog report once per 24-hour period. Reports are available for 30 days after they are posted and are formatted as tab-delimited text files.

When requesting reports, you can specify the type of report using the -type parameter in the requestReports mode in Transporter. Report types can be:

For example, the following requests all report types to be generated and downloaded to the Reports folder:

$ iTMSTransporter -m requestReports -u username -p password -type all -destination Reports/

If this is the first request for the reports in a 24-hour period, you will receive an email notification when the reports are available for download. If you have previously requested the reports and they are ready to be downloaded, using the requestReports mode will download the reports to the specified location.

To check the status of requested reports, use the listReports mode. Statuses include “Processing” or “Succeeded.”

$ iTMSTransporter -m listReports -u username -p password -type all -destination Reports/

Game Center Profile

Overview

Game Center is Apple’s social gaming network. This chapter provides information on delivering Game Center metadata for leaderboards and achievements, as well as providing localizations.

Use App Store Connect to enable your app for Game Center testing, and deliver the XML to set up your leaderboards and achievements. Then use GameKit Framework to integrate Game Center content into your app. When you are ready to distribute your app, enable your specific app version for Game Center and submit it to the App Store.

Note: Leaderboards and achievements can be set up using App Store Connect or through the metadata XML feed. So, it is possible that your game has some existing leaderboards and/or achievements. When sending leaderboard and achievement metadata (including localizations) through the feed, you are indicating that what you are sending is the current state of that leaderboard or achievement. For example, if you are adding or modifying a leaderboard or achievement, include it and the localizations that you want to add or modify in the metadata. If there is an existing leaderboard or achievement and you want to keep it as is, you can omit the leaderboard or achievement from the metadata XML. Likewise, you can omit the localizations that are to be kept as is.

Game Center functionality requires iOS 4.1 and later. For more information, refer to App Store Connect Help and Game Center Programming Guide.

About Achievements and Leaderboards

Achievements are specific goals that the user can accomplish by reaching a milestone or performing an action within your game (for example, “find 10 gold coins” or “capture the flag in less than 30 seconds”). You can customize the text that describes an achievement, the number of points a player earns by completing an achievement, and the image that is displayed after an achievement has been earned. A player can see their earned achievements using the Game Center service from within the game; they can also compare their achievements with those earned by a friend.

Leaderboards allow your game to post scores to the Game Center service where they can later be viewed by players. When you add leaderboards to your game, you decide how the game’s scores are interpreted and displayed. For example, you can customize a score so that it appears as time, money, or an arbitrary value (for example, “points” or “laps”). You can choose to create multiple categories of leaderboards — for example, you might display a different leaderboard for each level of difficulty your game supports. You can also create combined leaderboards that take the players from the single leaderboards and rank them all together. Finally, your game can retrieve the scores stored in the leaderboard.

Adding leaderboards and achievements to your game is optional. Note that once a leaderboard or achievement is available to the user for any version of your app, it cannot be deleted.

Note: To send single or group leaderboards or achievements for review with a specific version of your app, you must use App Store Connect; this can’t be done through the feed.

About Groups

Groups allow you to share your leaderboard and achievement data between apps. There is no restriction on the type of apps that can belong to a group, but an app can belong to only one group. Apps within a group can still have different default leaderboards.

To share leaderboards and achievements between apps, first set up the group in App Store Connect. In addition, a group can’t exist without containing at least one app, so you need to add the app (or apps) to the group using App Store Connect. You cannot create groups using the XML feed, but you can send group leaderboard or group achievement metadata through the feed. The app you want to associate with the group leaderboard or group achievement should be a member of that group.

Basic Game Center Metadata Example

Below is an example metadata.xml file for delivering achievements and leaderboard metadata.

<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="software6.0"> <provider>CyberInteractive</provider> <team_id>A9B8C7D6E5</team_id> <software> <vendor_id>CI0009</vendor_id> <software_metadata> . . . <game_center> <achievements> <achievement position="1"> <achievement_id>29.2.achievement.1</achievement_id> <reference_name>Achievement One</reference_name> <points>10</points> <hidden>true</hidden> <reusable>true</reusable> <locales> <locale name="en-US"> <title>Achievement One</title> <before_earned_description>Find 10 gold coins</before_earned_description> <after_earned_description>Awesome! You found 10 gold coins</after_earned_description> <achievement_after_earned_image> <file_name>after_achievement_image.png</file_name> <size>286243</size> <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum> </achievement_after_earned_image> </locale> <locale name="fr-FR" remove="true"/> </locales> </achievement> <achievement remove="true"> <achievement_id>29.1.achievement.1</achievement_id> </achievement> </achievements> <leaderboards> <leaderboard default="true" position="1"> <leaderboard_id>29.easy</leaderboard_id> <reference_name>Leaderboard One</reference_name> <aggregate_parent_leaderboard>other_leaderboard_id</aggregate_parent_leaderboard> <sort_ascending>true</sort_ascending> <score_range_min>0</score_range_min> <score_range_max>1000</score_range_max> <locales> <locale name="en-US"> <title>Leaderboard One</title> <formatter_suffix>Points</formatter_suffix> <formatter_suffix_singular>Point</formatter_suffix_singular> <formatter_type>INTEGER_DECIMAL_SEPARATOR</formatter_type> <leaderboard_image> <file_name>leaderboard1_image.png</file_name> <size>286243</size> <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum> </leaderboard_image> </locale> <locale name="fr-FR" remove="true"/> </locales> </leaderboard> <leaderboard remove="true"> <leaderboard_id>29.hard</leaderboard_id> </leaderboard> </leaderboards> </game_center> </software_metadata> </software></package>

Basic Game Center Metadata Annotated

<?xml version="1.0" encoding="UTF-8"?>

XML Declaration (required)

The character encoding of your document must be defined.

The App Store only accepts UTF-8 encoding as it efficiently encodes non-Roman characters.

Important: The metadata.xml file must not contain a byte-order mark (BOM).

XPath

<package xmlns="http://apple.com/itunes/importer" version="software6.0">

Package Container (required)

The xmlns (XML namespace) attribute is required and is used to declare the namespace to which the tags and attributes in the XML are expected to conform. The namespace must be: http://apple.com/itunes/importer.

The version attribute is required. Packages created to this specification must indicate version="software6.0". The “software” portion of the attribute must be in lowercase letters.

XPath

<provider>CyberInteractiveProductions</provider>

Provider (optional if <team_id> supplied)

This value should be the App Store-defined provider short name given for partner identification. If you do not know your provider short name, use the <team_id> tag to supply your team's Company/Organization ID.

Example:

  • CyberInteractiveProductions

  • Minimum length: 1 character

XPath

<team_id>A9B8C7D6E5</team_id>

Team Identifier (optional if <provider> supplied)

This value identifies your organization's team in the Apple Developer Program and is 10 characters long, consisting of numbers and uppercase letters. You can find your Team ID in the Membership section of your account on the Apple Developer website.

Example:

  • A9B8C7D6E5

XPath

<software>

Software (required)

Begins the software element block. Only one software element can be defined per XML delivery.

XPath

<vendor_id>CI0009</vendor_id>

Vendor Identifier (required, see restrictions)

The permanent value that uniquely identifies the software app separately from any other software app given by the provider. This ID is used for tracking your assets and reporting. Vendor identifiers cannot be reused. The vendor_id is the app’s SKU in App Store Connect.

Restrictions: The vendor identifier can only contain alphanumeric characters and underscore marks; it cannot contain spaces, dashes, ampersands, other punctuation, or symbols. The vendor identifier is case-sensitive and must not start with an underscore. If a Vendor ID is numeric, it is treated as a string, not numbers; a vendor identifier of '00000000012345' is not the same as '12345'. The Vendor ID must be at least 2 characters but no more than 100 bytes.

XPath

<software_metadata>

Software Metadata (required)

Begins the metadata element block that includes tags for describing Game Center metadata.

XPath

<game_center>

Game Center (optional)

Begins the Game Center element block. Within the Game Center block, you can deliver one or more achievements and leaderboards.

XPath

<achievements>

Achievements (optional)

Begins the achievements element block. Within the achievements block, you can deliver one or more achievements, as well as remove an existing achievement (described below). Even if you are delivering only one achievement, you must wrap it within an <achievements> tag.

XPath

<achievement position="1">

Achievement (At least one <achievement> is required if <achievements> block is supplied)

Identifies an individual achievement. You can define multiple <achievement> blocks as needed up to 100. The maximum number of achievements you can create is 100 for each app. For example, if you already have 90 achievements defined, and you submit an import package that adds 20 more achievements, delivery will fail.

The position attribute determines the order in which the achievements are presented to users. You can change the order on the app’s Game Center page or by sending a metadata update.

Note that once an achievement is available to the user for any version of your app, it cannot be deleted.

XPath

<achievement_id>29.2.achievement.1</achievement_id>

Achievement ID (required; up to 100 characters)

A unique identifier for the achievement. It can be composed of letters, numbers, underscores (_), and periods (.). This ID is limited to 100 characters. Your Achievement ID is a permanent setting and cannot be changed.

If the achievement is part of a group, prepend the achievement ID with the grp. prefix, for example, grp.time_challenge. Note that before sending group achievement metadata using the XML feed, you must first set up the group in App Store Connect.

XPath

<reference_name>Achievement One</reference_name>

Reference Name (required)

A unique name for the achievement. You can use up to 64 characters and it must be unique within the app. This is an internal reference used when searching for the achievement within App Store Connect. It is not displayed on the App Store.

XPath

<points>10</points>

Points (required)

The point value that this achievement is worth. There is a minimum of 0 (zero) points and a maximum of 100 points per achievement and a maximum of 1000 points total for all achievements (up to 100 achievements are allowed). An achievement that is more difficult or more time consuming to earn should be worth more points.

Note that you cannot change the points after the achievement has gone live.

XPath

<hidden>true</hidden>

Hidden (required)

Setting the value to true hides the achievement on Game Center until a player has achieved it. Must be set to true or false in English. If you do not supply the <hidden> tag, the value is false by default and the achievement will not be hidden. Most achievements should be immediately visible to the player. However, you might hide an achievement if it is intended to be a surprise or if it is available only when the player purchases additional content.

XPath

<reusable>true</reusable>

Reusable (optional)

Setting the value to true indicates that the user can earn the achievement more than once. Must be set to true or false in English. If you do not supply the <reusable> tag, the value is false by default and the user can earn the achievement only once.

XPath

<locales>

  <locale name="en-US"/>

Locale Name (required)

Provides a mechanism to supply localizations of the achievement title, descriptions, and image. If your app is available in multiple countries, you should localize the achievements for each country. If the achievement is new, you must supply localizations for at least one locale. If you are delivering a metadata update, and you are not modifying locale information, you can omit the <locales> block and <locale> tag(s).

The locale indicates both the language and the optional, specific region where the language is spoken. To specify a locale, use a dash character to combine a language with a region subtag. For example, the locale for English-language speakers in Great Britain is en-GB, while the locale for English-speaking residents of the United States is en-US. We recommend providing the region only when it adds useful information. See Language Codes for a list of languages supported for Game Center.

Note: To remove a locale, use the remove attribute, for example, <locale name="fr-FR" remove="true"/>. You can't remove the last remaining locale; you must have at least one locale.

XPath

<title>Achievement One</title>

Localized Title (required)

The localized title of the achievement in the specified <locale> language as you would like it to appear in Game Center. The title must be at least 2 characters but no more than 30.

XPath

<before_earned_description>Find 10 gold coins</before_earned_description>

Localized Before Earned Description (required)

The description of the achievement in the specified <locale> language as it will appear to Game Center users before they have earned it. This description should clearly explain what the player must do to earn the reward. It must be at least 2 characters but no more than 200 bytes.

XPath

<after_earned_description>Awesome! 10 gold coins</after_earned_description>

Localized After Earned Description (required)

The description of the achievement in the specified <locale> language as it will appear to Game Center users after they have earned it. This description should clearly state what they accomplished. It must be at least 2 characters but no more than 200 bytes.

XPath

<achievement_after_earned_image>

 <file_name>after_achievement_image.png</file_name>

 <size>286243</size>

 <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum>

</achievement_after_earned_image>

Localized Image (required if <locale> is new)

Delivers a localized image to be displayed when a player completes the achievement. This image is for the completed achievement only. Incomplete achievements always display a standard image provided by Game Center. The image must be JPEG (.jpg or .jpeg) or PNG (.png) in RGB color mode and must be 512 x 512 pixels or 1024 x 1024 pixels.

Important: Do not scale up the image if it is smaller than the minimum required size.

File Name (required)

The name of the image. File names are case sensitive and spaces are not allowed.

File Size (required)

The size in bytes of the image file. Do not include any commas nor period delimiters.

Checksum (required)

The MD5 checksum of the image file. See the Checksums section for more information.

  </locale>

</locales>

</achievement>

XPath

<achievement remove="true">

  <achievement_id>29.1.achievement.1</achievement_id>

</achievement>

Achievement (optional)

To remove an achievement, include the <achievement> block, set the attribute remove to "true", and indicate the Achievement ID to remove. Note that you cannot remove an achievement after it has gone live.

</achievements>

XPath

<leaderboards>

Leaderboards (optional)

Begins the leaderboards element block. Within the leaderboards block, you can deliver one or more leaderboards, as well as remove an existing Leaderboard (described below). Even if you are delivering only one leaderboard, you must wrap it within a <leaderboards> tag.

XPath

<leaderboard default="true" position="1">

Leaderboard (At least one <leaderboard> is required if <leaderboards> block is supplied)

Identifies an individual leaderboard. You can define multiple <leaderboard> blocks as needed, up to 25 for each app. For example, you might have a leaderboard for each game level: Easy, Medium, and Hard.

Use the default attribute when you have multiple leaderboards and you want to indicate that this leaderboard is the default leaderboard (the first leaderboard that the user sees on the device). Each app can have only one default leaderboard. Note that you can move the default from one leaderboard to another by including both leaderboards in the package, omitting the default="true" from the current default leaderboard (or setting it to "false") and specifying default="true" for the new default leaderboard.

The position attribute determines the order in which the leaderboards are presented to users. You can change the order on the app’s Game Center page or by sending a metadata update.

Note that once a leaderboard is available to the user for any version of your app, it cannot be deleted.

XPath

<leaderboard_id>29.easy</leaderboard_id>

Leaderboard ID (required; up to 100 characters)

A unique identifier for the leaderboard. It can be composed of letters, numbers, underscores (_), and periods (.). This ID is limited to 100 characters. Your Leaderboard ID is a permanent setting and cannot be changed. Note that the Leaderboard ID is equivalent to the “category” in GameKit API.

If the leaderboard is part of a group, prepend the leaderboard ID with the grp. prefix, for example, grp.level1_easy. Note that before sending group leaderboard metadata using the XML feed, you must first set up the group in App Store Connect.

XPath

<reference_name>Leaderboard One</reference_name>

Reference Name (required)

A unique name for the leaderboard. You can use up to 64 characters and it must be unique within the app. This is an internal reference used when searching for the leaderboard within App Store Connect. It is not displayed on the App Store.

XPath

<aggregate_parent_leaderboard>other_leaderboard_id</aggregate_parent_leaderboard>

Aggregate Parent Leaderboard (optional)

Identifies the aggregate parent leaderboard, if any. An aggregate parent leaderboard (also referred to as combined leaderboard in App Store Connect) joins and ranks together the players from multiple single leaderboards. You must have at least two single leaderboards before you can create an aggregate parent leaderboard, and the leaderboards cannot be combined unless they have the same score format and sort order.

You can create the leaderboards and their aggregate parent leaderboard in the same XML feed, as long as the score format and sort order are the same. You could alternatively set up the parent leaderboard in App Store Connect or in a previous XML delivery.

XPath

<sort_ascending>true</sort_ascending>

Sort (required)

Setting the value to true sorts the scores on the leaderboard from low to high; the lowest scores will be displayed first. Must be set to true or false in English. If you do not supply the <sort_ascending> tag, the value is false by default and the leaderboard scores will be displayed from high to low.

For example, a racing game that records scores as the time required to complete a track would rank scores in ascending order; the lowest score (fastest time) is the best score. A game that measures scores in the amount of wealth earned would choose descending order (setting <sort_ascending> to false). The best score is always displayed at the top of the list.

Note that you cannot change the sort order after the app has gone live.

XPath

<score_range_min>0</score_range_min>

Score Range Minimum (optional)

Defines the minimum score in the range using 64-bit signed integers. The values must be between the long min (-2^63) and long max (2^63 - 1). Any scores outside of this range will be deleted. Score range minimum and maximum values are optional, but if they are added then both values must be set and they must not be equal.

See the tag <formatter_type> (below) to set the score format (for example, time, points, or money).

XPath

<score_range_max>1000</score_range_max>

Score Range Maximum (optional)

Defines the maximum score in the range using 64-bit signed integers. The values must be between the long min (-2^63) and long max (2^63 - 1). Any scores outside of this range will be deleted. Score range minimum and maximum values are optional, but if they are added then both values must be set and they must not be equal.

See the tag <formatter_type> (below) to set the score format (for example, time, points, or money).

XPath

<locales>

  <locale name="en-US"/>

Locale Name (required)

Provides a mechanism to supply localizations of the leaderboard title, score suffix, score format, and leaderboard image. If your app is available in multiple countries, you should localize the leaderboards for each country. If the leaderboard is new, you must supply localizations for at least one locale. If you are delivering a metadata update, and you are not modifying locale information, you can omit the <locales> block and <locale> tag(s).

The locale indicates both the language and the optional, specific region where the language is spoken. To specify a locale, use a dash character to combine a language with a region subtag. For example, the locale for English-language speakers in Great Britain is en-GB, while the locale for English-speaking residents of the United States is en-US. We recommend providing the region only when it adds useful information. See Language Codes for a list of languages supported for Game Center.

Note: To remove a locale, use the remove attribute, for example, <locale name="fr-FR" remove="true"/>. You can't remove the last remaining locale; you must have at least one locale.

XPath

<title>Leaderboard One</title>

Localized Title (required)

The localized title of the leaderboard in the specified <locale> language as you would like it to appear in Game Center. The title must be at least 2 characters but no more than 30.

XPath

<formatter_suffix>Points</formatter_suffix>

Score Format Suffix (optional)

Specifies the plural suffix to use for the score in the specified <locale> language as it will appear to Game Center users. This will be added to the end of scores, in the plural form, displayed on your leaderboard. This is useful for clarifying the type of score your app uses.

For example, a game might choose Integer as the formatting type and “ point” and “ points” as the English localization for singular and plural values of that score. For example, if you reported a score of 10, the score would be formatted as “10 points”. Other games might use the same formatting type, but provide different localized strings (“ laps”, “ coins”).

Note: A leading space is not added to the suffix by default. If you want a leading space after the value, you must add it when you define your suffixes, for example, “ laps” or “ points”.

XPath

<formatter_suffix_singular>Point</formatter_suffix_singular>

Score Format Suffix Singular (optional)

Specifies the singular suffix to use for the score in the specified <locale> language as it will appear to Game Center users. This will be added to the end of scores, in the singular form, displayed on your leaderboard. This is useful for clarifying the type of score your app uses.

The languages supported for localizations of <formatter_suffix_singular> are:

  • Dutch: nl

  • English (United Kingdom): en-GB

  • English (United States): en-US

  • German (Germany): de

  • Italian: it

  • Portuguese (Portugal): pt-PT

  • Spanish (Spain): es-ES

  • Swedish: sv

XPath

<formatter_type>INTEGER_COMMA_SEPARATOR</formatter_type>

Score Format Type (required)

Indicates the type of format in which you want scores for this app to be expressed in your leaderboard—integer, fixed point, elapsed time, or money. This will determine how your scores are displayed on your leaderboard for the specified language. For example, if your app is scored with money, you may want to specify different types of money based on the language you select. See Supported Formats for Score Format Type for a list of accepted score formats. Note that the score format type cannot be changed after the app has gone live.

XPath

<leaderboard_image>

 <file_name>leaderboard1_image.png</file_name>

 <size>286243</size>

 <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum>

</leaderboard_image>

Localized Image (required if <locale> is new)

Delivers a localized image that represents the leaderboard. The image must be JPEG (.jpg or .jpeg) or PNG (.png) in RGB color mode and must be 512 x 512 pixels or 1024 x 1024 pixels.

Important: Do not scale up the image if it is smaller than the minimum required size.

File Name (required)

The name of the image. File names are case sensitive and spaces are not allowed.

File Size (required)

The size in bytes of the image file. Do not include any commas nor period delimiters.

Checksum (required)

The MD5 checksum of the image file. See the Checksums section for more information.

  </locale>

 </locales>

</leaderboard>

XPath

<leaderboard remove="true">

  <leaderboard_id>29.hard</leaderboard_id>

</leaderboard>

Leaderboard (optional)

To remove a leaderboard, include the <leaderboard> block, set the attribute remove to "true", and indicate the Leaderboard ID to remove. Note that you cannot remove a leaderboard after it has gone live.

     </leaderboards>

    </game_center>

   </software_metadata>

  </software>

</package>

Supported Formats for Score Format Type

Integer

INTEGER_COMMA_SEPARATOR

INTEGER_DECIMAL_SEPARATOR

Fixed Point - To 1 Decimal

FIXED_POINT_1_PLACE_WITH_COMMA_SEPARATOR

FIXED_POINT_1_PLACE_WITH_DECIMAL_SEPARATOR

Fixed Point - To 2 Decimals

FIXED_POINT_2_PLACE_WITH_COMMA_SEPARATOR

FIXED_POINT_2_PLACE_WITH_DECIMAL_SEPARATOR

Fixed Point - To 3 Decimals

FIXED_POINT_3_PLACE_WITH_COMMA_SEPARATOR

FIXED_POINT_3_PLACE_WITH_DECIMAL_SEPARATOR

Elapsed Time - To the Minute

ELAPSED_TIME_TO_MINUTE

Elapsed Time - To the Second

ELAPSED_TIME_TO_SECOND

Elapsed Time - To the Hundredth of a Second

ELAPSED_TIME_TO_HUNDREDTH_OF_SECOND

Money - Whole Numbers

MONEY_DOLLAR_WHOLE_WITH_COMMA_SEPARATOR

MONEY_EURO_WHOLE_WITH_DECIMAL_SEPARATOR

MONEY_EURO_WHOLE_WITH_SPACE_SEPARATOR

MONEY_POUND_WHOLE_WITH_COMMA_SEPARATOR

MONEY_KR_WHOLE_WITH_COMMA_SEPARATOR

MONEY_FR_WHOLE_WITH_SPACE_SEPARATOR

MONEY_YEN_WHOLE_WITH_COMMA_SEPARATOR

Money - 2 Decimals

MONEY_DOLLAR_2DECIMALS_WITH_COMMA_SEPARATOR

MONEY_EURO_2DECIMALS_WITH_DECIMAL_SEPARATOR

MONEY_EURO_2DECIMALSE_WITH_SPACE_SEPARATOR

MONEY_POUND_2DECIMALS_WITH_COMMA_SEPARATOR

MONEY_KR_2DECIMALS_WITH_COMMA_SEPARATOR

MONEY_FR_2DECIMALS_WITH_SPACE_SEPARATOR

Language Codes

The table below lists the languages supported for Game Center that can be used with the <locale> tag.

As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries. For example, there is generally not a need to distinguish between Japanese as used in one country versus another, so you should use only the language code subtag (ja) instead of the language code and region subtags (ja-JP). In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. This identifies both the language and the specific location where the language is used. For English with American spelling, use en-US; for English with British spelling, use en-GB.

The language codes are formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646 (https://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: https://www.w3.org/International/articles/language-tags/.

Description

RFC 5646 Language Code

Supported for Game Center

Arabic

ar-SA

Chinese (Simplified)

zh-Hans

Chinese (Traditional)

zh-Hant

Danish

da

Dutch

nl-NL

English (Australia)

en-AU

English (Canada)

en-CA

English (United Kingdom)

en-GB

English (United States)

en-US

Finnish

fi

French (Canada)

fr-CA

French (France)

fr-FR

German

de-DE

Greek

el

Hindi

hi

Indonesian

id

Italian

it

Japanese

ja

Korean

ko

Malay

ms

Norwegian

no

Portuguese (Brazil)

pt-BR

Portuguese (Portugal)

pt-PT

Russian

ru

Spanish (Mexico)

es-MX

Spanish (Spain)

es-ES

Swedish

sv

Thai

th

Turkish

tr

Vietnamese

vi

Frequently Encountered Issues

Accented characters such as é and ü don’t appear correctly in my titles and descriptions.

Make sure you are correctly encoding your metadata in UTF-8. You can use one of the XML Metadata Production tools listed in the Helpful Tools section. There is an XML tool called xmllint that will help identify problems with your XML encodings. You can also try previewing your XML in a browser that renders XML trees such as Firefox.

How do I create a checksum for my files?

Apple accepts file checksums using the industry standard MD5 message digest. There are a variety of tools available to produce an MD5 checksum. See the tools listed in Helpful Tools.

I’m not familiar with XML. Where can I find a general tutorial for XML?

W3Schools

Tutorials Point

XML: A Beginner’s Guide by Dave Mercer

https://www.w3schools.com/xml/

https://www.tutorialspoint.com/xml/

https://www.amazon.com/

Some letters in XML have to be rewritten, what is that about? What’s wrong with my ampersand? My XML isn’t valid!

XML uses a small set of characters to denote structure in the document. If you need to use these characters within content in your XML file, you need to let the XML file know that the characters are not being used as structure by "escaping" them. For example the letters < and > designate an element tag marker, so if you have a value of "9 > 0" in your XML, you need to escape the greater than character with a set of characters called an entity. The entity for greater than ">" is "&gt;", thus making your previous statement "9 &gt; 0". If you cannot rewrite these characters, see the next section regarding using a Character Data (CDATA) block.

Here are the characters that need to be escaped, and their equivalent entities:

Character

Escaped Equivalent

>

&gt;

<

&lt;

&

&amp;

I cannot rewrite my characters. Is there another option? What is CDATA?

XML does offer another solution when rewriting reserved characters is not possible. Element text may be enclosed in a special structure called a character data block CDATA. In a CDATA block, the <, >, and & characters are allowed; the only thing not allowed is the CDATA block closing sequence “]]>” which is unlikely to occur in your text.

Here’s an example using entity escaping:

<description>If 9 &gt; 0, then take 0 &amp; 9.</description>

And here is an example using a CDATA block:

<description><![CDATA[if 9 > 0, then take 0 & 9. ]]></description>

Both of these examples are correct and acceptable. For further explanation, see https://www.w3schools.com/xml/dom_cdatasection.asp. Note the characters must still be encoded in UTF-8.

I don’t have a value for an element that is shown in the XML.

For elements marked optional for which you have no value, Apple requires that you remove the tag entirely from the XML rather than leaving the element empty. If the element is marked required, you may not omit the element.

Helpful Tools

These products are neither endorsed nor supported by Apple.

XML Metadata Production

Oxygen XML Editor

Mac, Windows, Linux

https://www.oxygenxml.com/

Exchanger XML Editor

Mac, Windows, Linux

https://code.google.com/archive/p/exchangerxml/downloads

Altova XML Spy

Windows

https://www.altova.com/

XML Debugging

Firefox

Mac, Windows, Linux

https://www.mozilla.com/firefox/

xmllint

macOS, BSD

https://developer.apple.com/

MD5 Checksum

md5

macOS, BSD

https://developer.apple.com/

md5sum

Windows

MD5 Win Verifier

Revision History

Previous Spec Revisions

The following table lists the previously-released specs and the revisions:

Date/Version

Changes Made

September 22, 2021 - Version 5.12

Screenshot requirements have been updated for the new Apple Watch Series 7.

August 31, 2020 - Version 5.11

Added new tags for promotional offers for subscription discounts. Updated languages. Added a tag for privacy policy for tvOS apps. Updated schema number. Added clarifications. Added Arabic, English (Australia), English (Canada), French (Canada), Hindi, and Spanish (Mexico) support for Game Center. Added a link to generate the list of available territories.

October 31, 2018 - Version 5.10.1

Changes to screenshot and app previews size requirements.

September 19, 2018 - Version 5.10

Changes to screenshot and app previews size requirements. App subtitles and app previews are now supported for macOS Apps. Privacy policy is required for all apps. Delivery of up to 10 screenshots now supported for macOS Apps. Corrections to field lengths.

February 21, 2018 - Version 5.9.1

Changes to screenshot delivery. Made editorial and organizational changes.

January 31, 2018 - Version 5.9

Added new tags to specify app previews. Updated the schema version number. Made minor corrections throughout.

November 15, 2017 - Version 5.8

Added new subscription pricing options. Updated screenshot requirements and added a new value for use with the display_target attribute. Updated the schema version number.

October 18, 2017 - Version 5.7

Updated screenshot requirements and added a new value for use with the display_target attribute. Updated the schema version number.

June 5, 2017 - Version 5.6

Added two new tags for adding app subtitles (<subtitle>) and promotional text (<promotional_text>).

March 1, 2017 - Version 5.5.1

Free trial and bonus durations are no longer limited based on subscription durations. New durations added.

November 30, 2016 - Version 5.5

Changes to auto-renewable subscriptions. Changes to length of app titles. screenshots must be delivered before the app can be submitted to App Review. Tags added, changed, and deprecated to support new subscriptions structure.

September 8, 2016 - Version 5.4.3

Changes to auto-renewable subscriptions. Corrections to language codes.

July 21, 2016 - Version 5.4.2

Changes made to screenshot delivery.

March 23, 2016 - Version 5.4.1

Changes made to screenshot delivery.

December 4, 2015 - Version 5.4

Added a new attribute to support apps and universal purchase for different Apple devices. Added new attributes for display target for Apple TV and Apple Watch. Explained how to request and download catalog reports. Updated the schema version number. Replaced the listed sizes for screenshots with a link online where the sizes are updated more frequently.

April 9, 2014 - Version 5.2

Changed the version number of this specification from 5.1 to 5.2 to keep the version number in sync with the new schema version.

October 1, 2013 - Version 5.1.1

The tag <allow_volume_discounts> can now be used with apps developed for the Mac.

June 9, 2013 - Version 5.1

Added ability to deliver app metadata for an existing app set up using iTunes Connect. Content packages for non-consumable in-app purchases can now be delivered through the feed. Added interval pricing validations. Reorganized the spec based on the new features.

October 23, 2012 - Version 5.0

First release of the App Metadata Specification. Note that even though this is the first release of the spec, the version number is 5.0 to match the current version of the schema.

Changes in App Metadata Specification 5.12

Screenshots

Screenshot requirements have been updated for the new Apple Watch Series 7. A new value has been added for use with the display_target attribute on a <software_screenshot> tag: iOS-Apple-Watch-Series-7. The resolution of the screenshot image for the Apple Watch Series 7 should be 396 x 484 pixels.

Changes in App Metadata Specification 5.11

In-App Purchases: Subscription Discounts

Introductory offers for new customers: You use introductory subscription offers to provide discounted pricing for new customers during the introductory phase of your offer. Previously, you could specify two modes (using the <mode> tag): pay as you go and pay up front. You can now specify a free introductory subscription mode. With the free mode, customers access the subscription for free for a selected duration. Their subscription begins immediately, but they won’t be billed until the free trial is over.

This introductory free mode (<mode>free</mode>) replaces the <type>free-trial</type> previously used within an <offer> block. Using the free-trial type is still valid, but Apple recommends that you begin to use the introductory free mode in preparation for the time when free-trial is deprecated.

Promotional offers for existing customers: For existing or previously subscribed customers, you can offer a discounted price for a specific duration. These offers can help win back subscribers who have canceled their subscriptions or promote an upgrade to another subscription at a special price. Once the promotional period ends, the subscription auto-renews at the standard price. Promotional offer options (specified using the <mode> tag) include pay as you go, pay up front, and free.

Introductory and promotional offers are available for customers running iOS 10, tvOS 10, and macOS 10.12.6 and later. To read more and see a comparison of promotional and introductory offers, see Promoting Your Subscriptions with New Offers.

In-App Purchases: Subscription Upload

When uploading new auto-renewable in-app-purchases, Apple recommends limiting a delivery to 40 subscriptions per upload. For example, if you want to add 200 new subscriptions, you should upload 5 packages, each with 40 subscriptions. Limiting the number of new subscriptions ensures a better upload experience. Note that this recommended limit applies to new subscriptions; you can include any number of existing subscriptions.

In-App Purchases: Clarifications

To remove a locale for an in-app purchase that was previously delivered, include the <locales> block in a new delivery and omit the locale you want to remove.

Before submitting a new in-app purchase for review, you must include a <price> block for all territories. To generate a list of available territories, see List Territories.

Privacy Policy Text

If you are delivering a tvOS app, you must deliver the text of your policy using the tag <privacy_policy_text>. This tag is required for tvOS apps and it serves the same role as <privacy_url> used for other platforms. If your app works on tvOS and iOS, you must submit both the <privacy_policy_text> tag and the <privacy_url> tag. Note that you cannot remove your privacy policy text for tvOS apps.

Languages

The language code table has been updated to include all supported languages. Arabic (ar-SA), English (Australia) (en-AU), English (Canada) (en-CA), French (Canada) (fr-CA), Hindi (hi), and Spanish (Mexico) (es-MX) have been added for Game Center. See Language Codes for more information.

Schema Version

The schema version (5.11) has changed. The <package> tag version attribute has been changed throughout the specification to software5.11:

<package xmlns="http://apple.com/itunes/importer" version="software5.11">

Tag Changes

Added

<promotional_offers><promotional_offer>

<product_code>

<reference_name>

Changed

free can be used as a value with the <mode> tag within an <offers> block

<prices> and <price> can be used with <promotional_offer>

Changes in App Metadata Specification 5.10.1

Screenshots

Screenshot requirements have been updated for the new generation of iPad. You can now upload screenshots for the new 12.9-inch iPad Pro and 11-inch iPad Pro. Assets for the 12.9-inch iPad Pro (3rd generation) will be automatically resized for the 11-inch iPad Pro if you don’t deliver 11-inch iPad Pro screenshots. These assets are optional and can't be used for other iPad devices. New values have been added for use with the display_target attribute on a <software_screenshot> tag: iOS-iPad-Pro-2018 and iOS-iPad-Pro-11-in.

Starting March 2019, all new apps and app updates for iPad, including universal apps, will require screenshots for the 12.9-inch iPad Pro (3rd generation). They must also be built with the new iOS 12 SDK and support the latest devices.

If your app is the same across multiple device sizes and localizations, provide just the highest resolution screenshot set for each device type. For iPad, screenshots for the 12.9-inch iPad Pro (2nd generation) are required. Screenshots for the 12.9-inch iPad Pro (3rd generation) are optional and also display with rounded corners. These screenshots will scale down for the 11-inch iPad Pro, but not for older iPad devices.

To view the up-to-date screenshot size requirements, click this link: Screenshot specifications.

App Previews

App preview requirements have been updated for the new generation of iPad. You can now upload app previews for the new 12.9-inch iPad Pro and 11-inch iPad Pro. New values have been added for use with the display_target attribute on an <app_preview> tag: iOS-iPad-Pro-2018 and iOS-iPad-Pro-11-in.

If your app is the same across multiple device sizes and localizations, provide just the highest resolution app preview set for each device type. For iPad, app previews for the 12.9-inch iPad Pro (2nd generation) are required. App previews for the 12.9-inch iPad Pro (3rd generation) are optional and also display with rounded corners. These app previews will scale down for the 11-inch iPad Pro, but not for older iPad devices.

For app preview requirements and video specifications, see App preview specifications.

Schema Version

The version number 5.10.1 is for the specification revision; the schema version (5.10) has not changed. The <package> tag version attribute is still software5.10:

<package xmlns="http://apple.com/itunes/importer" version="software5.10">

Tag Changes

Added

iOS-iPad-Pro-2018 and iOS-iPad-Pro-11-in as new values for display_target for app previews

iOS-iPad-Pro-2018 and iOS-iPad-Pro-11-in as new values for display_target for screenshots

Changes in App Metadata Specification 5.10

Screenshots

Screenshot requirements have been updated for the new generation of iPhone. You can now upload screenshots for the new iPhone XS Max. These assets will be automatically resized for iPhone X and later (iPhone XR, iPhone XS, and iPhone X). Upload screenshots as they are, with no modifications. The rounded corners will be automatically applied after upload. A new value has been added for use with the display_target attribute on a <software_screenshot> tag: iOS-6.5-in. Starting March 2019, all new apps and app updates for iPhone, including universal apps, will require iPhone XS Max screenshots. They must also be built with the iOS 12 SDK and support the latest devices.

If your iOS app contains a watchOS app, you can provide a screenshot for the new Apple Watch using the display_target attribute on a <software_screenshot> tag: iOS-Apple-Watch-Series-4.

To view the up-to-date screenshot size requirements, click this link: Screenshot specifications.

You can now deliver up to ten screenshots for macOS Apps (previously limited to five).

App Previews

App preview requirements have been updated for the new generation of iPhone. You can now upload app previews for the new iPhone XS Max. These assets will be automatically resized for iPhone X and later. A new value has been added for use with the display_target attribute on a <app_preview> tag: iOS-6.5-in.

Previously, app previews displayed on the App Store for iPhone and iPad only. App previews are now supported for macOS Apps and appear on the app’s product page on the Mac App Store on macOS 10.14 or later. The accepted resolution is 1920 x 1080 pixels (16:9 aspect ratio).

For app preview requirements and video specifications, see App preview specifications.

App Subtitles

Previously, app subtitles displayed on the App Store for iPhone and iPad only. App subtitles are now supported for macOS Apps and appear under your app’s name on the Mac App Store on macOS 10.14 or later. App subtitles are optional and can be localized. Subtitles are limited to 30 characters.

Privacy Policy

A URL link to your privacy policy is now required for all apps. You deliver the link using the <privacy_url> tag. Previously, the privacy policy URL was required only for apps that included auto-renewable subscription in-app purchases.

Schema Version

The <package> tag version attribute has been updated in all examples to 5.10:

<package xmlns="http://apple.com/itunes/importer" version="software5.10">

Corrections

The character length for titles has been corrected from 50 to 30. The character length for in-app purchase descriptions has changed from 255 bytes to 45 characters and the character length for reference name has changed from 255 bytes to 64 characters.

Tag Changes

Added

Mac and iOS-6.5-in as new values for display_target for app previews

iOS-6.5-in and iOS-Apple-Watch-Series-4 as new values for display_target for screenshots

Changes in App Metadata Specification 5.9.1

Screenshots

The number of screenshots that can be delivered has changed. You can now deliver up to ten screenshots for iOS, tvOS, and watchOS and five for macOS for each locale.

Editorial Changes

To simplify updates where information appears in other documentation, several sections have been removed from this specification. Instead, you will see links to the information that is found in the other documents. In addition, some links have been updated.

Changes in App Metadata Specification 5.9

App Previews

App previews demonstrate the features, functionality, and user interface of your app using footage captured on the device. You can have up to three app previews for each display_target within each <locale> your app supports, and each preview can be up to 30 seconds long. App previews are optional, and when supplied, they appear before screenshots on the App Store.

You deliver the app previews using the new <app_preview> tag within the localized <app_previews> block and you set the display target and provide data file information. You can also select a frame within the preview to use as the poster frame image by specifying a timecode with the <preview_image_time> tag. App previews will autoplay on iOS 11 or later; for iOS 10.3 or earlier, the poster frame image appears.

For app preview requirements and video specifications, see App preview specifications.

Schema Version

The <package> tag version attribute has been updated in all examples to 5.9:

<package xmlns="http://apple.com/itunes/importer" version="software5.9">

Corrections

Links to other documents have been updated or added throughout the specification.

Tag Changes

Added

<app_previews> <app_preview>

<preview_image_time> used within the <app_preview> block

Changes in App Metadata Specification 5.8

Introductory Pricing for Auto-Renewable Subscriptions

You can offer new customers a discounted introductory price for your auto-renewable subscriptions on the App Store on iOS, tvOS, and macOS. Several tags have been added to specify your introductory prices. You can offer pay as you go, pay up front, or free trial pricing and free trial.

  • Pay As You Go: Customers pay an introductory price for each billing period for a selected duration (for example, $1.99 per month for 3 months for a subscription with a standard price of $9.99).

  • Pay Up Front: Customers pay a one-time introductory price for a selected duration (for example, $1.99 for 2 months for a subscription with a standard price of $9.99).

  • Free Trial: Customers access the subscription for free for a selected duration.

You deliver the introductory prices within the new <offers> block and you can set the duration, number of periods, start date, and end date.

As of the 5.8 version, the <free_trial_duration> tag is deprecated, however the older specifications (5.7 and less) will still support <free_trial_duration>. If you perform a metadata lookup, the <free_trial_duration> tag will not be returned. If you use the newer 5.8 specification, you must use the new <offers> structure; using the <free_trial_duration> tag will cause an error.

Screenshots

Screenshot requirements have been updated for the iPad Pro. A new value has been added for use with the display_target attribute on a <software_screenshot> tag: iOS-iPad-Pro-10.5-in.

To view the up-to-date screenshot size requirements, click this link: Screenshot specifications.

Schema Version

The <package> tag version attribute has been updated in all examples to 5.8:

<package xmlns="http://apple.com/itunes/importer" version="software5.8">

Tag Changes

Added

iOS-iPad-Pro-10.5-in as a new value for display_target for screenshots

<offers> <offer>

<type>, <territory>, <duration>, <number_of_periods>, <start_date>, and <end_date> used within the <offer> block

<tier> and <mode> used within the <offer> block for introductory offers only

Deprecated

<free_trial_duration> (use the new <offers> structure instead using the free-trial)

Changes in App Metadata Specification 5.7

Screenshots

Screenshot requirements have been updated due to the iPhone X release. A new value has been added for use with the display_target attribute on a <software_screenshot> tag: iOS-5.8-in.

To view the up-to-date screenshot size requirements, click this link: Screenshot specifications.

Schema Version

The <package> tag version attribute has been updated in all examples to 5.7:

<package xmlns="http://apple.com/itunes/importer" version="software5.7">

Tag Changes

Added

iOS-5.8-in as a new value for display_target for screenshots

Changes in App Metadata Specification 5.6

App Subtitle

The new <subtitle> tag provides a summary of your app that will appear under your app’s name on the App Store for customers with devices running iOS 11 or later. This can’t be longer than 30 characters. Note that the subtitle appears for universal apps in the iOS App Store only; the subtitle is not supported on macOS apps.

Promotional Text

The new <promotional_text> tag lets you inform your App Store visitors of any current app features without requiring an updated submission. This text will appear above your description on the App Store for customers with devices running iOS 11 or later. This property can't be longer than 170 characters.

Tag Changes

Added

<subtitle>

<promotional_text>

Changes in App Metadata Specification 5.5.1

In-App Purchases: Subscriptions

Free trial and bonus durations are no longer limited based on subscription durations. You can use any of the durations listed below. In addition, new free trial and bonus durations have been added: 3 days and 14 days.

  • 3 Days

  • 7 Days

  • 14 Days

  • 1 Month

  • 2 Months

  • 3 Months

Changes in App Metadata Specification 5.5

Auto-Renewable Subscriptions: New Structure

The XML structure for delivering in-app purchase, auto-renewable subscriptions has changed. All auto-renewable subscriptions are required to be part of a group (<subscription_group>), which was previously referred to as a <family>. The new structure allows you to set up different services with the same or different durations and different levels. To provide levels, in-app purchases within a subscription group must be ranked (using the <rank> tag) according to product or service levels. For example, you could have an app that used in-app purchases to allow customers to purchase different levels of TV service. You could offer a basic level that includes a minimum number of programs (rank 3); a mid-level that includes the basic programs and one premium channel (rank 2); and the highest level that includes the basic programs and two premium channels (rank 1).

Auto-Renewable Subscriptions: Pricing

For auto-renewable subscriptions, you deliver pricing though the feed using the new <prices> block (which replaces the <products> block that formerly contained pricing information). New tags have been added to accommodate new pricing structures and to manage pricing changes. You can select from 200 price tiers per territory. Make sure you have downloaded the current list of available subscription price tiers from iTunes Connect. You can download the subscription price tiers for an auto-renewable subscription in the Subscription Prices section (click All Prices and Currencies).

For initial pricing, you must include all 155 territories. On subsequent deliveries, you can change pricing using the <start_date> tag and specifying the new price tier. In addition, you can increase the price of an auto-renewable subscription for new customers while keeping existing subscribers at their current price (referred to as “price preservation”). To do this, use the <keep_previous_tier> tag set to true; if you omit the tag, the value is assumed to be true.

App Title

Previously, the app title could be up to 255 bytes in length. In some cases, developers used the longer titles to include descriptions and terms not directly related to the app in an attempt to improve search results. These long names are not fully displayed on the App Store and provide no user value. For any new apps and updates, the app title must be no more than 30 characters.

Software Screenshots

Previous versions of this specification indicated that screenshots must be delivered either on initial delivery or with a metadata update before the app can go live. However, screenshots must be delivered before the app can be submitted to App Review.

Tag Changes

Added

<app_name>

<rank>

<prices>

verification_code as an attribute of <prices>

<price>

<start_date>

<tier>

<keep_previous_tier>

Changed

<family> has been renamed to <subscription_group>

<cleared_for_sale> for auto-renewable IAPs only is now delivered within the <in_app_purchase> block, not the <products> <product> block

<locales> are now delivered within the <in_app_purchase> block for auto-renewable in-app purchases (same as other in-app purchases)

<reference_name>is now delivered within the <in_app_purchase> block for auto-renewable in-app purchases (same as other in-app purchases)

<review_screenshot> is now delivered within the <in_app_purchase> block; not the now deprecated <family> block

<review_note> is now delivered within the <in_app_purchase> block; not the now deprecated <family> block

Adding <locales>, <reference_name>, <review_screenshot>, and <review_note> tags align auto-renewable IAPs to with the other IAP types for consistency - notable exceptions being the <cleared_for_sale>, <rank>, and <prices> tags

Deprecated

free-subscription as an attribute of <type>

<publication_name>

Free subscriptions

Changes in App Metadata Specification 5.4.3

Auto-Renewable Subscriptions

Currently, auto-renewable subscriptions are not supported. You cannot add new auto-renewable subscriptions or edit existing auto-renewable subscriptions. You can do a metadata-lookup, but any existing subscription families will be empty; you will see a comment indicating that it is currently not supported. The sections Auto-Renewable In-App Purchase Metadata Example for a metadata XML example and Auto-Renewable In-App Purchase Metadata Annotated have been removed from this specification. Support for auto-renewable subscriptions will be restored in a later release.

Language Codes

Changes have been made to language codes: cmn-Hant has been changed to zh-Hant, cmn-Hans has changed to zh-Hans, nl has been changed to nl-NL, and de has been changed to de-DE.

Tag Changes

Currently not supported

auto-renewable as an attribute of type

<family>

Changes in App Metadata Specification 5.4.2

Screenshots

When you upload screenshots using iTunes Connect, you can indicate if you want to use a 5.5-inch iPhone screenshot for all other iPhone display sizes and localizations. The App Store resizes the screenshot for the different display sizes automatically. If, after uploading the screenshot and setting the option in iTunes Connect, you then deliver screenshots through the feed and specify a display target (for example, <software_screenshot display_target="iOS-4-in" position="1">), the option to use the 5.5-inch screenshot is overridden for that display size.

You can also streamline your XML metadata by delivering one screenshot (instead of separate screenshots in the various sizes) and have the App Store use it for each iPhone display size and localization. To take advantage of this feature, deliver a 5.5-inch iPhone screenshot with the display_target attribute set to iOS-5.5-in. If you previously added screenshots for other display sizes and localizations, you can select to use the 5.5-inch screenshot instead in iTunes Connect. Note that if your app doesn't look or behave identically in all languages and on all supported iPhone devices, you should deliver custom screenshots for each display size and localization.

Changes in App Metadata Specification 5.4.1

Screenshots

Previously, screenshots were required on initial delivery. Screenshots are now optional on initial delivery, but must be delivered with a metadata update before the app can be submitted to App Review. On initial delivery, you can omit the <software_screenshots> block. Later, send a metadata update that includes the <software_screenshots> block and deliver each screenshot in its own <software_screenshot> tag. If you include the <software_screenshots> tag in a metadata update, you must deliver all screenshots; previously delivered screenshots that are not included in the metadata update will be removed. If you deliver an empty tag (<software_screenshots></software_screenshots> or <software_screenshots/>), all existing screenshots will be removed (including any screenshots that may have been uploaded using iTunes Connect).

Changes in App Metadata Specification 5.4

Platform Support

To support apps for different Apple platforms, a new attribute for the <software_metadata> tag has been added to specify the platform associated with the current XML delivery. The attribute is named app_platform and the allowed values are: ios, osx, and appletvos. By specifying the platform, you can deliver the metadata for a platform-specific app. You can also deliver a universal purchase (see below) and customize the description, screenshots, keywords, and what’s new text for each platform. Use of the attribute requires software schema version 5.4.

In addition to the app_platform attribute, the display_target attribute used with the <software_screenshot> tag has a new value to indicate Apple TV (display_target="appletvos") and Apple Watch (display_target="iOS-Apple-Watch"), and the iPad Pro (display_target="iOS-iPad-Pro").

Universal Purchase

Universal purchase allows your customers to use your app on multiple platforms with a single purchase. Although the apps for each device are distinct binaries, you can create a universal purchase that bundles the apps. For example, the customer purchases an app once, and gets the iOS version for their iOS devices and a tvOS version for Apple TV.

To create a universal purchase via an XML delivery, you can use the app_platform attribute with a metadata update on an existing app. To set up the universal purchase, both apps must be associated with the same Apple ID. For example, if the existing app is for iOS and you specify tvOS with the attribute, the App Store automatically creates a version for Apple TV. The existing metadata from the current platform version is used for the new platform and you can edit the description, screenshots, keywords, and what’s new text for the new platform as needed. Note that the different platforms can have different version numbers and build strings.

In the universal purchase, when you make changes to the app name (<title>), privacy URL, or locales via XML, those changes are also automatically made to the other platforms.

Schema Version

The <package> tag version attribute has been updated in all examples to 5.4:

<package xmlns="http://apple.com/itunes/importer" version="software5.4">

The previous release of this specification was 5.2. The schema has since been updated to 5.3 and now 5.4, however there was no release of this specification for 5.3.

Catalog Reports

Catalog reports provide information on your apps, in-app purchases, and Game Center leaderboards and achievements. You can request each type of catalog report once per 24-hour period. Reports are available for 30 days after they are posted and are formatted as tab-delimited text files. You can request and download catalog reports using the requestReports mode in Transporter. See Catalog Reports for more information.

Screenshots

To view the up-to-date screenshot size requirements, click this link: Screenshot specifications.

Tag Changes

Added

app_platform attribute with allowed values: ios, osx, and appletvos

appletvos, iOS-Apple-Watch, and iOS-iPad-Pro as new values for display_target for screenshots

Changes in App Metadata Specification 5.2

Schema Version

The version number of this specification has changed from 5.1 to 5.2 to keep the version number in sync with the new schema version. In addition, the <package> tag version attribute has been updated in all examples to 5.2:

<package xmlns="http://apple.com/itunes/importer" version="software5.2">

No other changes have been made to this document; the new schema version was created due to major changes in other specifications.

Changes in App Metadata Specification 5.1.1

Allow Volume Discounts

Previously, the tag to indicate that an app is eligible for discounts for educational institutions was available for iOS only. The tag <allow_volume_discounts> can now be used with apps developed for the Mac.

Changes in App Metadata Specification 5.1

App Metadata

You can now deliver app metadata for an existing app set up using iTunes Connect. App metadata includes localized titles, descriptions, what’s new text, keywords, and screenshots, as well as territory rights, pricing, and availability.

Hosted Content

Hosted in-app purchases can be delivered via an XML content package through the feed. The product type for hosted content must be non-consumable. Customers purchase non-consumable products only once. Services that do not expire or decrease with use, such as a new race track for a game app, are usually implemented as non-consumables. The non-consumable product is provided to all devices associated with the customer’s iTunes account. Available for iOS and macOS applications.

Interval Pricing

New validations have been added for interval pricing. Packages that do not adhere to the requirements will be blocked.

In addition to the validations, the <start_date> of the first interval within the <intervals> block is optional for the first interval.

Corrections/Clarifications

Added the missing closing </description> tag in the example showing how to use CDATA. Clarified the <cleared_for_sale> tag.

Tag Changes

Added

<versions> and <version>

<keywords> and <keyword>

<version_whats_new>

<software_url>

<privacy_url>

<support_url>

<software_screenshots> and <software_screenshot>

<allow_volume_discount>

<has_hosted_content>

in-app-purchase-content as a type attribute for <asset> used for hosted content

Changed

<start_date> of the first interval within the <intervals> block is now optional