应用内购买和试用In-app purchases and trials

Windows SDK 提供可用于实现以下功能的 API,以从通用 Windows 平台 (UWP) 应用获取更多收益:The Windows SDK provides APIs you can use to implement the following features to make more money from your Universal Windows Platform (UWP) app:

  • 应用内购买  无论你的应用是否免费,你都可以直接从应用中销售内容或新的应用功能(例如解锁游戏的下一关卡)。In-app purchases  Whether your app is free or not, you can sell content or new app functionality (such as unlocking the next level of a game) from right within the app.

  • 试用功能  如果你在 Windows 开发人员中心仪表板中将应用配置为免费试用,则可通过在试用期内排除或限制某些功能吸引客户购买应用的完整版。Trial functionality  If you configure your app as a free trial in the Windows Dev Center dashboard, you can entice your customers to purchase the full version of your app by excluding or limiting some features during the trial period. 也可以在客户购买你的应用之前,启用仅在试用期才会出现的某些功能,如横幅或水印。You can also enable features, such as banners or watermarks, that are shown only during the trial, before a customer buys your app.

本文提供应用内购买和试用在 UWP 应用内的工作原理概述。This article provides an overview of how in-app purchases and trials work in UWP apps.

选择要使用哪个命名空间Choose which namespace to use

有两个不同的命名空间可用于向 UWP 应用添加应用内购买和试用功能,具体取决于应用面向 Windows10 的哪个版本。There are two different namespaces you can use to add in-app purchases and trial functionality to your UWP apps, depending on which version of Windows 10 your apps target. 尽管这些命名空间中的 API 用于相同目标,但它们的设计完全不同,并且代码在两个 API 之间并不兼容。Although the APIs in these namespaces serve the same goals, they are designed quite differently, and code is not compatible between the two APIs.

重要

Windows.ApplicationModel.Store 命名空间不再更新新功能,如果可能,建议你的应用改用 Windows.Services.Store 命名空间。The Windows.ApplicationModel.Store namespace is no longer being updated with new features, and we recommend that you use the Windows.Services.Store namespace instead if possible for your app. 在使用桌面桥的 Windows 桌面应用程序或使用开发人员中心开发沙盒的应用或游戏中,Windows.ApplicationModel.Store命名空间不受支持(例如,与 Xbox Live 集成的任何游戏都是这种情况)。The Windows.ApplicationModel.Store namespace is not supported in Windows desktop applications that use the Desktop Bridge or in apps or games that use a development sandbox in Dev Center (for example, this is the case for any game that integrates with Xbox Live).

基本概念Basic concepts

Microsoft Store 中提供的每一个项目通常称为产品Every item that is offered in the Store is generally called a product. 大多数开发人员只处理以下类型的产品:应用加载项Most developers only work with the following types of products: apps and add-ons.

加载项是指你在应用的上下文中向客户提供的产品或功能:例如,要在应用或游戏中使用的货币、游戏的新地图或武器、使用无广告应用的功能,或数字内容,如应用的音乐或视频(前提是应用能够提供此类内容)。An add-on is a product or feature that you make available to your customers in the context of your app: for example, currency to be used in an app or game, new maps or weapons for a game, the ability to use your app without ads, or digital content such as music or videos for apps that have the ability to offer that type of content. 每个应用和加载项都有关联的许可证,用于指示用户是否有权使用该应用或加载项。Every app and add-on has an associated license that indicates whether the user is entitled to use the app or add-on. 如果用户有权将该应用或加载项作为试用来使用,则许可证还提供关于该试用的其他信息。If the user is entitled to use the app or add-on as a trial, the license also provides additional info about the trial.

若要在应用中向客户提供加载项,必须在开发人员中心仪表板中为应用定义加载项以便使 Microsoft Store 知道它。To offer an add-on to customers in your app, you must define the add-on for your app in the Dev Center dashboard so the Store knows about it. 然后,应用可以使用 Windows.Services.StoreWindows.ApplicationModel.Store 命名空间中的 API 提供加载项,作为应用内购买向用户销售。Then, your app can use APIs in the Windows.Services.Store or Windows.ApplicationModel.Store namespace to offer the add-on for sale to the user as an in-app purchase.

UWP 应用可提供以下类型的加载项。UWP apps can offer the following types of add-ons.

加载项类型Add-on type 说明Description
耐用品Durable 持续时间为你在 Windows 开发人员仪表板中所指定生存期的加载项。An add-on that persists for the lifetime that you specify in the Windows Dev Center dashboard.

