Aktivieren von konsumierbaren Add-On-Käufen

In diesem Artikel wird veranschaulicht, wie Methoden der StoreContext Klasse im Windows.Services.Store Namespace verwendet werden können, um die Erfüllung konsumierbarer Add-Ons in Ihren UWP-Apps zu verwalten. Verwenden Sie Verbrauchs-Add-Ons für Artikel, die gekauft, verwendet und erneut gekauft werden können. Dies ist besonders nützlich für Dinge wie In-Game-Währung (Gold, Münzen usw.), die gekauft und dann zum Kauf bestimmter Power-Ups verwendet werden können.

Hinweis

Der Windows.Services.Store-Namespace wurde in Windows 10, Version 1607, eingeführt und kann nur in Projekten verwendet werden, die auf Windows 10 Anniversary Edition abzielen (10.0; Build 14393) oder einer höheren Version in Visual Studio. Wenn Ihre App auf eine frühere Version von Windows 10 ausgerichtet ist, müssen Sie den Windows.ApplicationModel.Store Namespace anstelle des Windows.Services.Store Namespace verwenden. Weitere Informationen finden Sie in diesem Artikel.

Übersicht über Verbrauchs-Add-Ons

Apps können zwei Arten von verbrauchbaren Add-Ons anbieten, die sich darin unterscheiden, wie deren Ausführung verwaltet wird:

• vom Entwickler verwaltete Verbrauchsgüter. Für diese Art von Verbrauchsmaterial sind Sie dafür verantwortlich, den Bestand der vom Add-On dargestellten Artikel des Benutzers im Blick zu behalten und den Kauf des Add-Ons als abgeschlossen an den Store zu melden, nachdem der Benutzer alle Artikel verbraucht hat. Der Benutzer kann die Erweiterung erst dann erneut kaufen, wenn die App den vorherigen Erweiterungskauf als erfüllt gemeldet hat.

  Wenn Ihr Add-On beispielsweise 100 Münzen in einem Spiel darstellt und der Benutzer 10 Münzen verbraucht, muss Ihre App oder Ihr Dienst das neue Restguthaben von 90 Münzen für den Benutzer beibehalten. Sobald der Benutzer alle 100 Münzen verbraucht hat, muss Ihre App das Add-On als abgeschlossen melden, und dann kann der Benutzer das 100-Münzen-Add-On erneut kaufen.

• vom Store verwalteten Verbrauchsartikel. Für diese Art von Verbrauchsartikel verfolgt der Store das Guthaben des Benutzers an Elementen, die das Add-On darstellt. Wenn der Benutzer Elemente nutzt, sind Sie dafür verantwortlich, diese Elemente als erfüllt an den Store zu melden, und der Store aktualisiert das Guthaben des Benutzers. Der Benutzer kann das Add-On so oft wie gewünscht kaufen (er muss die Elemente nicht zuerst nutzen). Ihre App kann den Store jederzeit nach dem aktuellen Saldo für den Benutzer abfragen.

  Wenn Ihr Add-On beispielsweise eine anfängliche Menge von 100 Münzen in einem Spiel darstellt und der Benutzer 50 Münzen verbraucht, meldet Ihre App dem Store, dass 50 Einheiten des Add-Ons erfüllt wurden, und der Store aktualisiert den verbleibenden Saldo. Wenn der Benutzer ihr Add-On dann erneut erwirbt, um 100 weitere Münzen zu erwerben, hat er jetzt insgesamt 150 Münzen.

  Hinweis

  Vom Store verwaltete Verbrauchsartikel wurden in Windows 10, Version 1607, eingeführt.

Um einem Benutzer ein konsumierbares Add-On anzubieten, befolgen Sie diesen allgemeinen Prozess:

1. Ermöglichen Sie Benutzern, das Add-On über Ihre App zu kaufen .
2. Wenn der Benutzer das Add-On nutzt (z. B. sie ausgeben Münzen in einem Spiel), das Add-On als erfülltmelden.

Sie können jederzeit auch das verbleibende Guthaben für einen vom Store verwalteten Verbrauchsartikel abrufen.

Voraussetzungen

Diese Beispiele haben die folgenden Voraussetzungen:

• Ein Visual Studio-Projekt für eine UWP-App (Universelle Windows-Plattform), die auf Windows 10 Anniversary Edition ausgerichtet ist (10.0; Build 14393) oder einer höheren Version.
• Sie haben eine App-Einreichung im Partner Center erstellt, und diese App ist im Store veröffentlicht. Sie können die App optional so konfigurieren, dass sie beim Testen nicht im Store auffindbar ist. Weitere Informationen finden Sie in unserem Testleitfaden.
• Sie haben ein verbrauchbares Add-On für die App im Partner Center erstellt.

Der Code in diesen Beispielen geht davon aus:

• Der Code wird im Kontext einer Page ausgeführt, die einen ProgressRing mit dem Namen workingProgressRing und einen TextBlock mit dem Namen textBlockenthält. Diese Objekte werden verwendet, um anzugeben, dass ein asynchroner Vorgang stattfindet, beziehungsweise um Ausgabemeldungen anzuzeigen.
• Die Codedatei enthält eine mit der-Anweisung für den Windows.Services.Store-Namespace.
• Die App ist eine Einzelbenutzer-App, die nur im Kontext des Benutzers ausgeführt wird, der die App gestartet hat. Weitere Informationen finden Sie unter dem Abschnitt In-App-Käufe und Testversionen.

Eine vollständige Beispielanwendung finden Sie im Store-Beispiel-.

Hinweis

Wenn Sie über eine Desktopanwendung verfügen, die die Desktop-Brücke verwendet, müssen Sie möglicherweise zusätzlichen Code hinzufügen, der in diesen Beispielen nicht gezeigt wird, um das StoreContext-Objekt zu konfigurieren. Weitere Informationen finden Sie unter Verwenden der StoreContext-Klasse in einer Desktopanwendung, die die Desktop-Brückeverwendet.

Ein Verbrauchs-Zusatzmodul als erfüllt melden

Nachdem der Benutzer das Add-On von Ihrer App erworben und es konsumiert hat, muss Ihre App das Add-On als erfüllt melden, indem die Methode ReportConsumableFulfillmentAsync der Klasse StoreContext aufgerufen wird. Sie müssen die folgenden Informationen an diese Methode übergeben:

• Die Store-ID des Add-Ons, das Sie als erfüllt melden möchten.
• Die Einheiten des Add-ons, die Sie als erfüllt verbuchen möchten.
  • Definieren Sie für einen vom Entwickler verwalteten Verbrauchsartikel eine Menge von 1 für den Parameter . Dadurch wird der Store benachrichtigt, dass der Verbrauchsartikel erfüllt wurde, und der Kunde kann dann den Verbrauchsartikel erneut kaufen. Der Benutzer kann den Verbrauchsartikel erst wieder kaufen, nachdem Ihre App dem Store mitgeteilt hat, dass der Kauf abgeschlossen ist.
  • Geben Sie für einen vom Store verwalteten Verbrauchsartikel die tatsächliche Anzahl der verbrauchten Einheiten an. Der Store aktualisiert das verbleibende Guthaben für das Verbrauchsgut.
• Die Tracking-ID für die Auftragserfüllung. Dies ist eine vom Entwickler bereitgestellte GUID, die die spezifische Transaktion identifiziert, der der Erfüllungsvorgang zu Tracking-Zwecken zugeordnet ist. Weitere Informationen finden Sie in den Hinweisen in ReportConsumableFulfillmentAsync.

In diesem Beispiel wird veranschaulicht, wie ein vom Store verwalteter Verbrauchsartikel als erfüllt angezeigt wird.

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

Das Restguthaben eines vom Store verwalteten Verbrauchsartikels abrufen

In diesem Beispiel wird veranschaulicht, wie Sie die GetConsumableBalanceRemainingAsync Methode der StoreContext-klasse verwenden, um den Restbetrag für ein vom Store verwaltetes Verbrauchs-Add-On abzurufen.

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

Zugehörige Themen

• In-App-Käufe und Testversionen
• Produktinformationen zu Apps und Add-Ons abrufen
• Lizenzinformationen für Apps und Add-Ons abrufen
• In-App-Käufe für Apps und Erweiterungen aktivieren
• Implementieren Sie eine Testversion Ihrer App
• Store-Beispiel