啟用消費性附加元件購買Enable consumable add-on purchases

本文章示範如何使用 Windows.Services.Store 命名空間中 StoreContext 類別的方法,來管理使用者如何在您的 UWP app 中完成消費性附加元件。This article demonstrates how to use methods of the StoreContext class in the Windows.Services.Store namespace to manage the user's fulfillment of consumable add-ons in your UWP apps. 請針對可購買、使用,然後再次購買的項目使用消費性附加元件。Use consumable add-ons for items that can be purchased, used, and purchased again. 這對於像遊戲內貨幣 (金幣、錢幣等) 這種可在買來後用來購買特定火力升級配備的東西,特別有用。This is especially useful for things like in-game currency (gold, coins, etc.) that can be purchased and then used to purchase specific power-ups.

注意

Windows.Services.Store 命名空間在 Windows 10 (版本 1607) 中引進,只適用於目標為 Visual Studio 中 Windows 10 Anniversary Edition (10.0;組建 14393) 或更新版本的專案。The Windows.Services.Store namespace was introduced in Windows 10, version 1607, and it can only be used in projects that target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio. 如果您的 app 目標為較早版本的 Windows 10,您必須使用 Windows.ApplicationModel.Store 命名空間,而不是 Windows.Services.Store 命名空間。If your app targets an earlier version of Windows 10, you must use the Windows.ApplicationModel.Store namespace instead of the Windows.Services.Store namespace. 如需詳細資訊,請參閱這篇文章For more information, see this article.

消費性附加元件概觀Overview of consumable add-ons

應用程式可提供兩種類型的消費性附加元件,其差別在於管理完成的方式:Apps can offer two types of consumable add-ons that differ in the way that fulfillments are managed:

  • 開發人員管理的消費性產品Developer-managed consumable. 針對這種類型的消費性產品,您必須負責持續追蹤使用者對該附加元件所代表之項目的餘額,以及在使用者用完所有項目之後,向市集回報已完成附加元件的購買。For this type of consumable, you are responsible for keeping track of the user's balance of items that the add-on represents, and for reporting the purchase of the add-on as fulfilled to the Store after the user has consumed all of 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 個金幣之後,您的 App 必須回報該附加元件已完成,接著使用者就能再次購買 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.

  • 存放區管理的取用。Store-managed consumable. 針對這種類型的消費性產品,市集會持續追蹤使用者對該附加元件所代表之項目的餘額。For this type of consumable, the Store keeps track of the user's balance of items that the add-on represents. 當使用者取用任何項目時,您必須負責向市集回報這些項目已完成,而市集會更新使用者的餘額。When the user consumes any items, 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). 您的應用程式可以隨時查詢 Microsoft Store 有關使用者目前的餘額。Your app can query the Store 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 管理的消費性產品是從 Windows 10 (版本 1607) 開始提供。Store-managed consumables were introduced in Windows 10, version 1607.

若要為使用者提供消費性附加元件,請依照下列一般程序執行:To offer a consumable add-on to a user, follow this general process:

  1. 讓使用者能夠從您的 App 購買附加元件Enable users to purchase the add-on from your app.
  2. 當使用者取用附加元件 (例如,他們在遊戲中花費金幣) 時,將附加元件回報為已完成When the user consumes the add-on (for example, they spend coins in a game), report the add-on as fulfilled.

您也可以隨時針對市集管理的消費性產品來取得剩下的餘額At any time, you can also get the remaining balance for a Store-managed consumable.

先決條件Prerequisites

這些範例包含下列先決條件:These examples have the following prerequisites:

  • 適用於目標為 Windows 10 Anniversary Edition (10.0;組建 14393) 或更新版本的通用 Windows 平台 (UWP) App 的 Visual Studio 專案。A Visual Studio project for a Universal Windows Platform (UWP) app that targets Windows 10 Anniversary Edition (10.0; Build 14393) or a later release.
  • 您已在合作夥伴中心中 建立提交應用 程式,並在存放區中發佈此應用程式。You have created an app submission in Partner Center and this app is published in the Store. 測試時您也可以選擇將應用程式設定為不可在市集中搜尋。You can optionally configure the app so it is not discoverable in the Store while you test it. 如需詳細資訊,請參閱我們的測試指南For more information, see our testing guidance.
  • 您已在合作夥伴中心 建立應用程式 的取用附加元件。You have created a consumable add-on for the app in Partner Center.

這些範例中的程式碼假設:The code in these examples assume:

  • 程式碼會在 Page 的內容中執行,其中包含名為 workingProgressRingProgressRing 和名為 textBlockTextBlockThe code runs in the context of a Page that contains a ProgressRing named workingProgressRing and a TextBlock named textBlock. 這些物件可個別用來表示發生非同步作業,以及顯示輸出訊息。These objects are used to indicate that an asynchronous operation is occurring and to display output messages, respectively.
  • 程式碼檔案含有適用於 Windows.Services.Store 命名空間的 using 陳述式。The code file has a using statement for the Windows.Services.Store namespace.
  • App 是單一使用者 app,僅會在啟動 app 的使用者內容中執行。The app is a single-user app that runs only in the context of the user that launched the app. 如需詳細資訊,請參閱 App 內購買和試用版For more information, see In-app purchases and trials.

如需完整的範例應用程式,請參閱市集範例For a complete sample application, see the Store sample.

注意

如果您的傳統型應用程式使用傳統型橋接器,您可能需要新增這些範例中未顯示的額外程式碼來設定 StoreContext 物件。If you have a desktop application that uses the Desktop Bridge, you may need to add additional code not shown in these examples to configure the StoreContext object. 如需詳細資訊,請參閱在使用傳統型橋接器的傳統型應用程式中使用 StoreContext 類別For more information, see Using the StoreContext class in a desktop application that uses the Desktop Bridge.

將消費性附加元件回報為已完全交付Report a consumable add-on as fulfilled

當使用者從您的 app 購買附加元件並取用您的附加元件之後,您的 app 必須藉由呼叫 StoreContext 類別的 ReportConsumableFulfillmentAsync 方法來將附加元件回報為已完成。After the user purchases the add-on from your app and they consume your add-on, your app must report the add-on as fulfilled by calling the ReportConsumableFulfillmentAsync method of the StoreContext class. 您必須將下列資訊傳遞給此方法:You must pass the following information to this method:

  • 您想要回報為已完成之附加元件的市集識別碼The Store ID of the add-on that you want to report as fulfilled.
  • 您想要回報為已完成之附加元件的單位數。The units of the add-on you want to report as fulfilled.
    • 對於開發人員管理的消費性產品,請針對 quantity 參數指定 1。For a developer-managed consumable, specify 1 for the quantity parameter. 這會警示市集,消費性產品已完成,而客戶接著可再次購買消費性產品。This alerts the Store that the consumable has been fulfilled, and the customer can then purchase the consumable again. 在您的 app 通知市集該消費性產品已完成之前,使用者將無法再次購買該產品。The user cannot purchase the consumable again until your app has notified the Store that it was fulfilled.
    • 針對市集管理的消費性產品,指定實際已取用的單位數。For a Store-managed consumable, specify the actual number of units that have been consumed. 市集將會更新該消費性產品剩下的餘額。The Store will update the remaining balance for the consumable.
  • 適用於完成操作的追蹤識別碼。The tracking ID for the fulfillment. 這是開發人員提供的 GUID,可基於追蹤目的用來識別與完成操作相關聯的特定交易。This is a developer-supplied GUID that identifies the specific transaction that the fulfillment operation is associated with for tracking purposes. 如需詳細資訊,請參閱 ReportConsumableFulfillmentAsync 中的備註。For more information, see the remarks in ReportConsumableFulfillmentAsync.

這個範例示範如何將 Microsoft Store 管理的消費性產品回報為已完成。This example demonstrates how to report a Store-managed consumable as fulfilled.

private StoreContext context = null;

public async void ConsumeAddOn(string storeId)
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // This is an example for a Store-managed consumable, where you specify the actual number
    // of units that you want to report as consumed so the Store can update the remaining
    // balance. For a developer-managed consumable where you maintain the balance, specify 1
    // to just report the add-on as fulfilled to the Store.
    uint quantity = 10;
    string addOnStoreId = "9NBLGGH4TNNR";
    Guid trackingId = Guid.NewGuid();

    workingProgressRing.IsActive = true;
    StoreConsumableResult result = await context.ReportConsumableFulfillmentAsync(
        addOnStoreId, quantity, trackingId);
    workingProgressRing.IsActive = false;

    // Capture the error message for the operation, if any.
    string extendedError = string.Empty;
    if (result.ExtendedError != null)
    {
        extendedError = result.ExtendedError.Message;
    }

    switch (result.Status)
    {
        case StoreConsumableStatus.Succeeded:
            textBlock.Text = "The fulfillment was successful. " + 
                $"Remaining balance: {result.BalanceRemaining}";
            break;

        case StoreConsumableStatus.InsufficentQuantity:
            textBlock.Text = "The fulfillment was unsuccessful because the remaining " +
                $"balance is insufficient. Remaining balance: {result.BalanceRemaining}";
            break;

        case StoreConsumableStatus.NetworkError:
            textBlock.Text = "The fulfillment was unsuccessful due to a network error. " +
                "ExtendedError: " + extendedError;
            break;

        case StoreConsumableStatus.ServerError:
            textBlock.Text = "The fulfillment was unsuccessful due to a server error. " +
                "ExtendedError: " + extendedError;
            break;

        default:
            textBlock.Text = "The fulfillment was unsuccessful due to an unknown error. " +
                "ExtendedError: " + extendedError;
            break;
    }
}

取得市集管理的消費性產品剩下的餘額。Get the remaining balance for a Store-managed consumable

這個範例示範如何使用 StoreContext 類別的 GetConsumableBalanceRemainingAsync 方法,來取得市集管理的消費性產品剩下的餘額。This example demonstrates how to use the GetConsumableBalanceRemainingAsync method of the StoreContext class to get the remaining balance for a Store-managed consumable add-on.

private StoreContext context = null;

public async void GetRemainingBalance(string storeId)
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    string addOnStoreId = "9NBLGGH4TNNR";

    workingProgressRing.IsActive = true;
    StoreConsumableResult result = await context.GetConsumableBalanceRemainingAsync(addOnStoreId);
    workingProgressRing.IsActive = false;

    // Capture the error message for the operation, if any.
    string extendedError = string.Empty;
    if (result.ExtendedError != null)
    {
        extendedError = result.ExtendedError.Message;
    }

    switch (result.Status)
    {
        case StoreConsumableStatus.Succeeded:
            textBlock.Text = "Remaining balance: " + result.BalanceRemaining;
            break;

        case StoreConsumableStatus.NetworkError:
            textBlock.Text = "Could not retrieve balance due to a network error. " +
                "ExtendedError: " + extendedError;
            break;

        case StoreConsumableStatus.ServerError:
            textBlock.Text = "Could not retrieve balance due to a server error. " +
                "ExtendedError: " + extendedError;
            break;

        default:
            textBlock.Text = "Could not retrieve balance due to an unknown error. " +
                "ExtendedError: " + extendedError;
            break;
    }
}