Introduction

Overview

This document provides information on delivering app localizations and product information, in-app purchases, and Game Center metadata to your existing apps. For in-app purchases, you provide metadata on the additional features and functionality you sell from within your free or paid iOS and macOS apps. For Game Center, you provide metadata for leaderboards and achievements, as well as providing localizations.

App 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 app product, the app localization screenshots, in-app purchase screenshots, Game Center assets, such as Achievement and Leaderboard images, as well as any optional hosted content files. Each package represents one app product within the App Store. For each app product, you can deliver multiple in-app purchases and Game Center leaderboards and achievements in the same package. Note that an app can have up to 10,000 in-app purchases overall, but no more than 1000 <in_app_purchase> elements can be delivered in a single upload.

Even though the app metadata, in-app purchases, and Game Center leaderboards and achievements are covered in separate chapters, you could deliver them all in one <software_metadata> element for a single app product as shown in Basic App Metadata Example. For more details about delivery, see Package Format.

About This Release

Date/Version

Changes Made

August 5, 2019 - 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.

What’s New 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. See the annotation in Auto-Renewable In-App Purchase Metadata Annotated for more details.

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.

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. 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>

Delivery & Formatting Guidelines

Package Format

You deliver app metadata (which includes localized titles, descriptions, what’s new text, keywords, and app screenshots, as well as provides territory rights, pricing, and availability), review screenshot files, and leaderboard and achievement images in the App Store Package format (.itmsp) through Transporter. Each App Store Package can contain localized app metadata and products for multiple territories, multiple in-app purchases (up to 1000 in a single upload) for a single app, as well as achievements (up to 100) and leaderboards (up to 25).

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

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

  • app screenshots files; for each locale, you must supply at least one screenshot for each supported device

  • associated review screenshot file(s) for in-app purchases (if delivering in-app purchases)

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

  • optional asset file(s) for hosted content

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 both in-app purchases and Game Center achievements and leaderboards and that includes hosted content.

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

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

  • screen-en-US-ipad-1.png, screen-en-US-ipad-2.png, screen-fr-FR-ipad-1.png, screen-fr-FR-ipad-2.png, and so on as needed for each locale/device combination.

  • screenshot-01.png, screenshot-02.png, and so on (review screenshot(s) for each in-app purchase)

  • 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>.

  • com.cyberinteractive.hosted_content.pkg (included if the in-app purchase contains hosted content). Note that the .pkg file is not an executable file; it just contains resources.

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 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.

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/

Basic App Metadata Profile

Overview

The App Metadata profile is used to deliver metadata for your app, the app’s in-app purchases, and Game Center. App metadata includes localized titles, descriptions, what’s new text, keywords, and screenshots, as well as territory rights, pricing and availability. You can also deliver in-app purchases and Game Center metadata in one metadata.xml file.

Note: Currently, you cannot create new apps or app versions through the feed; you must create the app version in App Store Connect as described in the App Store Connect Help. However, you can deliver localized titles, descriptions, what’s new text, keywords, and screenshots, as well as product information to an existing app version.

Basic App Metadata Example

Below is an example metadata.xml file for a fictional game. The example includes in-app purchases and Game Center metadata. To read an overview of in-app purchases and read tag annotations, see In-App Purchase Profile. To read an overview of Game Center and read tag annotations, see Game Center Profile.

<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="software5.11"> <provider>CyberInteractive</provider> <team_id>A9B8C7D6E5</team_id> <software> <vendor_id>CI0009</vendor_id> <software_metadata> <versions> <version string="1.1"> <locales> <locale name="en-US"> <title>Touch Fighter</title> <subtitle>Action-filled combat game</subtitle> <description>Challenging, action-filled combat game with fighter jets and missiles.</description> <promotional_text>On sale for a limited time.</promotional_text> <keywords> <keyword>combat</keyword> <keyword>multi-player</keyword> <keyword>jet fighters</keyword> </keywords> <version_whats_new>Fixed a bug.</version_whats_new> <software_url>http://www.CITouchfighter.com/</software_url> <privacy_url>http://www.CITouchfighter.com/privacy/</privacy_url> <privacy_policy_text>This is an example of privacy policy text for your Apple TV app</privacy_policy_text> <support_url>http://www.CITouchfighter.com/support/</support_url> <app_previews> <app_preview display_target="iOS-6.5-in" position="1"> <preview_image_time format="24/999 1000/nonDrop">00:00:17:01</preview_image_time> <data_file role="source"> <file_name>app_preview.mp4</file_name> <size>33558000</size> <checksum type="md5">cd12fca6b5858985fdbe10a422ade6c3</checksum> </data_file> </app_preview> </app_previews> <software_screenshots> <software_screenshot display_target="iOS-iPad" position="1"> <file_name>screen-en-US-ipad-1.png</file_name> <size>286243</size> <checksum type="md5">3cefb7c5c37f6c868c0f4c46dc16c415</checksum> </software_screenshot> <software_screenshot display_target="iOS-iPad" position="2"> <file_name>screen-en-US-ipad-2.png</file_name> <size>283624</size> <checksum type="md5">c37f6c8683cefb7c5c46dc16c4150f4c</checksum> </software_screenshot> </software_screenshots> </locale> <locale name="fr-FR"> <title>Touch Fighter</title> <subtitle>Rempli d'action jeu de combat</subtitle> <description>Jeu de combat complexe et rempli d'action.</description> <promotional_text>En vente pour un temps limité.</promotional_text> <keywords> <keyword>combat</keyword> <keyword>multi-joueur</keyword> <keyword>chasseur à réaction</keyword> </keywords> <version_whats_new>Bug corrigé.</version_whats_new> <software_url>http://www.CITouchfighter.com/fr/</software_url> <privacy_url>http://www.CITouchfighter.com/fr/privacy/</privacy_url> <support_url>www.CITouchfighter.com/fr/support/</support_url> <app_previews> <app_preview display_target="iOS-5.5-in" position="1"> <data_file role="source"> <file_name>app_preview_fr_FR.mp4</file_name> <size>33558000</size> <checksum type="md5">5e10a428a6bb2ade6c358985fdcd12fc</checksum> </data_file> </app_preview> </app_previews> <software_screenshots> <software_screenshot display_target="iOS-iPad" position="1"> <file_name>screen-fr-FR-ipad-1.png</file_name> <size>286243</size> <checksum type="md5">3cefb7c5c37f6c868c0f4c46dc16c415</checksum> </software_screenshot> <software_screenshot display_target="iOS-iPad" position="2"> <file_name>screen-fr-FR-ipad-2.png</file_name> <size>283624</size> <checksum type="md5">c37f6c8683cefb7c5c46dc16c4150f4c</checksum> </software_screenshot> </software_screenshots> </locale> <locale name="ru-RU" remove="true"/> </locales> </version> </versions> <products> <product> <territory>WW</territory> <sales_start_date>2010-05-25</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>9</wholesale_price_tier> <allow_volume_discount>false</allow_volume_discount> </product> <product> <territory>RU</territory> <cleared_for_sale>false</cleared_for_sale> </product> </products> <in_app_purchases> <in_app_purchase> <product_id>com.cyberinteractive.touchfighter.missiles.10</product_id> <reference_name>10 missiles</reference_name> <type>consumable</type> <products> <product> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>3</wholesale_price_tier> </product> </products> <locales> <locale name="en-US"> <title>10 Missiles</title> <description>This product provides an additional 10 missiles to take you on your way.</description> </locale> </locales> <review_screenshot> <file_name>screenshot-01.png</file_name> <size>286243</size> <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum> </review_screenshot> <review_notes>Some notes for the reviewer.</review_notes> </in_app_purchase> <in_app_purchase remove="true"> <product_id>obsolete_com.cyberinteractive.tf.missiles.15</product_id> </in_app_purchase> </in_app_purchases> <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="ru-RU" 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 App Metadata Annotated

The annotations in this section cover the tags used for delivering the basic app localizations and product information. For annotations on in-app purchases, see Basic In-App Purchase Metadata Annotated and for Game Center annotations, see 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="software5.11">

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="software5.11". 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 shortname given for partner identification. If you do not know your provider shortname, 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 package.

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 the app.

(Optional) You can specify a platform using the app_platform attribute, for example:

<software_metadata app_platform="appletvos">

The attribute indicates that the metadata in this XML delivery applies to that platform. Allowed values for app_platform include: ios, osx, and appletvos.

Note: If you send a metadata update for an existing iOS and you specify appletvos with the attribute, the App Store automatically creates a version for Apple TV.

XPath

<versions>

Versions (optional)

Begins the versions element block. Within the <versions> block, specify the version or versions to which the localizations apply. There are two potential versions (referenced by version number using the <version> tag):

  • “live” applies to the version currently on the App Store.

  • “in-flight” applies to the version that is being or has been submitted, but has not yet gone live.

You can target either one or both versions with localization updates, each within its own <version> block.

Note: If you are not delivering new locales or updating existing locales, you do not need to include the <versions> block.

XPath

<version string="1.1">

Version (required within the <versions> block)

The version of the app for which you are delivering localizations must match either the "live" or the "in-flight" App Store Connect version. You only need to include a <version> tag for the version or versions that you are updating; you can omit the <version> tag for any version that you are not currently updating.

Note: This is the version as set in App Store Connect for the app; not the version of the binary.

XPath

<locales>

  <locale name="en-US">

Locale Name (required when delivering locales)

Provides a mechanism to specify localizations for the app title, description, keywords, and screenshots. At least one locale must be provided for an app in the default language (set up on App Store Connect); once that locale has been provided, either through App Store Connect or through the feed, you do not need to keep delivering it unless you need to make changes.

