Покупки из приложения и пробные версии

Пакет Windows SDK предоставляет API, которые можно использовать для реализации следующих функций, позволяющих получать прибыль от своего приложения универсальной платформы Windows (UWP):

Покупки из приложения Независимо от того, является ли ваше приложение бесплатным или нет, вы можете продавать содержимое или новые функции приложения (например, разблокировать следующий уровень игры) прямо в приложении.

Функциональные возможности пробной версии Если вы настроите приложение в качестве бесплатной пробной версии в Центре партнеров, вы можете заставить клиентов приобрести полную версию приложения, исключив или ограничив некоторые функции в течение пробного периода. Вы можете также включить такие компоненты, как баннеры или водяные знаки, которые будут отображаться только во время пробного периода, пока пользователь не купит приложение.

Эта статья содержит обзорные сведения о том, как в приложениях UWP работают покупки из приложения и пробные версии.

Выбор пространства имен

Существует два разных пространствах имен, которые можно использовать для добавления функций покупок из приложения и пробной версии в приложениях UWP в зависимости от того, для какой версии Windows 10 предназначены ваши приложения. Несмотря на то что API в этих пространствах имен служат тем же целям, они различаются принципами разработки и имеют несовместимый код.

Windows.Services.Store начиная с Windows 10 версии 1607 приложения могут использовать API в этом пространстве имен для реализации покупок и пробных версий в приложении. Рекомендуется использовать элементы из этого пространства имен, если ваше проект вашего приложения предназначен для Windows 10 Anniversary Edition (10.0; сборка 14393) или более позднего выпуска в Visual Studio. Это пространство имен поддерживает последние типы надстроек, такие как управляемые Магазином потребляемые надстройки, и предназначены для обеспечения совместимости с будущими типами продуктов и функций, поддерживаемых Центром партнеров и Магазином. Дополнительные сведения об этом пространстве имен см. в разделе Покупки из приложения и пробные версии, использующие пространство имен Windows.Services.Store этой статьи.

Windows.ApplicationModel.Store Все версии Windows 10 также поддерживают более старый API для покупок в приложении и пробных версий в этом пространстве имен. Сведения об использовании элементов пространства имен Windows.ApplicationModel.Store см. в разделе Внутренние покупки приложения и пробные версии, использующие пространство имен Windows.ApplicationModel.Store.

Пространство имен Windows.ApplicationModel.Store больше не дополняется новыми функциями, и мы рекомендуем вместо него использовать пространство имен Windows.Services.Store, если это возможно для вашего приложения. Пространство имен Windows.ApplicationModel.Store не поддерживается в классических приложениях Windows, использующих мост для классических приложений или в приложениях или играх, использующих песочницу разработки в Центре партнеров (например, это относится к любой игре, которая интегрируется с Xbox Live).

Основные понятия

Каждый элемент, предлагаемый в Магазине, как правило, называется продукт. Большинство разработчиков работают только со следующими типами продуктов: приложения и надстройки.

Надстройка представляет собой продукт или функцию, которую вы предоставляете своим клиентам (пользователям) в контексте приложения: например, валюту для использования в приложении или игре, новые карты или оружие для игры, возможность использовать приложение без рекламы, а также цифровое содержимое (музыку или видео) для приложений, в которых реализована возможность предоставления такого типа содержимого. С каждым приложением и каждой надстройкой связана лицензия, указывающая, имеет ли пользователь право на использование приложения или надстройки. Если пользователь имеет право на использование приложения или надстройки в качестве пробной версии, лицензия также предоставляет дополнительную информацию об этой пробной версии.

Чтобы предложить надстройку клиентам в приложении, необходимо определить надстройку для приложения в Центре партнеров , чтобы Магазин знал об этом. Затем ваше приложение может использовать API в пространстве имен Windows.Services.Store или Windows.ApplicationModel.Store, чтобы предложить пользователю надстройку в качестве покупки из приложения.

Приложения UWP могут иметь следующие типы надстроек.

Когда пользователь использует все элементы, связанные с надстройкой, вы несете ответственность за поддержание баланса пользователя и за предоставление отчетов о покупке надстройки в Магазине после того, как пользователь использовал все элементы. Пользователь не может снова приобрести надстройку, пока ваше приложение не сообщит об израсходовании предыдущей покупки.

