Verwalten gezielter Angebote mithilfe von Store-Diensten

  • Artikel

Wenn Sie auf der Seite "Gezielte Angebote einbinden>" für Ihre App im Partner Center ein gezieltes Angebot 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 Zielangebot helfen. Weitere Informationen zu gezielten Angeboten und deren Erstellung im Dashboard finden Sie unter Verwenden gezielter Angebote zum Maximieren von Engagement und Konvertierungen.

Die API für gezielte Angebote ist eine einfache REST-API, die Sie verwenden können, um die Zielangebote abzurufen, die für den aktuellen Benutzer verfügbar sind, je nachdem, ob der Benutzer Teil des Kundensegments für das Zielangebot ist oder nicht. Führen Sie die folgenden Schritte aus, um diese API im Code Ihrer App zu verwenden:

  1. Rufen Sie ein Microsoft-Kontotoken für den aktuell angemeldeten Benutzer Ihrer App ab.
  2. Rufen Sie die Zielangebote für den aktuellen Benutzer ab.
  3. Implementieren Sie die In-App-Kauferfahrung für das Add-On, das einem der Zielangebote 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 aktuell angemeldeten Benutzer ab. Sie müssen dieses Token im Anforderungsheader Authorization für die Zielangebots-API des Microsoft Store übergeben. Dieses Token wird vom Store verwendet, um die Zielangebote abzurufen, die für den aktuellen Benutzer verfügbar sind.

Verwenden Sie zum Abrufen des MSA-Tokens die WebAuthenticationCoreManager-Klasse , um mithilfe des Bereichs devcenter_implicit.basic,wl.basicein Token anzufordern. Im folgenden Beispiel wird die dafür erforderliche Vorgehensweise veranschaulicht. Dieses Beispiel ist ein Auszug aus dem vollständigen Beispiel und erfordert using-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 Zielangebote 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 Zielangebote 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 Zielangeboten zugeordnet sind, die für den aktuellen Benutzer verfügbar sind. Mit diesen Informationen können Sie dem Benutzer eines oder mehrere der gezielten Angebote als In-App-Kauf anbieten.

Im folgenden Beispiel wird veranschaulicht, wie Sie die Zielangebote für den aktuellen Benutzer abrufen. 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:

  • Rufen Sie ein MSA-Token für den aktuellen Benutzer ab.
  • Rufen Sie alle Zielangebote für den aktuellen Benutzer mithilfe der Get targeted offers-Methode ab.
  • Erwerben Sie das Add-On, das einem Zielangebot zugeordnet ist.

Für dieses Beispiel ist die Json.NET-Bibliothek von Newtonsoft erforderlich. Im Beispiel wird diese Bibliothek verwendet, um JSON-formatierte Daten zu serialisieren und zu 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; }
    }
}