Keep the following points in mind for locales:

  • When delivering metadata for a version with locales, supply only the locales you are adding, changing, or removing (see the Remove Locale annotation below). You do not need to supply locales that have already been set up or delivered if you are not making changes to them.

  • There must be at least one locale set up and it must be in the default language as set on App Store Connect, but you do not need to supply it in the metadata delivery once it has been set up unless you are updating it.

The locale indicates both the language and the specific region where the language is spoken. To specify a locale, use a dash character to combine a language subtag 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 apps.

Note: When updating existing localizations, send only the locales you are changing; you do not need to redeliver all existing locales.

XPath

<title>Touch Fighter</title>

Title (required)

The title (called Name in App Store Connect) of the app in the specified <locale> language. This title is displayed on the App Store. The title must be at least 2 characters but no more than 30. The title must be unique per locale per software type. For example, you cannot have two iOS apps called Touch Fighter, however you can have one iOS app called Touch Fighter and a macOS app called Touch Fighter. The title is exactly how your app will display on your customer’s device based on their default language settings.

Note: If your tvOS app uses the same app ID as your iOS app as a universal purchase, the apps must share one title. If you are delivering a tvOS app that uses a separate app ID, the title must be a different name from your iOS app title. Do not include the phrases Apple TV, tvOS or ATV in the title of your tvOS app.

XPath

<subtitle>Action-filled combat game</subtitle>

App Subtitle (optional)

The subtitle (called Subtitle in App Store Connect) of the app in the specified <locale> language. The subtitle can’t be longer than 30 characters. Use the <subtitle> tag to provide a summary of your app. The subtitle appears apps on the App Store running iOS 11 or later or macOS 10.14 or later.

Note: If your tvOS app uses the same app ID as your iOS app as a universal purchase, the apps must share one subtitle. If you are delivering a tvOS app that uses a separate app ID, the subtitle must be a different name from your iOS app subtitle. Do not include the phrases Apple TV, tvOS or ATV in the subtitle of your tvOS app.

XPath

<description>Challenging, action-filled combat game with fighter jets and missiles.</description>

Description (required on initial delivery of a locale; otherwise optional)

The description of the app in the specified <locale> language. It must be at least 10 characters but no more than 4000 characters. Use the description to describe the features and functionality of your app. This description is exactly how your app will display on your customer’s device based on their default language settings.

Use plain text, not HTML. Line breaks are permitted.

If you are delivering metadata for a tvOS app, keep in mind that it can have its own app description. Use the description to explain the ways in which the app is optimized for a large screen and how the app leverages the features of the Apple TV Remote to create an immersive, intuitive experience.

XPath

<promotional_text>On sale for a limited time.</promotional_text>

Promotional Text (optional; can be updated at any time without requiring a binary update)

The promotional text of the app in the specified <locale> language. Use the <promotional_text> tag to 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.

XPath

<keywords>

  <keyword>combat</keyword>

  <keyword>multi-player</keyword>

  <keyword>fighter jets</keyword>

</keywords>

Keywords (required on initial delivery of a locale; otherwise optional)

One or more keywords that describe your app. Keywords are used to help customers find your app on the App Store effectively. You can supply single keywords or a phrase within a <keyword> tag, or you can supply multiple keywords separated by commas within a <keyword> tag (for example, <keyword>education, fun, words</keyword>). There is a limit of 100 characters for all keywords, including any commas. Customers can search your app by app name, company name, and keywords.

Note: Make sure the keywords do not violate the rights or trademarks of any third parties. Keywords must be related to your app content and cannot contain offensive or trademarked terms, other app names, or company names. If you deliver a keyword that is trademarked or that references another app’s name or company name, your app may be removed from the App Store.

XPath

<version_whats_new>Fixed a bug.</version_whats_new>

What’s New Text (required on initial delivery of a new locale for a new app revision)

Note: This tag is used only for apps that have been revised (for example, a 1.1 version). Do not use this tag for an app that is the first version (for example, 1.0). The version in this example is 1.1, so the “what’s new” text is required.

Describes the changes in the language specified in the locale tag that have been made to the app revision being delivered. The text must be at least 4 characters but no more than 4000 characters. You must deliver this tag when adding a new locale to a revised app; the tag is optional when updating a locale of a revised app.

XPath

<software_url>http://www.CITouchfighter.com</software_url>

Marketing URL (optional)

The website where users get more information about the app. The URL must be at least 2 characters but no more than 255 bytes.

To remove a marketing URL previously delivered, send the tag without a value (called an “empty” tag) using one of the following:

  • <software_url></software_url>

  • <software_url/>

XPath

<privacy_url>http://www.CITouchfighter.com/privacy/</privacy_url>

Privacy Policy URL (required on initial delivery of a new locale; optional on update of locale)

A URL that links to your privacy policy. A privacy policy is required for all apps. (For tvOS apps, see the Privacy Policy Text annotations below.)

To remove a privacy URL previously delivered, send the tag without a value (called an “empty” tag) using one of the following:

  • <privacy_url></privacy_url>

  • <privacy_url/>

XPath

<privacy_policy_text>This is an example of privacy policy text for your Apple TV app</privacy_policy_text>

Privacy Policy Text (required for tvOS apps on initial delivery of a new locale; optional on update of locale)

The text of your privacy policy. 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. For any non-tvOS app, you can remove privacy policy text previously delivered by sending the tag without a value (called an “empty” tag) using one of the following:

  • <privacy_policy_text></privacy_policy_text>

  • <privacy_policy_text/>

XPath

<support_url>http://www.CITouchfighter.com/support/</support_url>

Support URL (required on initial delivery of a locale; otherwise optional)

The support website you plan to provide for users who have questions regarding the app. The support URL must lead to actual contact information so that your users can contact you regarding app issues, general feedback, and feature enhancement requests. The URL must be at least 2 characters but no more than 255 bytes.

XPath

<app_previews>

App Previews (optional)

Begins the app previews element block. App previews are optional, and when supplied, they appear before screenshots on the App Store.

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. Keep in mind that the second or third previews are only visible for customers with devices running iOS 11. Also, app previews autoplay only on iOS 11 or later; for iOS 10.3 or earlier, the poster frame image appears. MacOS previews are only visible for customers with devices running macOS 10.14 or later.

For app preview guidelines, see Planning Your App Preview.

Important: If you deliver an empty tag (<app_previews></app_previews> or <app_previews/>), all existing app previews will be removed (including any app previews that may have been uploaded using App Store Connect).

XPath

<app_preview display_target="iOS-5.5-in" position="1">

App Preview (optional)

A video previewing your app. The app preview designated as position="1" is the first app preview that appears on your app product page on the Mac App Store and the device App Store when viewed from the user’s device. You can deliver up to three app previews for each display_target within each <locale>.

Use the required display_target attribute to indicate the device for the app preview you are delivering:

  • iOS-4-in

  • iOS-4.7-in

  • iOS-5.5-in

  • iOS-5.8-in

  • iOS-6.5-in

  • iOS-iPad

  • iOS-iPad-Pro

  • iOS-iPad-Pro-10.5-in

  • iOS-iPad-Pro-11-in

  • iOS-iPad-Pro-2018

  • tvOS

  • macOS

The position attribute is required and the position numbers must start with 1, should be consecutive, with no gaps between numbers. Also, position must be unique among elements with same display_target within a locale.

Notes:

  • You can reorder the app previews by delivering a metadata update with all the app previews in the new positions.

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

  • You can upload 6.5-inch display app previews for the iPhone XS Max, which will be automatically resized for iPhone X and later (iPhone XR, iPhone XS, and iPhone X).

  • You can upload 12.9-inch iPad Pro (3rd generation) app previews, which will be automatically resized for the 11-inch iPad Pro.

  • Whether you choose to use one device-specific app preview (one for iPhone devices and one for iPad devices) for all supported display sizes, or use an individual custom app preview for each display size, you must use the same option for both your app previews and screenshots per localization.

  • Any display target that has either app previews or screenshots will show only the previews and screenshots assigned to that display target. For example, if you provide 5.5" screenshots and previews and only 5.8" screenshots (without a 5.8” preview), then users won’t see any previews on the iPhone X.

  • To remove an app preview, redeliver the <app_previews> block, omitting the app preview you want to remove and renumbering the remaining previews.

To view the app preview size requirements, click this link: App preview specifications.

XPath

  <preview_image_time format="24/999 1000/nonDrop">00:00:17:01</preview_image_time>

Preview Image Time (optional)

The frame to use for the app preview poster frame image. You can specify an image for each app preview. The format can be qt_text (default) or one of the SMPTE formats shown in the Timecode Formats appendix in the iTunes Package Film Specification. In qt_text format, the frame nearest the timecode is used for the poster frame; you cannot specify an exact frame using qt_text.

The preview image time must be within the app preview source duration. If you omit the <preview_image_time> tag, a default time is used to capture a frame from the video to use for the poster frame.

XPath

    <data_file role="source">

      <file_name>app_preview.mp4</file_name>

      <size>33558000</size>

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

    </data_file>

App Preview Source Asset (optional)

The <data_file> block specifies the source video asset for the app preview. The data file must be in .mp4, .m4v, or .mov format and the duration must be between 15 and 30 seconds. The app preview asset can include only one data file and the role must be "source". The <file_name>, <size>, and <checksum> tags are required within the <data_file> block.

XPath

<software_screenshots>

Software Screenshots (optional)

Begins the software screenshots element block. Screenshots are optional on initial delivery, but must be delivered either on initial delivery or 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.

You can also reorder the screenshots by supplying all the screenshots in the new positions (using the position attribute) within the <software_screenshots> block.