Когда пользователь использует все элементы, связанные с надстройкой, вы несете ответственность за создание отчетов об этих элементах в Магазине, а Магазин обновляет баланс пользователя. Пользователь может приобрести надстройку сколько угодно раз (для этого не требуется сначала использовать элементы). Приложение может в любой момент запросить текущий баланс пользователя.

Например, если ваша надстройка представляет начальное количество 100 монет в игре, а пользователь потребляет 50 монет, ваше приложение сообщает Магазину, что было выполнено 50 единиц надстройки, а Магазин обновляет оставшийся баланс. Если пользователь затем снова приобретает надстройку, чтобы получить еще 100 монет, общее число монет составит 150.

Другие типы надстроек, например надстройки длительного пользования с пакетами (также известны как "загружаемое содержимое" или DLC), доступны ограниченному кругу разработчиков и не освещаются в этой документации.

Покупки из приложения и пробные версии, использующие пространство имен Windows.Services.Store

В этом разделе содержится обзор важных задач и понятий пространства имен Windows.Services.Store. Это пространство имен доступно только приложениям, предназначенным для Windows 10 Anniversary Edition (10.0; сборка 14393) и более поздних выпусков в Visual Studio (это соответствует Windows 10 версии 1607). Рекомендуется по возможности использовать пространство имен Windows.Services.Store, а не Windows.ApplicationModel.Store. Информацию о пространстве имен Windows.ApplicationModel.Store см. в этой статье.

Содержание раздела

Посмотрите видеоролик, чтобы ознакомиться с общими сведениями о том, как реализовать покупки из приложения с помощью пространства имен Windows.Services.Store.

Главной точкой входа в пространство имен Windows.Services.Store является класс StoreContext. Этот класс предоставляет методы, которые можно использовать, чтобы получить сведения о текущем приложении и его доступных надстройках, получить лицензионные сведения о текущем приложении или его надстройках, приобрести приложение или надстройку для текущего пользователя и решить другие задачи. Чтобы получить объект StoreContext, выполните одно из следующих действий.

В однопользовательском приложении (то есть приложении, которое работает только в контексте пользователя, который запустил это приложение) воспользуйтесь статическим методом GetDefault, чтобы получить объект StoreContext, который можно использовать для доступа к актуальным для пользователя данным, связанным с Microsoft Store. Большинство приложений UWP — это однопользовательские приложения.

В многопользовательском приложении используйте статический метод GetForUser, чтобы получить объект StoreContext, который можно использовать для доступа к данным, связанным с Microsoft Store. Речь идет о данных для конкретного пользователя, который при работе с приложением выполнил вход с учетной записью Майкрософт. В следующем примере мы получим объект StoreContext для первого доступного пользователя.

Классические приложения для Windows, использующие мост для классических приложений, должны выполнить дополнительные действия для настройки объекта StoreContext, чтобы его можно было использовать. Дополнительные сведения см. в этом разделе.

Получив объект StoreContext, можно начать вызывать методы этого объекта для получения сведений о продукте из Магазина для текущего приложения и его надстроек, получать сведения о лицензии для текущего приложения и его надстроек, приобретать приложение или надстройку для текущего пользователя и выполнять другие задачи. Дополнительные сведения об общих задачах, которые можно выполнять с помощью этого объекта, см. в следующих статьях:

Пример приложения, в котором показано, как использовать класс StoreContext и другие типы в пространстве имен Windows.Services.Store, см. в разделе Образец из Магазина.

Чтобы предложить покупки из приложения пользователям вашего приложения, используя пространство имен Windows.Services.Store, выполните следующие действия:

Если ваше приложение предлагает надстройки, которые клиенты могут приобрести, создайте отправки надстроек для вашего приложения в Центре партнеров .

Напишите код в приложении для извлечения сведений о продукте для вашего приложения или надстройки, предлагаемой приложением, а затем определите, активна ли лицензия (то есть имеется ли у пользователя лицензия на использование приложения или надстройки). Если лицензия неактивна, отобразите пользовательский интерфейс, предлагающий приложение или надстройку для продажи пользователю в качестве покупки из приложения.

Если пользователь решает приобрести ваше приложение или надстройку, используйте для покупки продукта соответствующий метод.

• Если пользователь покупает приложение или надстройку для долгосрочного использования, следуйте указаниям в разделе Включение покупок из приложений для приложений и надстроек.
• Если пользователь покупает потребляемую надстройку, следуйте инструкциям в разделе Включение покупок потребляемых надстроек.
• Если пользователь покупает надстройку с подпиской, следуйте указаниям в разделе Включение надстроек с подпиской для приложения.

