Verwalten gezielter Angebote mithilfe von Store-Diensten
Wenn Sie ein gezieltes Angebot auf der Seite "Gezielte Angebote einbeziehen>" für Ihre App im Partner Center erstellen, verwenden Sie die Microsoft Store-API für gezielte Angebote im Code Ihrer App, um Informationen abzurufen, die Ihnen bei der Implementierung der In-App-Erfahrung für das gezielte Angebot helfen. Weitere Informationen zu gezielten Angeboten und deren Erstellung im Dashboard finden Sie unter Verwenden von gezielten Angeboten zur Maximierung von Engagement und Konvertierungen.
Die API für gezielte Angebote ist eine einfache REST-API, mit der Sie die gezielten Angebote abrufen können, die für den aktuellen Benutzer verfügbar sind, je nachdem, ob der Benutzer Teil des Kundensegments für das gezielte Angebot ist. Führen Sie die folgenden Schritte aus, um diese API im Code Ihrer App zu verwenden:
- Rufen Sie ein Microsoft-Kontotoken für den aktuellen angemeldeten Benutzer Ihrer App ab .
- Abrufen der gezielten Angebote für den aktuellen Benutzer.
- Implementieren Sie die In-App-Einkaufserfahrung für das Add-On, das einem der gezielten Angebote zugeordnet ist. Weitere Informationen zum Implementieren von In-App-Käufen finden Sie in diesem Artikel.
Ein vollständiges Codebeispiel, das alle diese Schritte veranschaulicht, finden Sie im Codebeispiel am Ende dieses Artikels. Die folgenden Abschnitte enthalten weitere Details zu den einzelnen Schritten.
Abrufen eines Microsoft-Kontotokens für den aktuellen Benutzer
Rufen Sie im Code Ihrer App ein Microsoft-Kontotoken (MSA) für den aktuellen angemeldeten Benutzer ab. Sie müssen dieses Token im Anforderungsheader Authorization für die Api für gezielte Angebote des Microsoft Store übergeben. Dieses Token wird vom Store verwendet, um die gezielten Angebote abzurufen, die für den aktuellen Benutzer verfügbar sind.
Verwenden Sie zum Abrufen des MSA-Tokens die WebAuthenticationCoreManager-Klasse , um ein Token mithilfe des Bereichs devcenter_implicit.basic,wl.basicanzufordern. Im folgenden Beispiel wird die dafür erforderliche Vorgehensweise veranschaulicht. Dieses Beispiel ist ein Auszug aus dem vollständigen Beispiel und erfordert die Verwendung von Anweisungen, die im vollständigen Beispiel bereitgestellt werden.
private async Task<string> GetMicrosoftAccountTokenAsync()
{
var msaProvider = await WebAuthenticationCoreManager.FindAccountProviderAsync(
"https://login.microsoft.com", "consumers");
WebTokenRequest request = new WebTokenRequest(msaProvider, "devcenter_implicit.basic,wl.basic");
WebTokenRequestResult result = await WebAuthenticationCoreManager.RequestTokenAsync(request);
if (result.ResponseStatus == WebTokenRequestStatus.Success)
{
return result.ResponseData[0].Token;
}
else
{
return string.Empty;
}
}
Weitere Informationen zum Abrufen von MSA-Token finden Sie unter Web Account Manager.
Abrufen der gezielten Angebote für den aktuellen Benutzer
Nachdem Sie über ein MSA-Token für den aktuellen Benutzer verfügen, rufen Sie die GET-Methode des https://manage.devcenter.microsoft.com/v2.0/my/storeoffers/user URI auf, um die verfügbaren gezielten Angebote für den aktuellen Benutzer abzurufen. Weitere Informationen zu dieser REST-Methode finden Sie unter Abrufen gezielter Angebote.
Diese Methode gibt die Produkt-IDs der Add-Ons zurück, die den gezielten Angeboten zugeordnet sind, die für den aktuellen Benutzer verfügbar sind. Mit diesen Informationen können Sie dem Benutzer mindestens ein gezieltes Angebot als In-App-Kauf anbieten.
Im folgenden Beispiel wird veranschaulicht, wie die gezielten Angebote für den aktuellen Benutzer abgerufen werden. Dieses Beispiel ist ein Auszug aus dem vollständigen Beispiel. Es erfordert die Json.NET-Bibliothek von Newtonsoft und zusätzliche Klassen und die Verwendung von Anweisungen, die im vollständigen Beispiel bereitgestellt werden.
private async Task<List<TargetedOfferData>> GetTargetedOffersForUserAsync(string msaToken)
{
if (string.IsNullOrEmpty(msaToken))
{
System.Diagnostics.Debug.WriteLine("Microsoft Account token is null or empty.");
return null;
}
HttpClient httpClientGetOffers = new HttpClient();
httpClientGetOffers.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", msaToken);
List<TargetedOfferData> availableOfferData = null;
try
{
string getOffersResponse = await httpClientGetOffers.GetStringAsync(new Uri(storeOffersUri));
availableOfferData =
Newtonsoft.Json.JsonConvert.DeserializeObject<List<TargetedOfferData>>(getOffersResponse);
}
catch (Exception ex)
{
System.Diagnostics.Debug.WriteLine(ex.Message);
}
return availableOfferData;
}
Vollständiges Codebeispiel
Im folgenden Codebeispiel werden die folgenden Aufgaben veranschaulicht:
- Ruft ein MSA-Token für den aktuellen Benutzer ab.
- Rufen Sie alle gezielten Angebote für den aktuellen Benutzer mithilfe der Methode "Gezielte Angebote abrufen" ab.
- Kaufen Sie das Add-On, das einem gezielten Angebot zugeordnet ist.
In diesem Beispiel ist die Json.NET-Bibliothek von Newtonsoft erforderlich. Im Beispiel wird diese Bibliothek verwendet, um JSON-formatierte Daten serialisieren und deserialisieren.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Net.Http;
using System.Net.Http.Headers;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Windows.Services.Store;
using Windows.Security.Authentication.Web.Core;
namespace DocumenationExamples
{
public class TargetedOffersExample
{
private const string storeOffersUri = "https://manage.devcenter.microsoft.com/v2.0/my/storeoffers/user";
private const string jsonMediaType = "application/json";
private static string[] productKinds = { "Durable", "Consumable", "UnmanagedConsumable" };
private static StoreContext storeContext = StoreContext.GetDefault();
public async void DemonstrateTargetedOffers()
{
// Get the Microsoft Account token for the current user.
string msaToken = await GetMicrosoftAccountTokenAsync();
if (string.IsNullOrEmpty(msaToken))
{
System.Diagnostics.Debug.WriteLine("Microsoft Account token could not be retrieved.");
return;
}
// Get the targeted Store offers for the current user.
List<TargetedOfferData> availableOfferData =
await GetTargetedOffersForUserAsync(msaToken);
if (availableOfferData == null || availableOfferData.Count == 0)
{
System.Diagnostics.Debug.WriteLine("There was an error retrieving targeted offers," +
"or there are no targeted offers available for the current user.");
return;
}
// Get the product ID of the add-on that is associated with the first available offer
// in the response data.
TargetedOfferData offerData = availableOfferData[0];
string productId = offerData.Offers[0];
// Get the Store ID of the add-on that has the matching product ID, and then purchase the add-on.
List<String> filterList = new List<string>(productKinds);
StoreProductQueryResult queryResult = await storeContext.GetAssociatedStoreProductsAsync(filterList);
foreach (KeyValuePair<string, StoreProduct> result in queryResult.Products)
{
if (result.Value.InAppOfferToken == productId)
{
await PurchaseOfferAsync(result.Value.StoreId);
return;
}
}
System.Diagnostics.Debug.WriteLine("No add-on with the specified product ID could be found " +
"for the current app.");
return;
}
private async Task<string> GetMicrosoftAccountTokenAsync()
{
var msaProvider = await WebAuthenticationCoreManager.FindAccountProviderAsync(
"https://login.microsoft.com", "consumers");
WebTokenRequest request = new WebTokenRequest(msaProvider, "devcenter_implicit.basic,wl.basic");
WebTokenRequestResult result = await WebAuthenticationCoreManager.RequestTokenAsync(request);
if (result.ResponseStatus == WebTokenRequestStatus.Success)
{
return result.ResponseData[0].Token;
}
else
{
return string.Empty;
}
}
private async Task<List<TargetedOfferData>> GetTargetedOffersForUserAsync(string msaToken)
{
if (string.IsNullOrEmpty(msaToken))
{
System.Diagnostics.Debug.WriteLine("Microsoft Account token is null or empty.");
return null;
}
HttpClient httpClientGetOffers = new HttpClient();
httpClientGetOffers.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", msaToken);
List<TargetedOfferData> availableOfferData = null;
try
{
string getOffersResponse = await httpClientGetOffers.GetStringAsync(new Uri(storeOffersUri));
availableOfferData =
Newtonsoft.Json.JsonConvert.DeserializeObject<List<TargetedOfferData>>(getOffersResponse);
}
catch (Exception ex)
{
System.Diagnostics.Debug.WriteLine(ex.Message);
}
return availableOfferData;
}
private async Task PurchaseOfferAsync(string storeId)
{
if (string.IsNullOrEmpty(storeId))
{
System.Diagnostics.Debug.WriteLine("storeId is null or empty.");
return;
}
// Purchase the add-on for the current user. Typically, a game or app would first show
// a UI that prompts the user to buy the add-on; for simplicity, this example
// simply purchases the add-on.
StorePurchaseResult result = await storeContext.RequestPurchaseAsync(storeId);
// Capture the error message for the purchase operation, if any.
string extendedError = string.Empty;
if (result.ExtendedError != null)
{
extendedError = result.ExtendedError.Message;
}
switch (result.Status)
{
case StorePurchaseStatus.AlreadyPurchased:
System.Diagnostics.Debug.WriteLine("The user has already purchased the product.");
break;
case StorePurchaseStatus.Succeeded:
System.Diagnostics.Debug.WriteLine("The purchase was successful.");
break;
case StorePurchaseStatus.NotPurchased:
System.Diagnostics.Debug.WriteLine("The purchase did not complete. " +
"The user may have cancelled the purchase. ExtendedError: " + extendedError);
break;
case StorePurchaseStatus.NetworkError:
System.Diagnostics.Debug.WriteLine("The purchase was unsuccessful due to a network error. " +
"ExtendedError: " + extendedError);
break;
case StorePurchaseStatus.ServerError:
System.Diagnostics.Debug.WriteLine("The purchase was unsuccessful due to a server error. " +
"ExtendedError: " + extendedError);
break;
default:
System.Diagnostics.Debug.WriteLine("The purchase was unsuccessful due to an unknown error. " +
"ExtendedError: " + extendedError);
break;
}
}
}
public class TargetedOfferData
{
[JsonProperty(PropertyName = "offers")]
public IList<string> Offers { get; } = new List<string>();
[JsonProperty(PropertyName = "trackingId")]
public string TrackingId { get; set; }
}
}