默认情况下,耐用型加载项永远不会过期,在此情况下只能购买它们一次。By default, durable add-ons never expire, in which case they can only be purchased once. 如果你为加载项指定特定的持续时间,则用户可以在它过期后重新购买该加载项。If you specify a particular duration for the add-on, the user can repurchase the add-on after it expires.

开发人员管理的易耗品Developer-managed consumable 可以购买、使用并在用完后再次购买的加载项。An add-on that can be purchased, used, and then purchased again after it is consumed. 你负责跟踪用户拥有的加载项所表示商品的余量。You are responsible for keeping track of the user's balance of items that the add-on represents.

当用户使用与该加载项关联的任何商品时,你负责维护加载项所表示的商品的用户余量,并在用户消耗完所有商品后向 Microsoft Store 将加载项购买报告为已完成。When the user consumes any items that are associated with the add-on, you are responsible for maintaining the user's balance and for reporting the purchase of the add-on as fulfilled to the Store after the user has consumed all the items. 在你的应用将之前的加载项购买报告为已完成前,用户无法再次购买该加载项。The user cannot purchase the add-on again until your app has reported the previous add-on purchase as fulfilled.

例如,如果你的加载项表示游戏中的 100 个硬币,并且用户消耗了 10 个硬币,则你的用户或服务必须为该用户保留 90 个硬币的新剩余余额。For example, if your add-on represents 100 coins in a game and the user consumes 10 coins, your app or service must maintain the new remaining balance of 90 coins for the user. 在用户消耗完全部 100 个硬币后,你的应用必须将加载项报告为已完成,然后用户才可以再次购买 100 个硬币的加载项。After the user has consumed all 100 coins, your app must report the add-on as fulfilled, and then the user can purchase the 100 coin add-on again.

Microsoft Store 管理的易耗品Store-managed consumable 可以随时购买、使用并再次购买的加载项。An add-on that can be purchased, used, and purchased again at any time. Microsoft Store 会跟踪用户拥有的加载项所表示商品的余量。The Store keeps track of the user's balance of items that the add-on represents.

当用户消耗任何与加载项关联的商品时,你负责向 Microsoft Store 报告这些商品已完成,然后 Microsoft Store 会更新用户的余量。When the user consumes any items that are associated with the add-on, you are responsible for reporting those items as fulfilled to the Store, and the Store updates the user's balance. 用户可以根据需要多次购买加载项(他们不需要首先使用这些项目)。The user can purchase the add-on as many times as they want (they do not need to consume the items first). 你的应用可以随时查询用户的当前余量。Your app can query for the current balance for the user at any time.

例如,如果你的加载项在游戏中表示 100 个硬币的初始数量,并且用户消耗了 50 个硬币,则你的应用将向 Microsoft Store 报告 50 个单位的加载项已完成,然后 Microsoft Store 会更新剩余余额。For example, if your add-on represents an initial quantity of 100 coins in a game and the user consumes 50 coins, your app reports to the Store that 50 units of the add-on were fulfilled, and the Store updates the remaining balance. 如果用户再次购买你的加载项(增加 100 个硬币),他们现在总共有 150 个硬币。If the user then repurchases your add-on to acquire 100 more coins, they will now have 150 coins total.

注意  若要使用 Microsoft Store 管理的易耗品,应用必须在 Visual Studio 中面向 Windows 10 周年纪念版(10.0;版本 14393) 或更高版本,并且必须使用 Windows.Services.Store 命名空间,而不是 Windows.ApplicationModel.Store 命名空间。Note  To use Store-managed consumables, your app must target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio, and it must use the Windows.Services.Store namespace instead of the Windows.ApplicationModel.Store namespace.

订阅Subscription 一种持久型加载项,客户需要按重复时间间隔付费才能继续使用此加载项。A durable add-on where the customer continues to be charged at recurring intervals in order to keep using the add-on. 客户可以随时取消订阅,以免日后继续产生费用。The customer can cancel the subscription at any time to avoid further charges.

注意  若要使用订阅加载项,应用必须在 Visual Studio 中面向 Windows 10 周年纪念版(10.0;版本 14393) 或更高版本,并且必须使用 Windows.Services.Store 命名空间,而不是 Windows.ApplicationModel.Store 命名空间。Note  To use subscription add-ons, your app must target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio, and it must use the Windows.Services.Store namespace instead of the Windows.ApplicationModel.Store namespace.