Проверьте реализацию, следуя руководству по тестированию в этой статье.

Чтобы исключить или ограничить функции в пробной версии приложения с помощью пространства имен Windows.Services.Store, выполните следующие действия:

Исключите или ограничьте определенные функции приложения, если это пробная версия, а затем включите их, если пользователь приобретет полную лицензию. Дополнительные сведения и пример кода см. в разделе Внедрение пробной версии приложения.

Проверьте реализацию, следуя руководству по тестированию в этой статье.

Если ваше приложение использует API-интерфейсы в пространстве имен Windows.Services.Store для реализации покупок из приложения и пробного периода, вам необходимо опубликовать приложение в Microsoft Store и скачать его на свое устройство разработки, чтобы использовать его лицензию для тестирования. Выполните следующие действия, чтобы протестировать код.

Если ваше приложение еще не опубликовано и доступно в Магазине, убедитесь, что ваше приложение соответствует минимальным требованиям к комплекту сертификации приложений Windows, отправьте приложение в Центр партнеров и убедитесь, что ваше приложение прошло сертификацию. При необходимости можно настроить приложение, чтобы его нельзя было найти в Магазине, пока вы его тестируете. Обратите внимание на правильную конфигурацию тестовых пакетов. Неправильно настроенные тестовые пакеты могут быть недоступны для скачивания.

Затем убедитесь, что вы выполнили следующие действия:

• Напишите код в приложении, которое использует класс StoreContext и другие связанные типы в пространстве имен Windows.Services.Store, чтобы реализовать функцию покупок из приложения или пробной версии.
• Если ваше приложение предлагает надстройку, которую клиенты могут приобрести, создайте отправку надстройки для вашего приложения в Центре партнеров.
• Если вы хотите исключить или ограничить некоторые функции в пробной версии приложения, настройте приложение в качестве бесплатной пробной версии в Центре партнеров.

Открыв проект в Visual Studio, щелкните Меню проекта, укажите на Магазин и выберите Связать приложение с Магазином. Выполните инструкции мастера, чтобы связать проект приложения с приложением в учетной записи Центра партнеров, которую вы хотите использовать для тестирования.

Если не связать свой проект с приложением в Магазине, методы StoreContext присвоят свойству ExtendedError возвращаемых значений этих методов значение кода ошибки 0x803F6107. Это значение указывает, что Магазин ничего не знает об этом приложении.

Если вы еще не сделали этого, установите приложение из Магазина (см. предыдущий шаг), запустите приложение один раз и затем закройте его. Это гарантирует, что на устройстве разработки установлена действующая лицензия приложения.

Запустите свой проект или начните его отладку в Visual Studio. Код должен извлечь данные приложения и надстройки из приложения Магазина, которое вы связали с локальным проектом. В ответ на предложение переустановить приложение выполните инструкции, а затем запустите свой проект или начните его отладку.

После выполнения этих шагов вы сможете продолжить обновлять код вашего приложения, а затем выполнить отладку обновленного проекта на компьютере для разработки без отправки новых пакетов приложения в Магазин. Чтобы получить локальную лицензию, которая будет использоваться для тестирования, необходимо всего один раз скачать версию вашего приложения в Магазине на ваш компьютер для разработки. Вам всего лишь необходимо отправить новые пакеты приложения в Магазин после завершения тестирования, и когда вам потребуется открыть доступ для пользователей к покупкам из приложения или возможностям пробной версии вашего приложения.

Если ваше приложение использует пространство имен Windows.ApplicationModel.Store, вы можете использовать в своем приложении класс CurrentAppSimulator для моделирования лицензионных сведений во время тестирования перед отправкой приложения в Магазин. Дополнительные сведения см. в начало работы с классами CurrentApp и CurrentAppSimulator.

Пространство имен Windows.Services.Store не предоставляет класс, который можно использовать для имитации лицензионных сведений во время тестирования. Если вы используете пространство имен Windows.Services.Store для реализации покупок из приложения и пробных версий, вам необходимо опубликовать приложение в Магазине и скачать его на свое устройство разработки, чтобы использовать его лицензию для тестирования, как описано выше.

Пространство имен Windows.Services.Store не предоставляет API, который можно использовать для получения чека об успешном совершении покупки, в коде приложения. Это отличается от приложений, использующих пространство имен Windows.ApplicationModel.Store, которое может использовать клиентский API для извлечения чека о выполнении транзакции.

Если функция покупок из приложения реализована с использованием пространства имен Windows.Services.Store и требуется поверить, приобрел ли этот клиент приложение или надстройку, можно воспользоваться запросом метода продуктов в API REST коллекции Microsoft Store. Возвращаемые этим методом данные подтверждают, имеет ли указанный клиент право на использование этого продукта, и предоставляют информацию для транзакции, в которой пользователь приобрел этот продукт. API коллекции Microsoft Store использует для извлечения этой информации аутентификацию Azure AD.

Классические приложения, использующие мост для настольных компьютеров, могут реализовать покупки из приложения и пробную версию с помощью класса StoreContext. Однако если у вас есть классическое приложение Win32 или классическое приложение, которое имеет дескриптор окна (HWND), связанное с платформой отрисовки (например, WPF или Windows App SDK приложение), приложение должно настроить объект StoreContext, чтобы указать, какое окно приложения является окном владельца для модальных диалогов, отображаемых объектом.

Многие участники класса StoreContext (и участники других связанных типов, доступ к которым осуществляется через объект StoreContext) отображают пользователю модальное диалоговое окно для выполнения связанных с Магазином операций, например покупки продукта. Если в классическом приложении не настроен объект StoreContext, чтобы задать владельца окна для модальных диалоговых окон, этот объект будет возвращать неточные данные или ошибки.

Чтобы настроить объект StoreContext в классическом приложении, использующем мост для настольных компьютеров, выполните следующие действия.

Если приложение написано на C# с .NET 6 или более поздней версии, выполните следующие действия.

Убедитесь, что TargetFramework свойство в файле проекта имеет определенную версию пакета SDK Windows, чтобы получить доступ к api среда выполнения Windows, которая предоставляет доступ к пространству имен WinRT.Interop. Пример:

Получите объект StoreContext с помощью метода GetDefault (или GetForUser , если приложение является многопользовательским приложением), как описано выше в этой статье). Чтобы инициализировать диалоговое окно с указанным дескриптором окна, используйте методы WinRT.Interop.WindowNative.GetWindowHandle и WinRT.Interop.InitializeWithWindow.Initialize (см. раздел "Получение дескриптора окна( HWND) и отображение объектов пользовательского интерфейса WinRT, зависящих от CoreWindow).

Если приложение написано с более ранней версией .NET или C++, выполните следующие действия.

Выполните одно из следующих действий, чтобы предоставить приложению доступ к интерфейсу IInitializeWithWindow.

Если приложение написано на управляемом языке, например C# или Visual Basic (до .NET 6), объявите интерфейс IInitializeWithWindow в коде приложения с помощью атрибута ComImport, как показано в следующем C# примере. В этом примере предполагается, что файл кода имеет оператор using для пространства имен System.Runtime.InteropServices.

Если приложение написано на C++, добавьте ссылку на файл заголовка shobjidl.h в коде. Этот файл заголовка содержит объявление интерфейса IInitializeWithWindow.

Получите объект StoreContext, используя метод GetDefault (или метод GetForUser, если ваше приложение является многопользовательским), как описано выше в этой статье, и приведите этот объект к объекту IInitializeWithWindow. Затем вызовите метод IInitializeWithWindow.Initialize и передайте дескриптор окна, которое вы хотите сделать владельцем любых модальных диалоговых окон, которые отображаются методами StoreContext. В следующем C# примере показано, как передать дескриптор главного окна приложения методу. См. также статью Получение дескриптора окна (HWND) и Отображение объектов пользовательского интерфейса WinRT, зависящих от CoreWindow.

Каждый продукт в Магазине имеет по меньшей мере одну SKU, а каждая SKU — по меньшей мере одну доступность. Эти понятия абстрагируются от большинства разработчиков в Центре партнеров, и большинство разработчиков никогда не будут определять номера SKU или доступность для своих приложений или надстроек. Поскольку объектная модель для продуктов из Магазина в пространстве имен Windows.Services.Store все же содержит SKU и доступности, общие сведения об этих понятиях будут вам полезны в некоторых ситуациях.

Некоторые издатели могут определять собственные номера SKU. Например, крупный издатель игр может выпустить игру с одной SKU для стран, где показывать кровь красным запрещено и, следовательно, нужно показать ее зеленым цветом, а другую SKU — чтобы показывать кровь красной в любых странах. Кроме того, издатель, продающий цифровое видеосодержимое, может опубликовать две SKU для видео: одну — для версии высокой четкости, а другую — для версии стандартной четкости.

Все приложения, надстройки и другие продукты в Магазине имеют соответствующий код в Магазине (его также иногда называют кодом продукта в Магазине). Многие API-интерфейсы требуют указания кода продукта в Магазине для выполнения операции с приложением или надстройкой.

Код любого продукта в Магазине — это буквенно-цифровая строка, состоящая из 12 символов, например 9NBLGGH4R315 . Существует несколько различных способов получить код продукта в Магазине для продукта в Магазине.

• Для приложения можно получить идентификатор Магазина на странице удостоверений приложения в Центре партнеров.
• Для надстройки можно получить идентификатор Магазина на странице обзора надстройки в Центре партнеров.
• Для любого продукта вы также можете получить код продукта в Магазине программными средствами с помощью свойства StoreId объекта StoreProduct, представляющего продукт.

Для продуктов с SKU и доступностями каждый объект SKU и доступности также имеют собственные коды продукта в Магазине с различными форматами.

Объект Формат кода продукта в Магазине номер SKU Код продукта в Магазине для SKU имеет формат <product Store ID>/xxxx , где xxxx — это буквенно-цифровая строка из 4 символов, идентифицирующая SKU для продукта. Например, 9NBLGGH4R315/000N . Этот идентификатор возвращается свойством StoreId объекта StoreSku и иногда называется идентификатором хранилища SKU. Доступность Код продукта в Магазине для доступности имеет формат <product Store ID>/xxxx/yyyyyyyyyyyy , где xxxx — это буквенно-цифровая строка из 4 символов, которая определяет SKU для продукта, а yyyyyyyyyyyy — это буквенно-цифровая строка из 12 символов, которая определяет доступность для SKU. Например, 9NBLGGH4R315/000N/4KW6QZD2VN6X . Этот идентификатор возвращается свойством StoreId объекта StoreAvailability и иногда называется идентификатором хранилища доступности.

Как использовать коды продуктов для надстроек в коде

Если вы хотите сделать надстройку доступной для клиентов в контексте приложения, необходимо ввести уникальный идентификатор продукта для надстройки при создании отправки надстройки в Центре партнеров. Этот код продукта можно использовать для отсылки к надстройке в коде, хотя конкретные ситуации, в которых можно использовать код продукта, зависят от того, какое пространство имен используется для покупок из приложения.

Идентификатор продукта, который вы вводите в Центре партнеров для надстройки, отличается от идентификатора магазина надстройки. Идентификатор Магазина создается Центром партнеров.

Если ваше приложение использует пространство имен Windows.Services.Store, можно использовать код продукта для легкой идентификации объекта StoreProduct, представляющего вашу надстройку, или объекта StoreLicense, представляющего лицензию вашей надстройки. Код продукта предоставляется свойствами StoreProduct.InAppOfferToken и StoreLicense.InAppOfferToken.

Несмотря на то что код продукта является полезным средством для идентификации надстройки в коде, большинство операций в пространстве имен Windows.Services.Store используют код продукта в Магазине для надстройки, а не код продукта. Например, для программного извлечения одной или нескольких известных надстроек для приложения, передайте коды продуктов в магазине (а не коды продуктов) для этих надстроек методу GetStoreProductsAsync. Аналогичным образом, чтобы объявить об израсходовании потребляемой надстройки, передайте код продукта в Магазине для этой надстройки (а не код продукта) методу ReportConsumableFulfillmentAsync.

Если приложение использует пространство имен Windows.ApplicationModel.Store, необходимо использовать идентификатор продукта, назначенный надстройке в Центре партнеров для большинства операций. Пример:

Используйте код продукта для идентификации описания ProductListing, представляющего вашу надстройку, или ProductLicense, представляющей лицензию вашей надстройки. Код продукта предоставляется свойствами ProductListing.ProductId и ProductLicense.ProductId.

Укажите код продукта при покупке вашей надстройки для пользователя с помощью метода RequestProductPurchaseAsync. Дополнительные сведения см. в разделе Поддержка покупок внутренних продуктов приложения.

Укажите код продукта при сообщении об израсходовании потребляемой надстройки с помощью метода ReportConsumableFulfillmentAsync. Дополнительные сведения см. в разделе Поддержка покупок потребляемых внутренних продуктов приложения.