Important: 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 App Store Connect).

XPath

<software_screenshot display_target="iOS-iPad" position="1">

Software Screenshot (optional)

A screenshot of your app. The first screenshot (designated as position="1") is the first screenshot that appears on your app product page on the Mac App Store and the device App Store when viewed from the user’s device. You can deliver up to nine additional optional screenshots for iOS, tvOS, watchOS, and macOS. All subsequent screenshots will appear in numbered order on the App Store, in the same order in which they designated with the position attribute.

Use the required display_target attribute to indicate the device for the screenshot you are delivering:

  • iOS-3.5-in

  • iOS-4-in

  • iOS-4.7-in

  • iOS-5.5-in

  • iOS-5.8-in

  • iOS-6.5-in

  • iOS-iPad

  • iOS-iPad-Pro

  • iOS-iPad-Pro-10.5-in

  • iOS-iPad-Pro-11-in

  • iOS-iPad-Pro-2018

  • appletvos

  • iOS-Apple-Watch

  • iOS-Apple-Watch-Series-4

  • Mac

To be displayed on the Store, a locale must have at least one screenshot for each supported display_target.

The position attribute is required and the position number must start with 1, should be consecutive, with no gaps between numbers.

Notes:

  • Delivering a screenshot for a specific iPhone device display target through the feed (for example, <software_screenshot display_target="iOS-4-in" position="1">) overrides the option to use the 5.5-inch screenshot (if you selected it in App Store Connect) 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 App Store 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.

  • 6.5-inch display screenshots for iPhone XS Max are currently optional. You can upload screenshots for the iPhone XS Max, which 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.

  • 12.9-inch iPad Pro (3rd generation) display screenshots are currently optional and also display with rounded corners. These screenshots will scale down for the 11-inch iPad Pro, but not for older iPad devices.

  • Whether you choose to use one device-specific screenshot (one for iPhone devices and one for iPad devices) for all supported display sizes, or use an individual custom screenshot for each display size, you must use the same option for both your app previews and screenshots per localization.

To view the screenshot size requirements, click this link: Screenshot specifications.

To remove a screenshot, redeliver the <software_screenshots> block, omitting the screenshot you want to remove and renumbering the remaining screenshots.

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

XPath

<file_name>screen-en-US-ipad-1.png</file_name>

File Name (required when delivering a screenshot)

The name of the screenshot.

Important: File names are case sensitive and spaces are not allowed.

XPath

<size>286243</size>

File Size (required when delivering a screenshot)

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

XPath

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

Checksum (required when delivering a screenshot)

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

 </software_screenshot>

</software_screenshots>

XPath

<locale name="ru-RU" remove="true"/>

Remove Locale (optional)

To remove a locale, deliver the <locale> tag and use the name attribute to specify which locale to remove and set the attribute remove to "true".

Note: You cannot remove the locale of the default language (as set in App Store Connect or set with the attribute default="true" in the <locale> tag).

   </locale>

  </locales>

XPath

<products>

  <product>

Product (optional)

For each app, you can deliver information on the product, such as pricing and whether it is cleared for sale. You can set the price tier and schedule price tier changes for the future by setting start and end dates using the <intervals> tag. See Interval Pricing for information on how to deliver interval pricing.

XPath

<territory>WW</territory>

Product Territory (required within the <product> block)

The product territory specifies where the app is cleared for sale. You must specify WW (World Wide) as the territory because the price tiers, dates, and volume discount must be the same across all territories.

You can deliver additional <product> blocks for specific territories to indicate that the app is not to be sold in that territory. See the <cleared_for_sale> annotation below. When specifying the territories, you must use a valid ISO 3166 alpha-2 country code. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico).

For a list for ISO 3166-1 alpha 2 codes, see https://www.iso.org/obp/ui/#search.

XPath

<sales_start_date>2010-05-25</sales_start_date>

Sales Start Date (optional)

The date this app is available for purchase in the App Store. This field must be in YYYY-MM-DD format. The <sales_start_date> tag is allowed only within the WW territory; sales start dates must be the same across all territories.

Important: Omitting this tag will make the app available for sale immediately.

XPath

<cleared_for_sale>true</cleared_for_sale>

Cleared For Sale (required within the <product> block)

Indicates whether or not this app can be sold in the specified product territory. Accepted values are true and false in English. The <cleared_for_sale> tag can be used for non-WW territories.

To indicate that the app is not to be sold in the territory, set <cleared_for_sale> to false for the specified <territory>. Send the <product> block with the <cleared_for_sale> and <territory> tags only; you do not need to supply any other tags within the <product> block.

XPath

<wholesale_price_tier>9</wholesale_price_tier>

Wholesale Price Tier (required for WW territory)

The wholesale price tier for the app. Must be a wholesale price tier number as specified in the agreement with Apple. The <wholesale_price_tier> tag is allowed only within the WW territory; the price tier must be the same across all territories.

Review your agreement to verify the tiers available to you. If an invalid price tier is provided, the App Store reserves the right to reject the package. To request technical assistance, contact us at https://developer.apple.com/contact.

See Interval Pricing for information on how to deliver interval pricing.

XPath

<allow_volume_discount>false</allow_volume_discount>

Allow Volume Discount (optional)

Use this tag to indicate that the app is eligible for discounts for educational institutions. Accepted values are true and false in English. The <allow_volume_discount> tag is allowed only within the WW territory; the volume discount must be the same across all territories.

 </product>

</products>

    . . .

   </software_metadata>

  </software>

</package>

In-App Purchase Profile

Overview

This chapter provides information on delivering in-app purchases to the App Store. In-app purchases allow you to sell additional features and functionality from within your free or paid iOS, tvOS, and macOS apps. To learn more, see In-App Purchase for Developers.

Note: To offer in-app purchases in your apps, you will need to have the latest Paid Applications agreement in effect with Apple. Your Account Holder can request the latest Paid agreement in App Store Connect. Your Account Holder will also need to click through the latest Program License Agreement in the Membership section of your account on the Apple Developer website.

In-App Purchase Examples Overview

The following in-app purchase examples are used to deliver in-app purchase to an app that has already been delivered to the App Store. The examples describe how to deliver the following:

  • Consumable in-app purchase

  • Auto-renewable subscription in-app purchase

  • Non-consumable in-app purchase with content hosted by Apple

In addition, you can deliver a non-renewing in-app purchase by using the subscription type: <type>subscription</type>.

You can also deliver pricing intervals for an in-app purchase, which is described in Interval Pricing.

Basic In-App Purchase Metadata Example

Below is an example metadata.xml file for a basic (consumable) in-app purchase.

<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="software5.11"> <provider>CyberInteractive</provider> <team_id>A9B8C7D6E5</team_id> <software> <vendor_id>CI0009</vendor_id> <software_metadata> . . . <in_app_purchases> <in_app_purchase> <product_id>com.cyberinteractive.touchfighter.missiles.10</product_id> <reference_name>10 missiles</reference_name> <type>consumable</type> <products> <product> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>3</wholesale_price_tier> </product> </products> <locales> <locale name="en-US"> <title>10 Missiles</title> <description>This product provides an additional 10 missiles to take you on your way.</description> </locale> </locales> <review_screenshot> <file_name>screenshot-01.png</file_name> <size>286243</size> <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum> </review_screenshot> <review_notes>Some notes for the reviewer.</review_notes> </in_app_purchase> <in_app_purchase remove="true"> <product_id>obsolete_com.cyberinteractive.tf.missiles.15</product_id> </in_app_purchase> </in_app_purchases> . . . </software_metadata> </software></package>

Basic In-App Purchase 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="software5.11">

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="software5.11". 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 (not the in-app purchase) 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 the in-app purchase.

XPath

<in_app_purchases>

In-App Purchases (optional)

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

XPath

<in_app_purchase>

In-App Purchase (At least one <in_app_purchase> is required if <in_app_purchases> block is supplied)

Identifies an individual in-app purchase. You can define multiple <in_app_purchase> blocks as needed, up to 10,000 for each app. However, no more than 1000 <in_app_purchase> elements can be delivered in a single upload.

XPath

<product_id>com.cyberinteractive.touchfighter.missiles.10</product_id>

Product ID (required; up to 255 characters)

A unique identifier for the in-app purchase. It can be composed of letters, numbers, underscores (_), and periods (.). For example, com.company.app_name.productid.

When your app communicates with the App Store, it uses product identifiers to retrieve the configuration data you provided for the product. Later, when a customer wants to purchase a product, your app identifies the product to be purchased using its product identifier.

The product identifier is also used for reporting purposes and therefore must be unique across all of your applications and add-ons. You cannot edit the product ID after delivering your in-app purchase. Once you use a product ID for one in-app purchase, you cannot use it again.

XPath

<reference_name>10 missiles</reference_name>

Reference Name (required)

A unique name for the in-app purchase. You can use up to 64 characters and it must be unique within the app. The reference name is displayed in App Store Connect and in Sales and Trends reports. It is not displayed on the App Store.

XPath

<type>consumable</type>

Type (required)

Describes the product type of your in-app purchase from the viewpoint of the App Store. The in-app purchase type cannot be changed once your in-app purchase has been delivered. There are four in-app purchase types available for use: consumables, non-consumables, auto-renewable subscriptions, non-renewing subscriptions. For details, see In-App Purchase for Developers.

XPath

<products>

  <product>

Product (required)

For each in-app purchase, you must supply information on the product, such as pricing and whether it is cleared for sale. You can set the price tier and schedule price tier changes for the future by setting start and end dates using the <intervals> tag. See Interval Pricing for information on how to deliver interval pricing.