备注

其他类型的加载项,如使用软件包的耐用型加载项(也称为可下载内容或 DLC),仅适用于有限的开发人员群体,本文档中未涉及。Other types of add-ons, such as durable add-ons with packages (also known as downloadable content or DLC) are only available to a restricted set of developers, and are not covered in this documentation.

使用 Windows.Services.Store 命名空间的应用内购买和试用In-app purchases and trials using the Windows.Services.Store namespace

此部分概述了 Windows.Services.Store 命名空间的重要任务和概念。This section provides an overview of important tasks and concepts for the Windows.Services.Store namespace. 此命名空间仅适用于面向 Visual Studio 中的 Windows 10 周年纪念版(10.0;版本 14393) 或更高版本的应用(这对应于 Windows 10 版本 1607)。This namespace is available only to apps that target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio (this corresponds to Windows 10, version 1607). 我们建议应用使用 Windows.Services.Store 命名空间,而非使用 Windows.ApplicationModel.Store 命名空间(如可能)。We recommend that apps use the Windows.Services.Store namespace instead of the Windows.ApplicationModel.Store namespace if possible. 有关 Windows.ApplicationModel.Store 命名空间的信息,请参阅本文For information about the Windows.ApplicationModel.Store namespace, see this article.

本部分内容In this section

视频Video

请观看下面的视频,了解如何在你的应用中使用 Windows.Services.Store 命名空间实现应用内购买。Watch the following video for an overview of how to implement in-app purchases in your app using the Windows.Services.Store namespace.

StoreContext 类入门Get started with the StoreContext class

Windows.Services.Store 命名空间的主要入口点是 StoreContext 类。The main entry point to the Windows.Services.Store namespace is the StoreContext class. 此类提供的方法可用于获取当前应用及其可用加载项的信息、获取当前应用或其加载项的许可证信息、为当前用户购买应用或加载项以及执行其他任务。This class provides methods you can use to get info for the current app and its available add-ons, get license info for the current app or its add-ons, purchase an app or add-on for the current user, and perform other tasks. 若要获取 StoreContext 对象,请执行以下操作之一:To get a StoreContext object, do one of the following:

  • 在单用户应用(即,仅在启动该应用的用户上下文中运行的应用),使用静态 GetDefault 方法获取一个 StoreContext 对象,你可以使用该对象访问与用户的 Microsoft Store 相关数据。In a single-user app (that is, an app that runs only in the context of the user that launched the app), use the static GetDefault method to get a StoreContext object that you can use to access Microsoft Store-related data for the user. 大多数通用 Windows 平台 (UWP) 应用是单用户应用。Most Universal Windows Platform (UWP) apps are single-user apps.

    Windows.Services.Store.StoreContext context = StoreContext.GetDefault();
    
  • 多用户应用中,使用静态 GetForUser 方法获取一个 StoreContext 对象,你可以使用该对象访问特定用户(使用该应用时使用 Microsoft 帐户登录的用户)的 Microsoft Store 相关数据。In a multi-user app, use the static GetForUser method to get a StoreContext object that you can use to access Microsoft Store-related data for a specific user who is signed in with their Microsoft account while using the app. 以下示例为第一个可用用户获取 StoreContext 对象。The following example gets a StoreContext object for the first available user.

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

备注

使用桌面桥的 Windows 桌面应用程序必须执行额外步骤来配置 StoreContext 对象,然后才可以使用此对象。Windows desktop applications that use the Desktop Bridge must perform additional steps to configure the StoreContext object before they can use this object. 有关详情,请参阅本部分For more information, see this section.

拥有 StoreContext 对象后,可开始调用此对象的方法来获取当前应用以及加载项的 Microsoft Store 产品信息、检索当前应用及其加载项的许可证信息、为当前用户购买应用或加载项以及执行其他任务。After you have a StoreContext object, you can start calling methods of this object to get Store product info for the current app and its add-ons, retrieve license info for the current app and its add-ons, purchase an app or add-on for the current user, and perform other tasks. 有关可使用此对象执行的常见任务的详细信息,请参阅以下文章:For more information about common tasks you can perform using this object, see the following articles:

有关演示如何使用 StoreContextWindows.Services.Store 命名空间中的其他类型的示例应用,请参阅 Microsoft Store 示例For a sample app that demonstrates how to use StoreContext and other types in the Windows.Services.Store namespace, see the Store sample.

