Compartir a través de

Permitir compras de complementos consumibles

En este artículo se muestra cómo usar métodos de la clase StoreContext en el espacio de nombres Windows.Services.Store para administrar el cumplimiento de los complementos consumibles del usuario en las aplicaciones para UWP. Use complementos consumibles para los productos que se pueden comprar, usar y volver a comprar. Esto es especialmente útil para cosas como la moneda en el juego (oro, monedas, etc.) que se pueden comprar y luego usar para comprar potencias específicas.

Nota:

El espacio de nombres Windows.Services.Store se introdujo en Windows 10, versión 1607, y solo se puede usar en proyectos que tienen como destino Windows 10 Anniversary Edition (10.0; Compilación 14393) o una versión posterior en Visual Studio. Si la aplicación tiene como destino una versión anterior de Windows 10, debes usar el espacio de nombres Windows.ApplicationModel.Store en lugar del espacio de nombres Windows.Services.Store. Para obtener más información, consulte este artículo.

Visión general de los complementos consumibles

Las aplicaciones pueden ofrecer dos tipos de complementos consumibles que difieren de la manera en que se administran los cumplimientos:

  • Consumible administrado por el desarrollador. Para este tipo de consumible, usted es responsable de realizar un seguimiento del saldo de los elementos del usuario que representa el complemento y de informar a la Tienda que la compra del complemento se ha completado después de que el usuario haya consumido todos los artículos. El usuario no puede volver a comprar el complemento hasta que la aplicación haya notificado la compra anterior del complemento como completada.

    Por ejemplo, si el complemento representa 100 monedas en un juego y el usuario consume 10 monedas, la aplicación o el servicio deben mantener el nuevo saldo restante de 90 monedas para el usuario. Después de que el usuario haya consumido todas las 100 monedas, la aplicación debe notificar el complemento como cumplido y, a continuación, el usuario puede volver a comprar el complemento de 100 monedas.

  • Consumible gestionado por la tienda. Para este tipo de consumible, la Tienda lleva un registro del saldo de artículos del usuario que representa el complemento. Cuando el usuario consume cualquier elemento, usted es responsable de notificar esos elementos como cumplidos a la Tienda, y la Tienda actualiza el saldo del usuario. El usuario puede comprar el complemento tantas veces como quiera (no es necesario consumir primero los artículos). La aplicación puede consultar la Tienda para el saldo actual del usuario en cualquier momento.

    Por ejemplo, si el complemento representa una cantidad inicial de 100 monedas en un juego y el usuario consume 50 monedas, la aplicación informa a la Tienda de que se completaron 50 unidades del complemento y la Tienda actualiza el saldo restante. Si el usuario vuelve a comprar su complemento para adquirir 100 monedas más, ahora tendrá 150 monedas en total.

    Nota:

    Los consumibles administrados por la Tienda se introdujeron en Windows 10, versión 1607.

Para ofrecer un complemento consumible a un usuario, siga este proceso general:

  1. Permitir que los usuarios compren el complemento desde tu aplicación.
  2. Cuando el usuario consume el complemento (por ejemplo, gasta monedas en un juego), reportar el complemento como cumplido.

En cualquier momento, también puedes obtener el saldo restante de un recurso consumible gestionado por la tienda.

Prerrequisitos

Estos ejemplos tienen los siguientes requisitos previos:

  • Un proyecto de Visual Studio para una aplicación para la Plataforma Universal de Windows (UWP) que tiene como objetivo la Edición de Aniversario de Windows 10 (10.0; Compilación 14393) o una versión posterior.
  • Has creado un envío de aplicación en el Centro de Partners y esta aplicación está publicada en la Microsoft Store. Opcionalmente, puedes configurar la aplicación para que no se pueda detectar en la Tienda mientras la pruebas. Para obtener más información, consulte nuestra guía de pruebas de .
  • Ha creado un complemento consumible para la aplicación en el Centro de partners.

En el código de estos ejemplos se supone:

  • El código se ejecuta en el contexto de una Page que contiene un ProgressRing denominado workingProgressRing y un TextBlock denominado textBlock. Estos objetos se usan para indicar que se está produciendo una operación asincrónica y mostrar mensajes de salida, respectivamente.
  • El archivo de código tiene una instrucción mediante para el espacio de nombres Windows.Services.Store.
  • La aplicación es una aplicación de usuario único que solo se ejecuta en el contexto del usuario que inició la aplicación. Para obtener más información, consulte compras dentro de la aplicación y versiones de prueba.

Para obtener una aplicación de ejemplo completa, consulte el ejemplo de Store.

Nota:

Si tienes una aplicación de escritorio que usa el Puente de escritorio, es posible que tengas que agregar código adicional que no se muestra en estos ejemplos para configurar el objeto StoreContext . Para obtener más información, consulta "Cómo utilizar la clase StoreContext en una aplicación de escritorio que utiliza el Desktop Bridge".

Notificar una extensión consumible como completada

Después de que el usuario compra el complemento desde tu aplicación y consume tu complemento, tu aplicación debe notificar el complemento como completado llamando al método ReportConsumableFulfillmentAsync de la clase StoreContext. Debe pasar la siguiente información a este método:

  • El ID de la tienda del complemento que quiere informar como cumplido.
  • Las unidades del complemento que desea notificar como completadas.
    • Para un consumible administrado por el desarrollador, especifique 1 para el parámetro cantidad . Esto alerta a la Tienda de que se ha consumido el consumible, y entonces el cliente puede volver a comprar el consumible. El usuario no puede volver a comprar el consumible hasta que tu aplicación notifique a la Tienda que se haya cumplido.
    • Para un consumible administrado por la Tienda, especifique el número real de unidades que se han consumido. La Tienda actualizará el saldo disponible del consumible.
  • Identificador de seguimiento del suministro. Se trata de un GUID proporcionado por el desarrollador que identifica la transacción específica con la que está asociada la operación de cumplimiento con fines de seguimiento. Para obtener más información, vea los comentarios de ReportConsumableFulfillmentAsync.

En este ejemplo se muestra cómo notificar un consumible administrado por la Tienda como cumplido.

private StoreContext context = null;

public async void ConsumeAddOn(string addOnStoreId)
{
    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;
    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;
    }
}

Obtener el saldo restante de un consumible administrado por la Tienda

En este ejemplo se muestra cómo usar el método GetConsumableBalanceRemainingAsync de la clase StoreContext para obtener el saldo restante de un complemento consumible administrado por store.

private StoreContext context = null;

public async void GetRemainingBalance(string addOnStoreId)
{
    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.
    }

    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;
    }
}