Unterstützen von Endverbraucher-Add-On-Käufen
In diesem Artikel wird veranschaulicht, wie Sie Methoden der StoreContext-Klasse im Windows.Services.Store-Namespace verwenden, um die Erfüllung verbrauchsbasierter Add-Ons durch den Benutzer in Ihren UWP-Apps zu verwalten. Verwenden Sie Endverbraucher-Add-ons für Artikel, die gekauft, verwendet und erneut gekauft werden können. Dies ist besonders nützlich für Dinge wie spielinterne Währungen (Gold, Münzen usw.), die gekauft und dann zum Erwerben 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 Windows 10 Anniversary Edition (10.0; Build 14393) oder eine höhere Version in Visual Studio. Wenn Ihre App für eine frühere Version von Windows 10 geeignet ist, müssen Sie den Windows.ApplicationModel.Store-Namespace anstelle des Windows.Services.Store-Namespace verwenden. hier finden Sie weitere Informationen
Übersicht über Endverbraucher-Add-ons
Apps können zwei Arten von verbrauchsbaren Add-Ons anbieten, die sich in der Art und Weise unterscheiden, wie Fulfillments verwaltet werden:
Von Entwicklern verwaltetes Endverbraucher-Add-On. Bei dieser Art von Verbrauchsartikel sind Sie dafür verantwortlich, das Guthaben des Benutzers an Elementen zu verfolgen, die das Add-On darstellt, und den Kauf des Add-Ons dem Store als erfüllt zu melden, nachdem der Benutzer alle Elemente genutzt hat. Der Benutzer kann das Add-On erst dann erneut kaufen, nachdem Ihre App den vorherigen Kauf des Add-Ons als erfüllt gemeldet hat.
Wenn beispielsweise das Add-On 100 Münzen in einem Spiel darstellt und der Benutzer 10 Münzen nutzt, muss die App oder der Dienst den neuen Restbetrag von 90 Münzen für den Benutzer verwalten. Nachdem der Benutzer alle 100 Münzen genutzt hat, muss die App das Add-On als erfüllt melden, und danach kann der Benutzer das Add-On für 100 Münzen erneut kaufen.
Im Store verwaltete Verbrauchsmaterialien. Bei dieser Art von Verbrauchsartikel verfolgt der Store das Guthaben des Benutzers an Elementen, die das Add-On darstellt. Wenn der Benutzer Elemente nutzt, sind Sie verantwortlich dafür, diese Elemente dem Store als erfüllt zu melden, und der Store aktualisiert das Guthaben des Benutzers. Der Benutzer kann das Add-On so oft kaufen, wie er möchte (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 das verbleibende Guthaben. Wenn der Benutzer dann Ihr Add-On zurückkauft, um 100 weitere Münzen zu erwerben, hat er jetzt insgesamt 150 Münzen.
Hinweis
Speicherverwaltete Verbrauchsmaterialien wurden in Windows 10 Version 1607 eingeführt.
Um einem Benutzer ein Endverbraucher-Add-on anzubieten, befolgen Sie dieses allgemeine Verfahren:
- Ermöglichen Sie Benutzern den Erwerb des Add-ons in Ihrer App.
- Wenn der Benutzer das Add-on nutzt (z. B. indem er Münzen in einem Spiel ausgibt), melden Sie das Add-on als erfüllt.
Auch das Abrufen des Restbetrags für einen vom Store verwalteten Verbrauchsartikel ist jederzeit möglich.
Voraussetzungen
Für diese Beispiele gelten die folgenden Voraussetzungen:
- Ein Visual Studio-Projekt für eine Universelle Windows-Plattform-App (UWP), die auf Windows 10 Anniversary Edition (10.0; Build 14393) oder eine höhere Version.
- Sie haben eine App-Übermittlung im Partner Center erstellt, und diese App wird 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 verbrauchsfähiges Add-On für die App im Partner Center erstellt.
Der Code in diesen Beispielen geht von Folgendem aus:
- Die Ausführung des Codes erfolgt im Kontext einer Seite, die einen ProgressRing mit dem Namen
workingProgressRingund einen TextBlock mit dem NamentextBlockenthält. Diese Objekte werden verwendet, um anzugeben, dass ein asynchroner Vorgang ausgeführt wird, bzw. um Ausgabemeldungen anzuzeigen. - Die Codedatei enthält eine using-Anweisung für den Namespace Windows.Services.Store.
- 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 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ücke verwendet.
Melden eines Endverbraucher-Add-Ons als erfüllt
Nachdem der Benutzer den Kauf des Add-Ons über Ihre App tätigt und das Add-On nutzt, muss Ihre App durch Aufrufen der ReportConsumableFulfillmentAsync-Methode der StoreContext-Klasse das Add-On als erfüllt melden. 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, das Sie als erfüllt melden möchten.
- Geben Sie für einen von Entwicklern verwalteten Verbrauchsartikel als Parameter für die Menge 1 an. 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 dann erneut kaufen, wenn Ihre App den Store benachrichtigt hat, dass er erfüllt wurde.
- Geben Sie für einen vom Store verwalteten Verbrauchsartikel die tatsächliche Anzahl der Einheiten an, die verbraucht wurden. Der Store aktualisiert den Restbetrag für den Verbrauchsartikel.
- Die Tracking-ID für die Erfüllung. Dies ist eine vom Entwickler angegebene GUID, welche die spezielle Transaktion, mit der der Erfüllungsvorgang verknüpft ist, für Nachverfolgungszwecke identifiziert. Weitere Informationen finden Sie in den Hinweisen in ReportConsumableFulfillmentAsync.
In diesem Beispiel wird gezeigt, wie ein vom Store verwalteter Verbrauchsartikel als erfüllt gemeldet 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;
}
}
Abrufen des Restbetrags für einen vom Store verwalteten Verbrauchsartikel
Dieses Beispiel zeigt, wie die GetConsumableBalanceRemainingAsync-Methode der StoreContext-Klasse verwendet wird, um den Restbetrag für ein vom Store verwaltetes Endverbraucher-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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für