Note: The <products> block must contain one and only one <product>.

XPath

<cleared_for_sale>true</cleared_for_sale>

Cleared For Sale (required)

Specifies whether the in-app purchase is cleared for sale. Must be true or false in English.

Note: Setting <cleared_for_sale> to false does not permanently delete an in-app purchase from your app. To delete an in-app purchase, add the attribute remove="true" to an <in_app_purchase> tag and supply the <product_id> as shown at the bottom of this table below.

XPath

<wholesale_price_tier>9</wholesale_price_tier>

Wholesale Price Tier (required)

The wholesale price tier for the in-app purchase. Must be a wholesale price tier number as specified in your agreement with Apple.

If the <type> is consumable, subscription, non-consumable, or auto-renewable, the price tier must not be 0, (which indicates it is free).

Review your agreement to verify the tiers available to you. If an invalid price tier is provided, the App Store reserves the right to reject the package. To request technical assistance, contact us at https://developer.apple.com/contact.

 </product>

</products>

XPath

<locales>

  <locale name="en-US"/>

Locale Name (required)

Identifies the language of the product. The locale indicates both the language and the specific region where the language is spoken.

To specify a locale, use a dash character to combine a language designator 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 in-app purchases.

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.

XPath

<title>10 Missiles</title>

Title (required)

The title (also referred to as Display Name in App Store Connect) of the in-app purchase in the specified <locale> language. This name is displayed on the App Store. The name must be at least 2 characters but no more than 30. This name is exactly how your in-app purchase will display on your customer’s device based on their default language settings.

XPath

<description>This product provides an additional 10 missiles to take you on your way.</description>

Description (required)

The description of the in-app purchase in the specified <locale> language. It must be at least 10 characters but no more than 45. This description is exactly how your in-app purchase will display on your customer’s device based on their default language settings.

   </locale>

  </locales>

XPath

<review_screenshot>

Review Screenshot (required on initial delivery)

A screenshot of your in-app purchase in action used for review purposes only. (This is referred to as Screenshot under Review Information in App Store Connect.) Your in-app purchase image will not display on the App Store or on a user’s device. The screenshot should be a clear picture of your in-app purchase in action. The screenshot can be JPEG (.jpg or .jpeg) or PNG (.png) in RGB color mode. Each in-app purchase can have only one screenshot associated with it.

To view the screenshot size requirements, click this link: Screenshot specifications.

If you are sending an update, review screenshots are not required.

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

XPath

<file_name>screenshot-01.png</file_name>

File Name (required)

The name of the review screenshot.

Important: File names are case sensitive and spaces are not allowed.

XPath

<size>286243</size>

File Size (required)

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

XPath

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

Checksum (required)

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

 </review_screenshot>

XPath

<review_notes>Some notes for the reviewer.</review_notes>

Review Notes (optional)

Use this tag to give demo account information with full access to Apple for purposes of reviewing your in-app purchase. The information you include in the tag is visible only to the App Review team; it will not appear on the App Store. The maximum length for review notes is 4000 bytes.

The following lists some examples of what to include in this tag:

  • If your in-app purchase requires specific settings, user registrations, or account information prior to submission to the App Store, be sure to include that information.

  • If the in-app purchase delivers streaming video over the cellular network, include a test stream URL.

  • Include general instructions or other relevant information about your in-app purchase that you think would be useful for the review process.

To remove existing notes, supply an empty <review_notes> notes tag: <review_notes></review_notes>

</in_app_purchase>

XPath

<in_app_purchase remove="true">

In-App Purchase (required)

To remove an obsoleted in-app purchase, include an <in_app_purchase> block and set the attribute remove to "true".

XPath

<product_id>obsolete_com.cyberinteractive.tf.missiles.15</product_id>

Product ID (required; up to 255 characters)

A unique identifier for the in-app purchase you are removing.

     </in_app_purchase>

    </in_app_purchases>

   </software_metadata>

  </software>

</package>

Auto-Renewable In-App Purchase Metadata Example

Below is an example metadata.xml file for an in-app purchase that is automatically renewed. To learn about auto-renewable subscriptions, including subscription groups, levels, duration, and pricing, see Auto-renewable Subscriptions.

Before You Begin: Before you can create auto-renewable subscriptions, you must first generate a receipt validation code, known as a shared secret. A shared secret is a unique receipt validation code that you should use when you make the call to our servers for your in-app purchase receipts. Without a shared secret, you will not be able to test auto-renewable subscriptions in the sandbox mode, nor will you be able to make them available in the App Store.

Auto-renewable subscriptions require the value auto-renewable in the <type> tag; no other values are allowed. You deliver auto-renewable subscriptions using the <subscription_group> tag. All in-app purchases within the <subscription_group> tag must be the same content, but with different durations and optional levels. For example, suppose your in-app purchase is for a streaming service and you want to offer both a 6-month and a 1-year subscription. To do this, include two <in_app_purchase> blocks within a <subscription_group>, one offering a 6-month duration and the other offering a 1-year duration—it is the same product offered for two different durations.

In addition to different durations, you can offer different levels by using the <rank> tag. Using the streaming service example, you could have different levels depending on the number of products/services provided. You could offer a basic level that includes a minimum number of programs (rank 3); a mid-level that includes the basic and one premium channel (rank 2); and the highest level that includes the basic and two premium channels (rank 1).

The Subscription Group is also used to group your subscription offerings on the customer’s Manage Subscriptions page on the device.

Note: 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.

The example below shows the delivery of an in-app purchase <subscription_group> only, however, the <subscription_group> block can be delivered together with other in-app purchases. The example shows one subscription group with four in-app purchases offering two different durations, in two different service levels. One in-app purchase includes both an introductory offer and a promotional offer.

<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="software5.11 <provider>CyberInteractive</provider> <team_id>A9B8C7D6E5</team_id> <software> <vendor_id>CI0009</vendor_id> <software_metadata> <in_app_purchases> <subscription_group name="Streaming All Access"> <locales> <locale name="en-US"> <title>Streaming All Access</title> <app_name>Super Streaming</app_name> </locale> </locales> <in_app_purchase> <reference_name>Every Movie In The World Plus One Month</reference_name> <locales> <locale name="en-US"> <title>Every Movie In The World Plus One Month</title> <description>Every movie ever plus extra stuff for one month.</description> </locale> </locales> <product_id>every_movie_in_the_world_plus_1month</product_id> <type>auto-renewable</type> <duration>1 Month</duration> <bonus_duration>7 Days</bonus_duration> <cleared_for_sale>true</cleared_for_sale> <rank>1</rank> <review_screenshot> <file_name>every_movie_in_the_world_plus_1month.png</file_name> <size>286243</size> <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum> </review_screenshot> <review_notes>Some notes for the reviewer.</review_notes> <prices> <!-- Before submitting the in-app purchase for review, you can supply only initial prices and you must supply prices for all 155 territories. Once the review process occurs and it is approved, initial prices can no longer be added or changed. --> <price> <territory>US</territory> <tier>5</tier> </price> <!-- Additional territories here --> </prices> </in_app_purchase> <in_app_purchase> <reference_name>Every Movie In The World Plus Six Months</reference_name> <locales> <locale name="en-US"> <title>Every Movie In The World Plus Six Months</title> <description>Every movie ever plus extra stuff for six months.</description> </locale> </locales> <product_id>every_movie_in_the_world_plus_6months</product_id> <type>auto-renewable</type> <duration>6 Months</duration> <bonus_duration>1 Month</bonus_duration> <cleared_for_sale>true</cleared_for_sale> <rank>1</rank> <review_screenshot> <file_name>every_movie_in_the_world_plus_6months.png</file_name> <size>266253</size> <checksum type="md5">4c46cc5c6c4153ce868b7fcdc137f60f</checksum> </review_screenshot> <review_notes>Some notes for the reviewer.</review_notes> <prices> <price> <territory>US</territory> <tier>7</tier> </price> <price> <start_date>2017-05-30</start_date> <territory>US</territory> <tier>8</tier> <keep_previous_tier>true</keep_previous_tier> </price> <!-- Additional territories here --> </prices> <offers> <offer> <territory>US</territory> <type>introductory</type> <tier>1</tier> <mode>pay-as-you-go</mode> <duration>1 month</duration> <number_of_periods>2</number_of_periods> <start_date>2018-01-01</start_date> <end_date>2018-03-01</end_date> </offer> </offers> <promotional_offers> <promotional_offer> <type>promotional</type> <reference_name>promo1_2018</reference_name> <product_code>2018NewYear</product_code <mode>pay-as-you-go</mode> <duration>1 month</duration> <number_of_periods>2</number_of_periods> <!-- These prices refer to the promotional offer --> <prices> <price> <territory>US</territory> <tier>3</tier> </price> <!-- Additional price territories and tiers here --> </prices> </promotional_offer> </promotional_offers> </in_app_purchase> <in_app_purchase> <reference_name>Every Movie In The World One Month</reference_name> <locales> <locale name="en-US"> <title>Every Movie In The World One Month</title> <description>Every movie ever for one month.</description> </locale> </locales> <product_id>every_movie_in_the_world_1month</product_id> <type>auto-renewable</type> <duration>1 Month</duration> <bonus_duration>7 Days</bonus_duration> <cleared_for_sale>true</cleared_for_sale> <rank>2</rank> <review_screenshot> <file_name>every_movie_in_the_world_1month.png</file_name> <size>243862</size> <checksum type="md5">cef37f6c0f53c868b7c5c4c46dc16c41</checksum> </review_screenshot> <review_notes>Some notes for the reviewer.</review_notes> <prices> <price> <territory>US</territory> <tier>4</tier> </price> <price> <start_date>2017-05-30</start_date> <territory>US</territory> <tier>5</tier> <keep_previous_tier>true</keep_previous_tier> </price> <!-- Additional territories here --> </prices> </in_app_purchase> <in_app_purchase> <reference_name>Every Movie In The World Six Months</reference_name> <locales> <locales> <locale name="en-US"> <title>Every Movie In The World Six Months</title> <description>Every movie ever for six months.</description> </locale> </locales> <product_id>every_movie_in_the_world_6months</product_id> <type>auto-renewable</type> <duration>6 Months</duration> <bonus_duration>1 Month</bonus_duration> <cleared_for_sale>true</cleared_for_sale> <rank>2</rank> <review_screenshot> <file_name>every_movie_in_the_world_6months.png</file_name> <size>293253</size> <checksum type="md5">b7c5c6c53cefcf4c46dc137f868c4160</checksum> </review_screenshot> <review_notes>Some notes for the reviewer.</review_notes> <prices> <price> <territory>US</territory> <tier>6</tier> </price> <price> <start_date>2017-05-30</start_date> <territory>US</territory> <tier>7</tier> <keep_previous_tier>true</keep_previous_tier> </price> <!-- Additional territories here --> </prices> </in_app_purchase> </subscription_group> </in_app_purchases> </software_metadata> </software></package>