实现应用内购买Implement in-app purchases

若要使用 Windows.Services.Store 命名空间在应用中向客户提供应用内购买:To offer an in-app purchase to customers in your app using the Windows.Services.Store namespace:

  1. 如果应用提供可供客户购买的加载项,请在开发人员中心仪表板中为应用创建加载项提交If your app offers add-ons that customers can purchase, create add-on submissions for your app in the Dev Center dashboard.

  2. 在应用中编写代码以检索应用或应用提供的加载项的产品信息,然后确定许可证是否处于活动状态(即,用户是否具有使用该应用或加载项的许可证)。Write code in your app to retrieve product info for your app or an add-on offered by your app and then determine whether the license is active (that is, whether the user has a license to use the app or add-on). 如果许可证不处于活动状态,请显示提供应用或加载项以作为应用内购买向用户销售的 UI。If the license isn't active, display a UI that offers the app or add-on for sale to the user as an in-app purchase.

  3. 如果用户选择购买应用或加载项,请使用相应的方法购买该产品:If the user chooses to purchase your app or add-on, use the appropriate method to purchase the product:

  4. 按照本文中的测试指南测试实现。Test your implementation by following the testing guidance in this article.

实现试用功能Implement trial functionality

若要使用 Windows.Services.Store 命名空间排除或限制应用的试用版中的功能:To exclude or limit features in a trial version of your app using the Windows.Services.Store namespace:

  1. 在 Windows 开发人员中心仪表板中将应用配置为免费试用Configure your app as a free trial in the Windows Dev Center dashboard.

  2. 在应用中编写代码以检索应用或应用提供的加载项的产品信息,然后确定与应用关联的许可证是否是试用许可证Write code in your app to retrieve product info for your app or an add-on offered by your app and then determine whether the license associated with the app is a trial license.

  3. 如果是试用,则排除或限制应用中的特定功能,然后在用户购买完整许可证时启用这些功能。Exclude or limit certain features in your app if it is a trial, and then enable the features when the user purchases a full license. 有关详细信息和代码示例,请参阅实现应用的试用版For more information and a code example, see Implement a trial version of your app.

  4. 按照本文中的测试指南测试实现。Test your implementation by following the testing guidance in this article.

测试你的应用内购买或试用实现Test your in-app purchase or trial implementation

如果你的应用使用 Windows.Services.Store 命名空间中的 API 实现应用内购买和试用功能,则你必须将应用发布到 Microsoft Store,然后将此应用下载到开发设备上以使用其许可证进行测试。If your app uses APIs in the Windows.Services.Store namespace to implement in-app purchase or trial functionality, you must publish your app to the Store and download the app to your development device to use its license for testing. 请按照下述过程测试你的代码:Follow this process to test your code:

  1. 如果应用尚未在 Microsoft Store 中发布和可用,请确保应用满足 Windows 应用认证工具包最低要求、将应用提交到 Windows 开发人员中心仪表板,并确保应用通过认证过程。If your app is not yet published and available in the Store, make sure your app meets the minimum Windows App Certification Kit requirements, submit your app to the Windows Dev Center dashboard, and make sure your app passes the certification process. 在测试应用期间,你可以将应用配置为在 Microsoft Store 中隐藏You can configure your app so it is not discoverable in the Store while you test it.

  2. 接下来,确保已完成以下操作:Next, make sure you have completed the following:

  3. 在项目在 Visual Studio 中打开的情况下,单击项目菜单、指向** Microsoft Store,然后单击将应用与 Microsoft Store 关联With your project open in Visual Studio, click the **Project menu, point to Store, and then click Associate App with the Store. 完成向导中的说明以将应用项目与 Windows 开发人员中心帐户中要用于测试的应用关联。Complete the instructions in the wizard to associate the app project with the app in your Windows Dev Center account that you want to use for testing.

    备注

    如果你未将项目与 Microsoft Store 中的应用关联,则 StoreContext 方法会将其返回值的 ExtendedError 属性设置为错误代码值 0x803F6107。If you do not associate your project with an app in the Store, the StoreContext methods set the ExtendedError property of their return values to the error code value 0x803F6107. 此值指示 Microsoft Store 并不了解关于该应用的任何信息。This value indicates that the Store doesn't have any knowledge about the app.

  4. 如果你尚未关联,请从 Microsoft Store 安装你在上一步中指定的应用、运行该应用一次,然后关闭此应用。If you have not done so already, install the app from the Store that you specified in the previous step, run the app once, and then close this app. 这可确保将应用的有效许可证安装到你的开发设备。This ensures that a valid license for the app is installed to your development device.

  5. 在 Visual Studio 中,开始运行或调试你的项目。In Visual Studio, start running or debugging your project. 你的代码应从与你的本地项目关联的 Microsoft Store 应用中检索应用和加载项数据。Your code should retrieve app and add-on data from the Store app that you associated with your local project. 如果系统提示你重新安装该应用,请按照说明操作,然后运行或调试项目。If you are prompted to reinstall the app, follow the instructions and then run or debug your project.

    备注

    完成这些步骤后,你可以继续更新应用代码并在开发计算机上调试更新的项目,而无需将新的应用包提交到 Microsoft Store。After you complete these steps, you can continue to update your app's code and then debug your updated project on your development computer without submitting new app packages to the Store. 获取将要用于测试的本地许可证后,只需要将应用的 Microsoft Store 版本下载到开发计算机。You only need to download the Store version of your app to your development computer once to obtain the local license that will be used for testing. 完成测试后,只需要将新的应用包提交到 Microsoft Store,并允许客户使用应用内购买或应用中的试用相关功能。You only need to submit new app packages to the Store after you complete your testing and you want to make the in-app purchase or trial-related features in your app available to your customers.

