/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

  \page qtpurchasing-appstore.html
  \title Registering Products in App Store
  \brief A short guide to registering in-app products in the iOS App Store.

  To take advantage of in-app purchasing functionality on iOS, register your
  application and all the available products in
  \l{http://itunesconnect.apple.com}{iTunes Connect}.
  This guide provides a brief introduction on how to register an application
  and it's in-app products on App Store.

  In-App purchasing can only be tested on the actual hardware for the iOS
  platform. For more information refer to the
  \l{http://developer.apple.com/in-app-purchase/}{iOS documentation}.


  \section1 Register a Unique App ID

  One of the requirements to support in-app purchases on iOS is to have
  a registered unique App ID. This means that it is not possible to use
  an App ID that contains a wildcard character. You can check the existing App
  IDs and create new ones from the
  \l{https://developer.apple.com/account/ios/identifiers/bundle/bundleList.action}{Apple  Developer Certificate, Identifiers, and Profiles manager}.

  In the \uicontrol{App IDs} tab of the
  \uicontrol{Developer Certificate, Identifiers, and Profiles} manager, click
  the \uicontrol{+} button to create a New App ID. This will open up the page
  to register a new iOS App ID.

  Give your App a relevant ID description and prefix. Your App ID Suffix
  should be an Explicit App ID type. Enter a unique App ID in the Bundle ID
  field. It is recommended to use the com.mycompany.myappname convention for
  App ID. Where, the "com.mycompany" is the Internet domain name of the
  publisher.

  In the \uicontrol{App Services} area make sure that the
  \uicontrol{In-App Purchases} is checked. Click \uicontrol{continue} your to
  complete the App ID registration.

  \section1 Create a Provisioning Profile

  To be able to use your new App ID, generate a new provision profile that
  includes the new ID to sign and run your app. Provisioning Profiles are also
  managed through the
  \uicontrol{Apple Developer Certificate, Identifiers, and Profiles} manager.

  Navigate to the \uicontrol{Provisioning Profiles} tab of the manager and
  click the \uicontrol{+} button to create a new Provisioning Profile.  Make
  sure that the \uicontrol{iOS App Development} is selected and click the
  \uicontrol{Continue} button.

  You are now given an option to choose the App ID to use for this profile,
  which will be the unique App ID you created in the previous section. Once
  again make sure that the App ID does not contain any wildcard characters
  (“*”) as it is not be possible to use the In-App Purchasing service with
  such an App ID.

  On the next page you will need to select the certificates that will be
  distributed with your Provisioning Profile. You would have needed to uploaded
  a certificate on your local development machine to the Apple Developer
  Certificate, Identifiers, and Profiles manger previously. Generally you will
  want to add any certificates of the members of your team who will need to build
  your App.

  On the next page you will need to select the devices you will be developing and
  testing your app on. You must register your devices to the Apple Developer
  Certificate, Identifiers, and Profiles manger previously. The devices you
  select here are the only ones capable of running apps signed against this
  provisioning profile, so select all the devices you intend use during the
  development and testing phase.

  Give your Provisioning Profile a descriptive display name, and click
  \uicontrol{Generate} to create the actual profile. When this process is
  completed you’ll be given a choice to download the Provisioning Profile.

  Open the downloaded file in XCode to install. Now the next time you plug in
  one of the registered devices, your Provisioning Profile should be installed
  to it automatically.

  \section1 Register Your Application

  Before you can register new products available to the in-app purchasing service,
  you need to register your application in iTunes Connect. iTunes Connect is the
  place where you register an app when you want to submit it to the Apple iOS
  App Store.

  Start by going to \l{https://itunesconnect.apple.com}{iTunes Connect} and
  logging in. Once logged in open the \uicontrol{Manage your Apps} link. If you
  have already registered your app here, you can skip the registration step,
  otherwise click the \uicontrol{Add New App} button in the top left corner
  of the page.

  Select iOS App and then proceed to fill out the required information on the
  next page. When you get to the \uicontrol{Bundle ID} section select the
  unique App ID we created in the previous steps.

  It is likely at this point that you do not have all the necessary details to
  complete the information required to register your app. For now, just fill
  out the forms with stub data as everything except the \uicontrol{SKU} and
  \uicontrol{Version} fields are editable later.

  \section1 Register the Products

  Once your app is registered in iTunes Connect you will have additional options
  available to manage that App. In the \uicontrol{Manage Your Apps} page of iTunes
  Connect, click the icon representing your app to manage its details. Within this
  menu you can select the \uicontrol{Manage In-App Purchases} button on the right
  to register in-app products you wish to offer.

  To register a new product, click the \uicontrol{Create New} button in the top
  left corner of the page. The first choice you will be given is the type of
  in-app purchase you would like to create. The Qt Purchasing API currently
  only supports Consumable and Non-Consumable types so limit your selection
  to these.  See QInAppProduct for an explanation about the different product
  types.

  On the next page, you must fill out the details about your product. The
  \uicontrol{Reference Name} field refers to how the product will be
  displayed in iTunes Connect and in sales reports, but not in the
  App Store itself. The \uicontrol{Product ID} field is very important
  as it is the unique ID that will be used to query for the product from your
  app itself. If possible make this the same ID as the corresponding products
  in the other platform’s stores, otherwise you will have to conditional logic
  in your app for each platform when specifying product identifiers.

  Select the pricing and availability details for you product next. For the iOS
  App Store, pricing is set via a tier system. Each tier represents a price
  level in each iOS App Store region. Your end users will be given the actual
  price expected for a product in terms of what region their App Store is in.

  In the next section \uicontrol{In-App Purchase Details} you specify the details
  for at least one language. When the app requests the product details like
  \c title and \c description, they will be provided in the language of their
  locale if they are available. Create language details for the regions you
  expect to distribute app in.

  Finally, you will need to attach a screenshot that will be used for review
  purposes. This again can be a stub for now, but your product will need to
  pass the review before it can go live to be sold in your published app. Click
  \uicontrol{save} to complete the product registration.

  \section1 Create an iTunes Test User

  Once your products are registered you will be able to purchase them from your
  app. When you are developing your app it is desirable to test buying your
  products without spending real currency. There are actually two separate
  stores that requests can be sent to when using the In-App Purchasing service
  on iOS. While your app is being developed, any iOS App Store requests will be
  sent to a sandbox store. This occurs when your app has been signed with a
  developer Provisioning Profile. The sandbox store will only accept requests
  from test users and will not charge for the purchases. However, when you
  submit your app to the iOS App Store and it is accepted, all in-app
  purchasing requests are sent to the production store, which requires real
  iTunes users accounts, and will charge for the purchases.

  To create an iTunes test user, log into
  \l{https://itunesconnect.apple.com}{iTunes Connect}.

  Select the \uicontrol{Manage Users} link on the left and click the
  \uicontrol{Test User} button. Here you will see any existing iTunes test
  users associated with your account. To add a new iTunes test user, click the
  \uicontrol{Add New User} button on the top left corner of the page. Fill out
  the details to your preference, bearing in mind that the most important
  selection is the \uicontrol{Select iTunes Store}, which specifies the
  store region your users will be testing from.

  \section1 Using the Sandbox App Store

  Once you have created your iTunes test user, you will be able to log in to
  the sandbox app store when developing your app.

  It is important that you first log out of the current iTunes user on your
  Apple device. To do this, open the \uicontrol{Settings} app from the
  homescreen and go to the \uicontrol{iTunes & App Store} entry. Click the
  first entry (which should be \uicontrol{Apple ID}) and select
  \uicontrol{Sign Out}.

  Do not sign in with your iTunes test user from the Settings App as this
  connects to the production App Store and your purchase request will fail.

  The first time your App makes a request to the sandbox App Store it will
  request that you login. This is where you should log in using your iTunes
  test user credentials.
*/