Auto-Renewable In-App Purchase 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="software5.11">

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="software5.11". The “software” portion of the attribute must be in lowercase letters.

XPath

<provider>CyberInteractive</provider>

Provider (required, App Store-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:

  • Acme|Productions

  • 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 the in-app purchase.

XPath

<in_app_purchases>

In-App Purchases (required)

Begins the in-app purchases element block.

XPath

<subscription_group name="Streaming All Access">

Subscription Group (required)

Identifies a renewable subscription. The name attribute identifies the name of the subscription (streaming service, magazine, newspaper, newsletter, and so on). For each subscription duration/optional level you offer, define an <in_app_purchase> block. All in-app purchases within the <subscription_group> tag must be the same content, but with different durations/optional levels. For example, suppose your in-app purchase is for a video streaming service and you want to offer both a 6-month and a 1-year subscription. To do this, include two <in_app_purchase> blocks, one offering a 6-month duration and the other offering a 1-year duration—it is the same service offered for two different durations. To offer different levels (for example, a basic service and a basic+plus service), you would include four in-app purchases: the basic with the two durations and the basic+plus with two durations. You assign a level using the <rank> tag described below.

Notes:

  • A subscription group can contain a maximum of 100 in-app purchases.

  • In-app purchases within the same subscription group may have the same duration.

  • In-app purchases within a subscription group must have a rank.

  • Subscription group names cannot be edited using an XML delivery. You can use App Store Connect to make the name changes.

XPath

<locales>

  <locale name="en-US"/>

Locale Name (required)

Identifies the language of the renewable subscription. The locale indicates both the language and the specific regions where the language is spoken.

Note: The <locales> entered here apply to subscription group. You can also include the <locales> block within each individual <in_app_purchase> block.

To specify a locale, use a dash character to combine a language designator 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 conveys useful information. See Language Codes for a list of languages supported for in-app purchases.

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.

XPath

<title>Streaming All Access</title>

Title (required)

The title of the auto-renewable subscription in the specified <locale> language. This title is displayed on the App Store and on the Manage App Subscriptions page on the user’s device. The title must be at least 2 characters but no more than 30. This title is exactly how the subscription group will display on your customer’s device based on their default language settings.

XPath

<app_name>Super Streaming</app_name>

App Name (optional)

The App Name field is optional, but can be used to supply a shorter version of your app name. The name must be at least 2 characters and no more than 30 characters. This value must be unique and can’t be reused across multiple apps.

   </locale>

  </locales>

XPath

<in_app_purchase>

In-App Purchase (required)

Identifies a subscription duration (and optional level) <in_app_purchase> within the <subscription_group>. You can define multiple <in_app_purchase> blocks as needed for the durations/levels you plan to offer.

Note: 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.

XPath

<reference_name>Every Movie In The World Plus One Month</reference_name>

Reference Name (required)

A unique name for the in-app purchase. You can use up to 64 characters and it must be unique within the app. The reference name is displayed in App Store Connect and in Sales and Trends reports. It is not displayed on the App Store.

XPath

<locales>

  <locale name="en-US"/>

    <title>Every Movie In The World Plus One Month</title>

    <description>Every movie ever plus extra stuff for one month.</description>

  </locale name>

</locales>

Localized In-App Purchase Title and Description (required)

The title and description of the renewable subscription in the specified <locale> language.

To specify a locale, use a dash character to combine a language designator 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. Apple recommends providing the region only when it conveys useful information. See Language Codes for a list of languages supported for in-app purchases.

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.

XPath

<product_id>every_movie_in_the_world_plus_1month</product_id>

Product ID (required; up to 255 characters)

A unique identifier for the in-app purchase. It can be composed of letters, numbers, underscores (_), and periods (.). For example, com.company.app_name.productid.

When your app communicates with the App Store, it uses product identifiers to retrieve the configuration data you provided for the product. Later, when a customer wants to purchase a product, your app identifies the product to be purchased using its product identifier.

The product identifier is also used for reporting purposes and therefore must be unique across all of your apps and in-app purchases. You cannot edit the product ID after delivering your in-app purchase. Once you use a product ID for one in-app purchase, you cannot use it again.

XPath

<type>auto-renewable</type>

Type (required)

Describes the product type of your in-app purchase from the viewpoint of the App Store. The in-app purchase type cannot be changed once your in-app purchase has been delivered. For renewable subscriptions, the type must be auto-renewable.

XPath

<duration>1 Month</duration>

Duration (required)

Identifies the length of the subscription you are offering with this in-app purchase. A subscription duration is the length of time between auto-renewals. You must add at least one <duration>. Note that in-app purchases within a subscription group can have the same duration. Accepted values are:

  • 7 Days

  • 1 Month

  • 2 Months

  • 3 Months

  • 6 Months

  • 1 Year

XPath

<bonus_duration>7 Days</bonus_duration>

Bonus Duration (optional)

Use <bonus_duration> to offer customers a subscription extension as an incentive when they opt in to share their contact information with you for marketing purposes. The bonus duration is available only when the customer initially subscribes; not on subsequent renewals. Accepted values are:

  • 3 Days

  • 7 Days

  • 14 Days

  • 1 Month

  • 2 Months

  • 3 Months

Note: You can view the customer’s opted-in information in Sales and Trends of App Store Connect.

XPath

<review_screenshot>

Review Screenshot (required on initial delivery)

A screenshot of your renewable subscription in-app purchase used for review purposes only. (This is referred to as Screenshot under Review Information in App Store Connect.) Your in-app purchase screenshot will not display on the App Store or on a user’s device. The screenshot should be a clear picture of your in-app purchase and can be JPEG (.jpg or .jpeg) or PNG (.png) in RGB color mode. Each <subscription_group> can have only one screenshot associated with it.

To view the screenshot size requirements, click this link: Screenshot specifications.

Important: Do not scale up the screenshot artwork if it is smaller than the required size.

XPath

<file_name>every_movie_in_the_world_plus_1month.png</file_name>

File Name (required)

The name of the review screenshot.

Important: File names are case sensitive and spaces are not allowed.

XPath

<size>286243</size>

File Size (required)

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

XPath

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

Checksum (required)

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

 </review_screenshot>

XPath

<review_notes>Some notes for the reviewer.</review_notes>

Review Notes (optional)

Use this tag to give demo account information with full access to Apple for purposes of reviewing your in-app purchase. This information you include in the tag is visible only to the App Review team; it will not appear on the App Store. These review notes apply to the individual in-app purchase. The maximum length for review notes is 4000 bytes.

The following lists some examples of what to include in this tag:

  • If your in-app purchase requires specific settings, user registrations, or account information prior to submission to the App Store, be sure to include that information.

  • If the in-app purchase delivers streaming video over the cellular network, include a test stream URL.

  • Include general instructions or other relevant information about your in-app purchase that you think would be useful for the review process.

To remove existing notes, supply an empty <review_notes> notes tag:

<review_notes></review_notes>

XPath

<cleared_for_sale>true</cleared_for_sale>

Cleared For Sale (optional)

Specifies whether the in-app purchase is cleared for sale. Must be true or false in English. If you set <cleared_for_sale> to false, this duration/level will not be available for purchase from within the app. If you omit the <cleared_for_sale> tag, it defaults to true.

Note: Setting <cleared_for_sale> to false does not permanently delete an in-app purchase from your app. To delete an in-app purchase, add the attribute remove="true" to an <in_app_purchase> tag and supply the <product_id> as shown in Basic In-App Purchase Metadata Example.

XPath

<rank>1</rank>

Subscription Level (optional)

Specifies the subscription level of the in-app purchase within the subscription group. Must be a positive number. Subscription levels that offer the highest level of service should be rank 1. You can add more than one subscription to each level if the service provided is determined to be equal. Other service levels would be ranked 2, 3,… and so on. For example, if you offer three levels, the highest level would be rank 1; mid-level would be rank 2, and the lowest level would be rank 3. These levels are used to define upgrades, downgrades, and crossgrades.

XPath

<prices>

Prices (optional)

A collection of one or more price blocks for an auto-renewable in-app purchase.

Note: If any of the price blocks contain changes that can increase or decrease an existing customer's subscription price, a verification code is required to confirm the changes made. If this is the case, when you deliver the XML metadata, you will see an error message that gives you the verification code you need to supply. To deliver the code, add the attribute verification_code="code_in_error_message" (where code_in_error_message is the code displayed in the error message) to the <prices> tag and resubmit the metadata (<prices verification_code="2059904228">). Once these changes go into effect they cannot be reversed.

The following price changes require that you supply a verification_code:

  • Planning a future price change that decreases the cost. Any existing customers paying more than the new tier/cost will pay the newer, lower price.

  • Ending price preservation for a customer group. Affected customers would pay the next highest price provided they agree to the new price. If they do not agree to the new price, their subscription will not renew.

  • Scheduling a price increase without using price preservation. Existing customers must agree to the new, higher price or their subscription will not renew.

XPath

  <price>

Price (optional)

The price of an auto-renewable subscription duration/level for a specific territory. Every territory requires an initial price and only one price change (price with a start date in the future) is maintained per territory. Before submitting a new in-app purchase for review, you must include a <price> block for each of the 155 territories and the <price> block should include only the <territory> and <price_tier> tags as shown below:

<prices>

 <price>

  <territory>US</territory>

  <tier>3</tier>

 <price>

 . . .

</prices>

You can change an initial price as long as the in-app purchase has not been submitted for review. Once the in-app purchase has been approved, you can deliver the existing prices (either the initial prices or any prior changes you made to those prices).

In addition, the following three examples (price change, price change removal, and cost increase for an existing price) can only be made once the in-app purchase is approved (and initial prices are immutable).

To create a future price change: supply the <start_date> (which must be in the future), <territory>, <tier>, and (optionally) <keep_previous_tier> for that price change. (If you omit the <keep_previous_tier> tag when scheduling a future price change, it defaults to true.)

<price>

  <start_date>2017-05-30</start_date>

  <territory>US</territory>

  <tier>4</tier>

</price>

To delete a future price change: add the attribute remove="true" to a <price> tag and supply the <start_date> (which must be in the future), <territory>, and <tier> for that price change:

<price remove="true">

  <start_date>2017-05-30</start_date>

  <territory>US</territory>

  <tier>4</tier>

</price>

To increase the cost for an existing price: add the attribute increase_cost="true" to a <price> tag and supply the <start_date>, <territory>, and <tier> for that existing price. A <start_date> is not required if you are increasing an initial price; if you do not include a start date, it is assumed you are updating the initial price.

<price increase_cost="true">

  <territory>US</territory>

  <tier>7</tier>

</price>

A <start_date> is required if you are selecting prices that were scheduled subsequent to the initial price.

<price>

  <territory>BN</territory>

  <tier>3</tier>

</price>

<price>

  <territory>BN</territory>

  <tier>5</tier>

  <start_date>2016-10-28</start_date>

</price>

<price>

  <territory>BN</territory>

  <tier>7</tier>

  <start_date>2016-11-01</start_date>

</price>

<price>

  <territory>BN</territory>

  <tier>10</tier>

  <start_date>2016-11-03</start_date>

</price>

You could end price preservation for the prices in bold above.

If you want everyone who is paying Tier 7 amount from 11/01 to now pay Tier 10 amount, the XML should be:

<price increase_cost="true">

  <territory>BN</territory>

  <tier>7</tier>

  <start_date>2016-11-01</start_date>

</price>

XPath

    <start_date>2016-05-30</start_date>

Pricing Start Date (required except for initial price)

The start date for the price in YYYY-MM-DD format. Initial prices do not have a start date.

You can schedule one future price change per territory.

Below is an example of delivering the initial price (which was supplied before approval and cannot be changed) and scheduling a price change for an in-app purchase that has been approved:

<prices>

 <price>

  <territory>US</territory>

  <tier>3</tier>

 </price>

 <price>

  <start_date>2017-05-30</start_date>

  <territory>US</territory>

  <tier>4</tier>

 </price>

</prices>

XPath

  <territory>

Territory (required)

The territory to which this pricing applies.

You can deliver additional <price> blocks for specific territories to indicate that the price tier is for that territory. When specifying the territories, you must use a valid ISO 3166 alpha-2 country code. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico).

For a list for ISO 3166-1 alpha 2 codes, see https://www.iso.org/obp/ui/#search.

XPath

  <tier>6</tier>

Price Tier (required)

The price tier for the renewable subscription duration/level, which translates to a specific currency type and amount per territory. Must be a price tier number as specified in your agreement with Apple. The price tier must not be 0, (which indicates it is free). You can change prices as frequently as you would like.

Note: If you lower the price of a subscription, all subscribers at the current price in affected territories will be charged the new, reduced price; you cannot decrease a price for a specific group of subscribers. When you decrease a price, you must supply a value using the verification_code attribute in the <prices> tag. See the annotation for the <prices> tag above.

Important: Make sure you have downloaded the current list of available subscription price tiers from App Store Connect. You can download the subscription price tiers for an auto-renewable subscription in the Subscription Prices section (click All Prices and Currencies).

Review your agreement to verify the tiers available to you. If an invalid price tier is provided, the App Store reserves the right to reject the package. To request technical assistance, contact us at https://developer.apple.com/contact.

XPath

  <keep_previous_tier>true</keep_previous_tier>

Keep Previous Tier (optional)

Specifies whether a price change will leave the previous subscription tier unchanged in the specified territory (referred to as price preservation). This tag allows you to increase the price on new auto-renewable subscriptions while preserving the current price for existing subscribers. If you omit the tag, the value is assumed to be true. If you choose not to keep existing subscribers at their current price by delivering a value of false, subscribers are notified with an email and a push notification. If they do not agree to the new price, their subscription is not renewed. There is no upper limit on the number of existing subscribers to which the previous price preservation applies.

Note: You can preserve the current price for existing subscribers only when increasing prices. If you lower the price of a subscription, all subscribers above the new price in affected territories will be charged the new, reduced price.

To remove a previous price preservation tier, include a <price> block and add the attribute increase_cost="true". See the annotation for the <price> tag above:

 </price>

</prices>

XPath

<offers>

Offers (optional)

A collection of one or more offer blocks for an auto-renewable in-app purchase.

XPath

<offer>

Offer (optional)

The existing or future introductory price of an auto-renewable subscription duration/level for a specific territory. Each territory can have one existing and one future offer in effect at any time. An offer is not required. You can change the existing introductory price as long as the in-app purchase has not been submitted for review. Once the in-app purchase has been approved, you can deliver the existing offers and (optionally) include any changes to offers in the future.

To create an introductory price change: supply the <type>, <territory>, <tier> (for introductory offers only), <mode> (for introductory offers only), <duration>, <number_of_periods> (for pay-as-you-go introductory offers), <start_date> (which must be today or in the future), and (optionally) <end_date> (which must be after the start date).

Introductory type example:

<offer>

  <territory>US</territory>

  <type>introductory</type>

  <tier>4</tier>

  <mode>pay-up-front</mode>

  <duration>7 Days</duration>

  <number_of_periods>2</number_of_periods>

  <start_date>2018-01-01</start_date>

</offer>

Free Trial type example (currently still supported):

<offer>

  <territory>US</territory>

  <type>free-trial</type>

  <duration>7 Days</duration>

  <start_date>2018-01-01</start_date>

  <end_date>2019-01-01</end_date>

</offer>

To remove an offer: redeliver the <offers> block, omitting the offer you want to remove.

Important: If you deliver an empty tag (<offers></offers> or <offers/>), all existing and future offers will be removed.

XPath

<territory>

Territory (required)

The territory to which this offer applies.

You can deliver additional <offer> blocks for specific territories to indicate that the offer tier is for that territory. When specifying the territories, you must use a valid ISO 3166 alpha-2 country code. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico). For a list for ISO 3166-1 alpha 2 codes, see https://www.iso.org/obp/ui/#search.

XPath

<type>

Type (required)

The type of offer being applied.

Currently you can specify either introductory or free-trial as the type. Only one type can be applied to a territory at one time. You can switch the type of offer applied by delivering a future offer change.

For introductory offers, you can offer “pay-as-you-go”, “pay-up-front”, or “free” (see the annotation for <mode> below).

XPath

<tier>

Price Tier (required; only applicable for introductory type)

The price tier for the introductory offer, which translates to a specific currency type and amount per territory. Must be a price tier number as specified in your agreement with Apple. The price tier must not be 0, (which indicates it is free). You can change prices as frequently as you would like.

Important: For introductory offers using the pay-as-you-go mode, if the tier of the offer is greater than the tier of the subscription, it will not be offered to customers.

Important: Make sure you have downloaded the current list of available subscription price tiers from App Store Connect. You can download the subscription price tiers for an auto-renewable subscription in the Subscription Prices section (click All Prices and Currencies).

Review your agreement to verify the tiers available to you. If an invalid price tier is provided, the App Store reserves the right to reject the package. To request technical assistance, contact us at https://developer.apple.com/contact.

XPath

<mode>

Mode (required; only applicable for introductory type)

The payment mode, which is offered as one of three types:

  • 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: Customers receive a subscription for free for a selected duration (for example, free for 2 months).

Introductory 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.

XPath

<duration>1 Month</duration>

Introductory Offer Duration (required)

The period of the introductory offer. Each introductory offer type and mode permits a certain set of durations as shown in the table below.

For an introductory offer using the pay-as-you-go mode, the allowable durations will vary based on the standard subscription duration. You define the period of the introductory offer by delivering a duration (<duration>) combined with a valid number of periods (<number_of_periods>). For example, if you have a one month subscription and wanted to set up a for 4-month introductory offer, deliver <duration>1 Month</duration> and <number_of_periods>4</number_of_periods>.

durations for subscriptions and offers
XPath

  <number_of_periods>2</number_of_periods>

Number of Periods (optional)

The number of periods that the introductory offer lasts for based on the duration you delivered. If the number of periods is omitted, then the value '1' is used. For introductory offers using the pay-up-front mode, the number of periods must be '1' (or omitted). For introductory offers using the pay-as-you-go mode, the number of periods is limited to a maximum value of 12 or that which lasts for no more than 1 year, whichever comes sooner.

XPath

  <start_date>2018-01-01</start_date>

Start Date (optional)

The date that the introductory offer goes into effect. If the start date is omitted, then today's date is used.

XPath

<end_date>2018-03-01</end_date>

End Date (optional)

The date that the introductory offer ends. If the end date is omitted, then the offer will not have an end date.

  </offer>

</offers>

XPath

<promotional_offers>

Promotional Offers (optional)

A collection of one or more <promotional_offer> blocks for an auto-renewable subscription.

XPath

<promotional_offer>

Promotional Offer (optional)

A discounted promotional price for a specific duration for existing or previously subscribed customers. An offer is not required. Once the promotional period ends, the subscription auto-renews at the standard price. You can have up to 10 active promotional offers within the <promotional_offers> block.

For promotional offers, you can offer “pay-as-you-go”, “pay-up-front”, or “free” (see the annotation for <mode> below).

To remove a promotional offer: deliver the tag <promotional_offer remove="true">.

XPath

<reference_name>promo1_2018</reference_name>

Promotional Offer Reference Name (required)

An internal name for a promotional offer that you can reference. The reference name must have at least 2 characters, but not more than 64. The reference name must be unique within a delivery; you can’t re-use a reference name, even if it's been deleted.

XPath

<product_code>2018NewYear</product_code>

Promotional Offer Product Code (required)

A code that you create using from 1 to 100 characters. This code must be unique for each offer you create; you can’t re-use a product code, even if it's been deleted.

Restrictions: The product code can only contain alphanumeric characters, underscore marks, and periods; it cannot contain spaces, dashes, ampersands, other punctuation, or symbols. The product code is case-sensitive.

XPath

<mode>

Promotional Offer Mode (required for new offers)

The payment mode, which is offered as one of three types:

  • pay-as-you-go: Customers pay a promotional 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 promotional price for a selected duration (for example, $1.99 for 2 months for a subscription with a standard price of $9.99).

  • free: Customers receive a promotional subscription for free for a selected duration (for example, free for 2 months).

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.

XPath

<duration>1 Month</duration>

Promotional Offer Duration (optional)

The period of the promotional subscription offer. Each promotional offer type and mode permits a certain set of durations as shown in the table below.

For a promotional offer using the pay-as-you-go mode, the allowable durations will vary based on the standard subscription duration. You define the period of the promotional offer by entering a duration (<duration>) combined with a valid number of periods (<number_of_periods>). For example, if you have a one month subscription and wanted to set up a 4-month promotional offer, deliver <duration>1 Month</duration> and <number_of_periods>4</number_of_periods>.

durations for subscriptions and offers
XPath

  <number_of_periods>2</number_of_periods>

Number of Periods (optional)

The number of periods that the promotional offer lasts for based on the duration you delivered. If the number of periods is omitted, then the value '1' is used. For promotional offers using the pay-up-front mode, the number of periods must be '1' (or omitted). For promotional offers using the pay-as-you-go mode, the number of periods is limited to a maximum value of 12 or that which lasts for no more than 1 year, whichever comes sooner.

XPath

<prices>

Prices (required for promotional offers that are not free)

A collection of one or more price blocks for a promotional offer.

Note: The <prices> block is not allowed with free promotional offers.

XPath

  <price>

Price (required for promotional offers that are not free)

The price of the promotional offer for a specific territory.

To make changes to existing promotional offer prices, redeliver the <promotional_offer> block with the changed territory/tier. You must supply the <product_code> and <reference_name> tags; the other tags can be omitted. If you do supply the <mode>,, <duration>, or <number_of_periods> tags, they must match the existing discount offer, or delivery will fail. You only need to deliver the territories with new price tiers; other territories will stay at their existing tiers.

XPath

  <territory>

Territory (required)

The territory to which this pricing applies.

You can deliver additional <price> blocks for specific territories to indicate that the price tier is for that territory. A territory can appear only once per promotional offer.

When specifying the territories, you must use a valid ISO 3166 alpha-2 country code. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico).

For a list for ISO 3166-1 alpha 2 codes, see https://www.iso.org/obp/ui/#search.

XPath

  <tier>3</tier>

Price Tier (required)

The price tier for the promotional offer, which translates to a specific currency type and amount per territory. Must be a price tier number as specified in your agreement with Apple. The price tier must not be 0, (which indicates it is free). You can change prices as frequently as you would like.

Review your agreement to verify the tiers available to you. If an invalid price tier is provided, the App Store reserves the right to reject the package. To request technical assistance, contact us at https://developer.apple.com/contact.

     </price>

    </prices>

  </promotional_offer>

</promotional_offers>

      </in_app_purchase>

     </subscription_group>

    </in_app_purchases>

   </software_metadata>

  </software>

</package>

Hosted In-App Purchase Metadata Example

Non-consumable in-app purchases can be hosted by Apple so you do not need to maintain your own servers. The product type for hosted content must be non-consumable. Hosted content can be additional resources, but not executables. Examples include filters on a camera app, a level map for a game, add-on videos, images, or a magazine issue. 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 account, and available for iOS, tvOS, and macOS apps. For details on how to upload hosted content in Xcode, see Xcode Help.

Below is an example metadata.xml file for a non-consumable in-app purchase. The in-app purchase is a single issue of a magazine. This example delivers both the metadata for the content, and the asset.

<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="software5.11 <provider>FreestonePress</provider> <team_id>7D6EA9B8C5</team_id> <software> <vendor_id>com.freestonepress.guidebooks</vendor_id> <software_metadata> <in_app_purchases> <in_app_purchase> <product_id>com.freestonepress.guidebooks.bodega</product_id> <reference_name>Bodega Guide</reference_name> <type>non-consumable</type> <products> <product> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>3</wholesale_price_tier> </product> </products> <locales> <locale name="en-US"> <title>Bodega Guide</title> <description>This publication is a travel guide to Bodega, one volume of the series on small towns in Sonoma County.</description> </locale> </locales> <review_screenshot> <file_name>screenshot-01.png</file_name> <size>286243</size> <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum> </review_screenshot> <review_notes>Some notes for the reviewer.</review_notes> <has_hosted_content>true</has_hosted_content> <software_assets> <asset type="in-app-purchase-content"> <data_file> <file_name>com.freestonepress.guidebooks.bodega.pkg</file_name> <size>286243</size> <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum> </data_file> </asset> </software_assets> </in_app_purchase> </in_app_purchases> </software_metadata> </software></package>

Hosted In-App Purchase Metadata Annotated

Only the tags relevant to hosted content are annotated below. See Basic In-App Purchase Metadata Annotated for information on the other tags.

XPath

<type>non-consumable</type>

Type (required)

The product type for hosted content must be non-consumable. The in-app purchase type cannot be changed once your in-app purchase has been delivered. 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 App Store account. Available for iOS and macOS applications.

XPath

<has_hosted_content>true</has_hosted_content>

Hosted Content (optional)

Indicates that your in-app purchase is hosted by Apple, not on your own servers. Currently, only non-consumable in-app purchases can be hosted. Acceptable values are true or false.

Keep the following in mind when sending the <has_hosted_content> tag:

  • If the in-app purchase is not currently live, you can remove the files by changing true to false. You do not need to send an empty <software_assets> block for removal).

  • If the in-app purchase is currently live and is not content-hosted, supplying the true value triggers version creation. If the in-app purchase is not live, or if it is live and is already hosted, no version creation is triggered.

  • Once the <has_hosted_content> tag has been set to true and the content is live, you cannot change the value to false.

XPath

<software_assets>

  <asset type="in-app-purchase-content">

    <data_file>

      <file_name>com.freestonepress.guidebooks.bodega.pkg</file_name>

      <size>286243</size>

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

    </data_file>

  </asset>

</software_assets>

Software Assets (optional)

Use the <software_assets> block to deliver the in-app purchase content that will be hosted by Apple. The asset type must be "in-app-purchase-content". The data file must be in .pkg format (built by Xcode). The <file_name>, <size>, and <checksum> tags are required within the <data_file> block.

If the in-app purchase content has already been delivered and the checksum is different, the following apply:

  • If the content is not currently live, the existing data file will be replaced.

  • If the content is currently live, a new version will be created.

Note: Currently, only one asset file may be included in the <software_assets> block.

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 Game Kit 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 within the Game Center app; 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="software5.11"> <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="software5.11">

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="software5.11". 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 Game Kit 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

Interval Pricing

Overview

Pricing intervals allow you to schedule price tier changes for an app and for in-app purchases over time. This is useful for sales and other temporary pricing changes that have a definite beginning and end date, as well as permanent pricing changes that have no end date. For example, you could offer a promotional price for a month, and then return to the regular price. You can set a price tier <start_date> (the date that the new tier will take effect on the App Store), and a price tier <end_date> (the date that the tier will no longer be in effect and will revert to the previously set price tier). You can set up as many price tier changes as you want in advance and the app or in-app purchase will change prices on your effective dates. Omitting the <end_date> tag means that the interval will last until the start date of the following interval. If no further intervals are specified, the price will remain in effect indefinitely.

Note: You are not required to use interval pricing. Use intervals only when you want the price to change at a specified date in the future.

If you provide interval pricing, you must follow these requirements or delivery will fail:

  • Gaps between intervals are not allowed.

  • For the first interval, the <start_date> tag must either be omitted (meaning that the interval implicitly starts immediately) or it must contain a value that is no later than the current date. For subsequent intervals, the <start_date> may be any point in the future.

  • The end date of the first interval must not be earlier than the <sales_start_date>.

  • The last interval must have no end date.

Note: If the in-app purchase is new, you must supply an interval that starts either today or a date in the past and that does not have an end date. This ensures that there is always a price available for all dates in the future.

Keep the following in mind when delivering interval pricing:

  • An unlimited number of intervals are allowed; however, for each interval, there is a period of several hours where the product will be unavailable for sale while the price is changed.

  • Once intervals are delivered for a given product, the classic pricing model (as outlined in the Basic App Metadata Profile) may no longer be used.

  • Intervals are date-specific and not time-specific. Your app will be available based on the time zone used for each territory, for example, in the US, the app will be available no later than midnight Pacific time (PT) on the date specified in the <sales_start_date> tag.

  • The minimum interval duration is one day, and each change will take several hours to appear in the store while the cache is updated.

  • If two intervals overlap, the last interval specified in a given metadata update will take precedence.

  • You can leave out the <end_date> and the price will not change again. If no <end_date> is supplied, the interval does not end and remains in effect indefinitely.

  • If you would like to preserve planned scheduled changes, your product updates should contain all known pricing intervals from the date of delivery forward. Otherwise, new pricing information, particularly where there is no start or end date may impact previously-delivered scheduled changes.

Interval Pricing Metadata Example

The example XML below shows how to deliver an app and an in-app purchase with pricing intervals. Note that you do not need to deliver the <versions> block if you are just updating the pricing for the app.

<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="software5.11"> <provider>CyberInteractive</provider> <team_id>A9B8C7D6E5</team_id> <software> <vendor_id>CI0009</vendor_id> <software_metadata> <products> <product> <territory>WW</territory> <sales_start_date>2010-05-25</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <intervals> <interval> <start_date>2010-05-25</start_date> <end_date>2010-06-25</end_date> <wholesale_price_tier>9</wholesale_price_tier> </interval> <interval> <start_date>2010-06-25</start_date> <wholesale_price_tier>7</wholesale_price_tier> </interval> </intervals> </product> <product> <territory>FR</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <in_app_purchases> <in_app_purchase> <product_id>com.cyberinteractive.touchfighter.missiles.10</product_id> <reference_name>10 missiles</reference_name> <type>consumable</type> <products> <product> <cleared_for_sale>true</cleared_for_sale> <intervals> <interval> <start_date>2010-05-25</start_date> <end_date>2010-06-25</end_date> <wholesale_price_tier>9</wholesale_price_tier> </interval> <interval> <start_date>2010-06-25</start_date> <wholesale_price_tier>7</wholesale_price_tier> </interval> </intervals> </product> </products> <locales> <locale name="en-US"> <title>10 Missiles</title> <description>This product provides an additional 10 missiles to take you on your way.</description> </locale> </locales> <review_screenshot> <file_name>screenshot-01.png</file_name> <size>286243</size> <checksum type="md5">c0f4c46dc16c4153cef37f6c868b7c5c</checksum> </review_screenshot> <review_notes>Some notes for the reviewer.</review_notes> </in_app_purchase> </in_app_purchases> </software_metadata> </software></package>

Interval Pricing Metadata Annotated

Only the tags relevant to interval pricing are annotated. See Basic App Metadata Example and Basic App Metadata Annotated for annotations on other tags.

XPath

<products>

  <product>

Product (required if providing intervals)

For each app, you must supply information on the product, such as pricing and whether it is cleared for sale. You can set the price tier and schedule price tier changes for the future by setting start and end dates using the <intervals> tag.

XPath

<cleared_for_sale>true</cleared_for_sale>

Cleared For Sale (required)

Specifies whether the app is cleared for sale in the specified territory. Must be true or false in English.

XPath

<intervals>

Interval Declaration (required)

The beginning of a group of intervals for a specific product, for all countries in which the product is available.

Note: The <intervals> block can only be delivered within the WW territory; other territories can only have the <cleared_for_sale> tag (and the <territory> tag). This is because all territories must have the same sales start date and same price tier.

XPath

<interval>

Interval (required)

The beginning of an individual interval for a specific product, for all countries in which the product is available.

XPath

<start_date>2010-05-25</start_date>

Interval Start Date (optional)

The start date for the given interval in YYYY-MM-DD format. For the first interval, the <start_date> tag must either be omitted (meaning that the interval implicitly starts immediately) or it must contain a value that is no later than the current date (except for new app products—see the following paragraph). For subsequent intervals, the <start_date> may be any point in the future.

If the app product is new, you must supply an interval that doesn't have an end date; the start date must be either today, in the past, or no start date at all. This ensures that there is always a price available for all dates in the future.

XPath

<end_date>2010-06-25</end_date>

Interval End Date (optional)

The end date for the given interval. This may be any point at least 24 hours after the interval's start date and must follow the YYYY-MM-DD format. If the end date is not specified, the interval will last until the start date of the following interval. If no further intervals are specified, the interval will last indefinitely.

XPath

<wholesale_price_tier>9</wholesale_price_tier>

Wholesale Price Tier (required)

The wholesale price tier for the app for the given interval. Must be a wholesale price tier number as specified in your agreement with Apple.

Review your agreement to verify the tiers available to you. If an invalid price tier is provided, App Store reserves the right to reject the package. To request technical assistance, contact us at https://developer.apple.com/contact.

    </interval>

   </intervals>

 </product>

</products>

XPath

<in_app_purchases>

  <in_app_purchase>

    <products>

      <product>

Product (required if providing intervals)

For each in-app purchase, you must supply information on the product, such as pricing and whether it is cleared for sale. You can set the price tier and schedule price tier changes for the future by setting start and end dates using the <intervals> tag.

XPath

<cleared_for_sale>true</cleared_for_sale>

Cleared For Sale (required)

Specifies whether the in-app purchase is cleared for sale. Must be true or false in English.

Note: Setting <cleared_for_sale> to false does not permanently delete an in-app purchase from your app. To delete an in-app purchase, add the attribute remove="true" to an <in_app_purchase> tag and supply the <product_id> as shown in Basic App Metadata Example.

XPath

<intervals>

Interval Declaration (required)

The beginning of a group of intervals for a specific product.

XPath

<interval>

Interval (required)

The beginning of an individual interval for a specific product. Any number of intervals may be provided in any initial product delivery or subsequent update.

XPath

<start_date>2010-05-25</start_date>

Interval Start Date (optional)

The start date for the given interval YYYY-MM-DD format. For the first interval, the <start_date> tag must either be omitted (meaning that the interval implicitly starts immediately) or it must contain a value that is no later than the current date (except for new in-app purchases—see the following paragraph). For subsequent intervals, the <start_date> may be any point in the future.

If the in-app purchase is new, you must supply an interval that doesn't have an end date; the start date must be either today, in the past, or no start date at all. This ensures that there is always a price available for all dates in the future.

XPath

<end_date>2010-06-25</end_date>

Interval End Date (optional)

The end date for the given interval. This may be any point at least 24 hours after the interval's start date and must follow the YYYY-MM-DD format. If the end date is not specified, the interval will last until the start date of the following interval. If no further intervals are specified, the interval will last indefinitely.

XPath

<wholesale_price_tier>9</wholesale_price_tier>

Wholesale Price Tier (required)

The wholesale price tier for the in-app purchase for the given interval. Must be a wholesale price tier number as specified in your agreement with Apple.

If the <type> is consumable, subscription, non-consumable, or auto-renewable, the price tier must not be 0, (which indicates it is free).

Review your agreement to verify the tiers available to you. If an invalid price tier is provided, App Store reserves the right to reject the package. To request technical assistance, contact us at https://developer.apple.com/contact.

       </interval>

      </intervals>

      </product>

   </products>

 </in_app_purchase>

</in_app_purchase>

Language Codes

The table below lists the supported languages for use with the <locale> tag. The languages supported for Game Center are a subset of the languages listed below. The checkmark appears in the appropriate column to indicate that language is supported.

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 Software and In-App Purchases

Supported for Game Center

Catalan

ca

Chinese (Simplified)

zh-Hans

Chinese (Traditional)

zh-Hant

Croatian

hr

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

Hungarian

hu

Indonesian

id

Italian

it

Japanese

ja

Korean

ko

Malay

ms

Norwegian

no

Polish

pl

Portuguese (Brazil)

pt-BR

Portuguese (Portugal)

pt-PT

Romanian

ro

Russian

ru

Slovak

sk

Spanish (Mexico)

es-MX

Spanish (Spain)

es-ES

Swedish

sv

Thai

th

Turkish

tr

Ukrainian

uk

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

http://www.nullriver.com/

Revision History

Previous Spec Revisions

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

Date/Version

Changes Made

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.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. See Basic App Metadata Example for an XML example and see Basic App Metadata Annotated for annotations.

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. See Basic App Metadata Example for an XML example and see Basic App Metadata Annotated for annotations.

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. See Basic App Metadata Example for an XML example and see Basic App Metadata Annotated for annotations.

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. See Auto-Renewable In-App Purchase Metadata Example for an XML example and see Auto-Renewable In-App Purchase Metadata Annotated for annotations.

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. See Auto-Renewable In-App Purchase Metadata Example for a metadata XML example and see Auto-Renewable In-App Purchase Metadata Annotated for tag annotations.

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. See Interval Pricing for a list of the requirements.

In addition to the validations, the <start_date> of the first interval within the <intervals> block is optional for the first interval. See Interval Pricing Metadata Annotated for more information.

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