如果你的应用使用的是 Windows.ApplicationModel.Store 命名空间,则在将应用提交到 Microsoft Store 之前,你可以在应用中使用 CurrentAppSimulator 类模拟许可证信息进行测试。If your app uses the Windows.ApplicationModel.Store namespace, you can use the CurrentAppSimulator class in your app to simulate license info during testing before you submit your app to the Store. 有关详细信息,请参阅开始使用 CurrentApp 和 CurrentAppSimulator 类For more information, see Get started with the CurrentApp and CurrentAppSimulator classes.

备注

Windows.Services.Store 命名空间不提供可用于在测试期间模拟许可证信息的类。The Windows.Services.Store namespace does not provide a class that you can use to simulate license info during testing. 如果使用 Windows.Services.Store 命名空间实现应用内购买或试用,你必须将应用发布到 Microsoft Store,然后将此应用下载到开发设备上以使用其许可证进行测试(如上所述)。If you use the Windows.Services.Store namespace to implement in-app purchases or trials, you must publish your app to the Store and download the app to your development device to use its license for testing as described above.

应用内购买的收据Receipts for in-app purchases

Windows.Services.Store 命名空间不在应用代码中提供可用于获取成功购买的交易收据的 API。The Windows.Services.Store namespace does not provide an API you can use to obtain a transaction receipt for successful purchases in your app's code. 这是与使用 Windows.ApplicationModel.Store 命名空间的应用不同的体验,该命名空间可使用客户端 API 检索交易收据This is a different experience from apps that use the Windows.ApplicationModel.Store namespace, which can use a client-side API to retrieve a transaction receipt.

如果使用 Windows.Services.Store 命名空间实现应用内购买并且希望验证给定客户是否已购买某个应用或加载项,可使用 Microsoft Store collection REST API 中的查询产品方法If you implement in-app purchases using the Windows.Services.Store namespace and you want to validate whether a given customer has purchased an app or add-on, you can use the query for products method in the Microsoft Store collection REST API. 此方法的返回数据确认指定客户是否具有对给定产品的权利,并为用户获取产品的交易提供数据。The return data for this method confirms whether the specified customer has an entitlement for a given product, and provides data for the transaction in which the user acquired the product. Microsoft Store 收集 API 使用 Azure AD 身份验证检索此信息。The Microsoft Store collection API uses Azure AD authentication to retrieve this information.

通过桌面桥使用 StoreContext 类Using the StoreContext class with the Desktop Bridge

使用桌面桥的桌面应用程序可使用 StoreContext 类实现应用内购买和试用。Desktop applications that use the Desktop Bridge can use the StoreContext class to implement in-app purchases and trials. 但是,如果你有 Win32 桌面应用程序或具有与呈现框架(如 WPF 应用程序)相关联的窗口句柄 (HWND) 的桌面应用程序,则该应用程序必须配置 StoreContext 对象以为该对象所显示的模式对话框指定哪个应用程序窗口是所有者窗口。However, if you have a Win32 desktop application or a desktop application that has a window handle (HWND) that is associated with the rendering framework (such as a WPF application), your application must configure the StoreContext object to specify which application window is the owner window for modal dialogs that are shown by the object.

