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

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

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

В этом разделе

• Видео
• Начало работы с классом StoreContext
• Реализация покупок в приложении
• Реализация функциональных возможностей пробной версии
• Протестируйте покупку в приложении или пробную версию
• чеки за покупки внутри приложения
• Использование класса StoreContext с Desktop Bridge
• Продукты, номера SKU и доступность
• идентификаторы магазинов

Начало работы с классом StoreContext

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

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

  Windows.Services.Store.StoreContext context = StoreContext.GetDefault();
  

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

  var users = await Windows.System.User.FindAllAsync();
  Windows.Services.Store.StoreContext context = StoreContext.GetForUser(users[0]);
  

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

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

Пример приложения, демонстрирующего использование StoreContext и других типов в пространстве имен Windows.Services.Store, см. в примере Магазина.

Реализация покупок в приложении

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

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

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

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

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

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

Реализация функциональных возможностей пробной версии

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

1. Настройте своё приложение как бесплатную пробную версию в Центре партнеров.

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

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

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

Тестирование реализации покупки или пробной версии в приложении

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

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

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

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

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

   Замечание

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

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

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

   Замечание

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

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

Квитанции для покупок в приложении

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

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

Использование класса StoreContext с мостом для настольных компьютеров

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

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

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

Для .NET 6 или более поздней версии

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

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

   <PropertyGroup>
     <!-- You can also target other versions of the Windows SDK and .NET, e.g. "net6.0-windows10.0.19041.0" -->
     <TargetFramework>net6.0-windows10.0.22000.0</TargetFramework>
   </PropertyGroup>
   

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

   StoreContext context = StoreContext.GetDefault();
   // Obtain window handle by passing in pointer to the window object
   var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(windowObject);
   // Initialize the dialog using wrapper function for IInitializeWithWindow
   WinRT.Interop.InitializeWithWindow.Initialize(context, hwnd); 
   

Для более ранних версий .NET или C++

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

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

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

     [ComImport]
     [Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1")]
     [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
     public interface IInitializeWithWindow
     {
         void Initialize(IntPtr hwnd);
     }
     

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

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

   StoreContext context = StoreContext.GetDefault();
   IInitializeWithWindow initWindow = (IInitializeWithWindow)(object)context;
   initWindow.Initialize(System.Diagnostics.Process.GetCurrentProcess().MainWindowHandle);
   

Продукты, номера SKU и доступность

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

Идентификаторы магазина

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

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

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

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

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

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

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

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

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

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

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

• Укажите идентификатор продукта при покупке дополнения для пользователя с помощью метода RequestProductPurchaseAsync. Дополнительные сведения см. в разделе Включение покупок в приложении.

• Укажите идентификатор продукта при отчете о используемой надстройке как выполненной с помощью метода ReportConsumableFulfillmentAsync. Дополнительные сведения см. в разделе Включение покупок продуктов в приложении.

Связанные темы

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