许多 StoreContext 成员(以及通过 StoreContext 对象访问的其他相关类型的成员)针对 Microsoft Store 相关的操作(如购买产品)向用户显示模式对话框。Many StoreContext members (and members of other related types that are accessed through the StoreContext object) display a modal dialog to the user for Store-related operations such as purchasing a product. 如果桌面应用程序未配置 StoreContext 对象以指定模式对话框的所有者窗口,则此对象将返回不准确的数据或错误。If a desktop application does not configure the StoreContext object to specify the owner window for modal dialogs, this object will return inaccurate data or errors.

若要在使用桌面桥的桌面应用程序中配置 StoreContext 对象,请按照这些步骤操作。To configure a StoreContext object in a desktop application that uses the Desktop Bridge, follow these steps.

  1. 进行以下操作之一,使你的应用可以访问 IInitializeWithWindow 接口:Do one of the following to enable your app to access the IInitializeWithWindow interface:

    • 如果应用程序使用托管语言(如 C# 或 Visual Basic)编写,则在应用代码中使用 ComImport 属性声明 IInitializeWithWindow 接口,如以下 C# 示例所示。If your application is written in a managed language such as C# or Visual Basic, declare the IInitializeWithWindow interface in your app's code with the ComImport attribute as shown in the following C# example. 此示例假设代码文件具有 System.Runtime.InteropServices 命名空间的 using 语句。This example assumes that your code file has a using statement for the System.Runtime.InteropServices namespace.

      [ComImport]
      [Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1")]
      [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
      public interface IInitializeWithWindow
      {
          void Initialize(IntPtr hwnd);
      }
      
    • 如果应用程序是采用 C++ 编写的,请在代码中添加对 shobjidl.h 头文件的引用。If your application is written in C++, add a reference to the shobjidl.h header file in your code. 此头文件包含 IInitializeWithWindow 接口的声明。This header file contains the declaration of the IInitializeWithWindow interface.

  2. 按照本文前面部分所述,使用 GetDefault 方法(或 GetForUser,如果你的应用是多用户应用)获取 StoreContext 对象并将此对象转换为 IInitializeWithWindow 对象。Get a StoreContext object by using the GetDefault method (or GetForUser if your app is a multi-user app) as described earlier in this article, and cast this object to an IInitializeWithWindow object. 然后,调用 IInitializeWithWindow.Initialize 方法,并传递你希望成为所有者(对于 StoreContext 方法显示的任何模式对话框)的窗口的句柄。Then, call the IInitializeWithWindow.Initialize method, and pass the handle of the window that you want to be the owner for any modal dialogs that are shown by StoreContext methods. 以下示例 C# 显示如何将应用主窗口的句柄传递到该方法。The following C# example shows how to pass the handle of your app's main window to the method.

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

产品、SKU 和可用性Products, SKUs, and availabilities

Microsoft Store 中的每个产品都至少有一个 SKU,而每个 SKU 都至少有一个可用性Every product in the Store has at least one SKU, and each SKU has at least one availability. 这些概念抽象自 Windows 开发人员中心仪表板中的大多数开发人员,并且大多数开发人员永远不需要为其应用或加载项定义 SKU 或可用性。These concepts are abstracted away from most developers in the Windows Dev Center dashboard, and most developers will never define SKUs or availabilities for their apps or add-ons. 但是,由于 Windows.Services.Store 命名空间中的 Microsoft Store 产品的对象模型包括 SKU 和可用性,因此大致了解这些概念对于某些情况可能很有帮助。However, because the object model for Store products in the Windows.Services.Store namespace includes SKUs and availabilities, a basic understanding of these concepts can be helpful for some scenarios.

对象Object 说明Description
产品Product 产品是指在 Microsoft Store 中提供的任何类型的产品,包括应用或加载项。A product refers to any type of product that is available in the Store, including an app or add-on.

Microsoft Store 中的每个产品都有相应的 StoreProduct 对象。Each product in the Store has a corresponding StoreProduct object. 此类提供可用于访问数据的属性,如产品的 Store ID、Store 一览的图像和视频以及定价信息。This class provides properties you can use to access data such as the Store ID of the product, the images and videos for the Store listing, and pricing info. 它还提供可用于购买产品的方法。It also provides methods you can use to purchase the product.

SKUSKU SKU 是带有其自己的说明、价格和其他独特产品详细信息的产品特定版本。A SKU is a specific version of a product with its own description, price, and other unique product details. 每个应用或加载项都有默认的 SKU。Each app or add-on has a default SKU. 大多数开发人员拥有针对一个应用的多个 SKU 的唯一情况是,他们要发布应用的完整版和试用版(在 Microsoft Store 目录中,其中每一个版本都是同一个应用的不同 SKU)。The only time most developers will ever have multiple SKUs for an app is if they publish a full version of their app and a trial version (in the Store catalog, each of these versions is a different SKU of the same app).

某些发布者能够定义他们自己的 SKU。Some publishers have the ability to define their own SKUs. 例如,大型游戏发布者可能发布具有以下两个 SKU 的游戏:一个 SKU 在不允许红色血液的市场中显示绿色血液,另一个 SKU 在所有其他市场中显示红色血液。For example, a large game publisher might release a game with one SKU that shows green blood in markets that don't allow red blood and a different SKU that shows red blood in all other markets. 另外,销售数字视频内容的发布者可能针对一个视频发布两个 SKU,一个 SKU 用于高清版本,另一个 SKU 用于标清版本。Alternatively, a publisher who sells digital video content might publish two SKUs for a video, one SKU for the high-definition version and a different SKU for the standard-definition version.

Microsoft Store 中的每个 SKU 都有相应的 StoreSku 对象。Each SKU in the Store has a corresponding StoreSku object. 每个 StoreProduct 都有可用于访问产品 SKU 的 Skus 属性。Every StoreProduct has a Skus property you can use to access the SKUs for the product.

可用性Availability 可用性是带有自己独特定价信息的 SKU 的特定版本。An availability is a specific version of a SKU with its own unique pricing info. 每个 SKU 都有默认的可用性。Each SKU has a default availability. 某些发布者能够定义他们自己的可用性来为给定 SKU 引入不同的价格选项。Some publishers have the ability to define their own availabilities to introduce different price options for a given SKU.

Microsoft Store 中的每个可用性都有相应的 StoreAvailability 对象。Each availability in the Store has a corresponding StoreAvailability object. 每个 StoreSku 都有可用于访问 SKU 可用性的 Availabilities 属性。Every StoreSku has an Availabilities property you can use to access the availabilities for the SKU. 对于大多数开发人员来说,每个 SKU 都有单个默认可用性。For most developers, each SKU has a single default availability.

Store IDStore IDs

Microsoft Store 中的每个应用、加载项或其他产品都有关联的** Store ID(有时也称为产品 Store ID)。Every app, add-on, or other product in the Store has an associated **Store ID (this is also sometimes called a product Store ID). 许多 API 都需要 Store ID 才能执行有关应用或加载项的操作。Many APIs require the Store ID in order to perform an operation on an app or add-on.

Microsoft Store 中的任何产品的 Store ID 都是 12 个字符的字母数字字符串,例如 9NBLGGH4R315The Store ID of any product in the Store is 12-character alpha-numeric string, such as 9NBLGGH4R315. 有多种不同的方法可用于获取 Microsoft Store 中某个产品的 Store ID:There are several different ways to get the Store ID for a product in the Store:

  • 对于应用,你可以在开发人员中心仪表板的应用标识页上获取 Store ID。For an app, you can get the Store ID on the App identity page of the Dev Center dashboard.
  • 对于加载项,你可以在开发人员仪表板的加载项概述页面上获取 Store ID。For an add-on, you can get the Store ID on the add-on's overview page in the dashboard.
  • 对于任何产品,还可以使用表示此产品的 StoreProduct 对象的 StoreId 属性以编程方式获取 Store ID。For any product, you can also get the Store ID programmatically by using the StoreId property of the StoreProduct object that represents the product.

对于具有 SKU 和可用性的产品,SKU 和可用性还有自己的具有不同格式的 Store ID。For products with SKUs and availabilities, the SKUs and availabilities also have their own Store IDs with different formats.

对象Object Store ID 格式Store ID format
SKUSKU 对于 SKU,Store ID 的格式为 <product Store ID>/xxxx,其中 xxxx 是 4 个字符的字母数字字符串,用于标识产品的 SKU。The Store ID for a SKU has the format <product Store ID>/xxxx, where xxxx is a 4-character alpha-numeric string that identifies a SKU for the product. 例如,9NBLGGH4R315/000NFor example, 9NBLGGH4R315/000N. 此 ID 由 StoreSku 对象的 StoreId 属性返回,并且有时称为 SKU Store IDThis ID is returned by the StoreId property of a StoreSku object, and it is sometimes called the SKU Store ID.
可用性Availability 对于可用性,Store ID 的格式为 <product Store ID>/xxxx/yyyyyyyyyyyy,其中 xxxx 是标识产品 SKU 的 4 字符数字字母字符串,而 yyyyyyyyyyyy 是标识 SKU 可用性的 12 字符字母数字字符串。The Store ID for an availability has the format <product Store ID>/xxxx/yyyyyyyyyyyy, where xxxx is a 4-character alpha-numeric string that identifies a SKU for the product and yyyyyyyyyyyy is a 12-character alpha-numeric string that identifies an availability for the SKU. 例如,9NBLGGH4R315/000N/4KW6QZD2VN6XFor example, 9NBLGGH4R315/000N/4KW6QZD2VN6X. 此 ID 由 StoreAvailability 对象的 StoreId 属性返回,并且有时称为可用性 Store IDThis ID is returned by the StoreId property of a StoreAvailability object, and it is sometimes called the availability Store ID.

如何在代码中使用加载项的产品 IDHow to use product IDs for add-ons in your code

如果要在应用上下文中向客户提供加载项,你必须在开发人员中心仪表板中创建加载项提交时为加载项输入唯一产品 IDIf you want to make an add-on available to your customers in the context of your app, you must enter a unique product ID for your add-on when you create your add-on submission in the Dev Center dashboard. 你可以使用此产品 ID 在代码中引用加载项,但可以使用产品 ID 的特定方案取决于你在应用中实现应用内购买所用的命名空间。You can use this product ID to refer to the add-on in your code, although the specific scenarios in which you can use the product ID depend on which namespace you use for in-app purchases in your app.

备注

你在开发人员中心仪表板中为加载项输入的产品 ID 不同于此加载项的 Store IDThe product ID that you enter in the Dev Center dashboard for an add-on is different than the add-on's Store ID. Store ID 由开发人员中心生成。The Store ID is generated by Dev Center.

使用 Windows.Services.Store 命名空间的应用Apps that use the Windows.Services.Store namespace

如果应用使用的是 Windows.Services.Store 命名空间,你可以借助产品 ID 轻松识别表示加载项的 StoreProduct 或表示加载项许可证的 StoreLicenseIf your app uses the Windows.Services.Store namespace, you can use the product ID to easily identify the StoreProduct that represents your add-on or the StoreLicense that represents your add-on's license. 产品 ID 由 StoreProduct.InAppOfferTokenStoreLicense.InAppOfferToken 属性公开。The product ID is exposed by the StoreProduct.InAppOfferToken and StoreLicense.InAppOfferToken properties.

备注

虽然产品 ID 是在代码中识别加载项的有用方式,但 Windows.Services.Store 命名空间中的大多数操作使用的是加载项的 Store ID,而不是产品 ID。Although the product ID is a useful way to identify an add-on in your code, most operations in the Windows.Services.Store namespace use the Store ID of an add-on instead of the product ID. 例如,要以编程方式检索某应用的一个或多个已知加载项,可以向 GetStoreProductsAsync 方法传递加载项的 Store ID(而不是产品 ID)。For example, to programmatically retrieve one or more known add-ons for an app, pass the Store IDs (rather than the product IDs) of the add-ons to the GetStoreProductsAsync method. 同样,要报告易耗型加载项已完成,可以向 ReportConsumableFulfillmentAsync 方法传递加载项的 Store ID(而不是产品 ID)。Similarly, to report a consumable add-on as fulfilled, pass the Store ID of the add-on (rather than the product ID) to the ReportConsumableFulfillmentAsync method.

使用 Windows.ApplicationModel.Store 命名空间的应用Apps that use the Windows.ApplicationModel.Store namespace

如果应用使用的是 Windows.ApplicationModel.Store 命名空间,你需要使用自己在开发人员中心仪表板中向加载项分配的产品 ID 来进行大多数操作。If your app uses the Windows.ApplicationModel.Store namespace, you'll need to use the product ID that you assign to an add-on in the Dev Center dashboard for most operations. 例如:For example: