Gérer les offres ciblées à l’aide des services du Windows Store
Si vous créez une offre ciblée dans la page Engager > des offres ciblées pour votre application dans l’Espace partenaires, utilisez l’API des offres ciblées du Microsoft Store dans le code de votre application pour récupérer des informations qui vous aident à implémenter l’expérience dans l’application pour l’offre ciblée. Pour plus d’informations sur les offres ciblées et sur la façon de les créer dans le tableau de bord, consultez Utiliser des offres ciblées pour optimiser l’engagement et les conversions.
L’API des offres ciblées est une API REST simple que vous pouvez utiliser pour obtenir les offres ciblées disponibles pour l’utilisateur actuel, selon que l’utilisateur fait partie ou non du segment client de l’offre ciblée. Pour utiliser cette API dans le code de votre application, procédez comme suit :
- Obtenez un jeton de compte Microsoft pour l’utilisateur connecté actuel de votre application.
- Obtenez les offres ciblées pour l’utilisateur actuel.
- Implémentez l’expérience d’achat dans l’application pour le module complémentaire associé à l’une des offres ciblées. Pour plus d’informations sur l’implémentation d’achats dans l’application, consultez cet article.
Pour obtenir un exemple de code complet qui illustre toutes ces étapes, consultez l’exemple de code à la fin de cet article. Les sections suivantes fournissent plus de détails sur chaque étape.
Obtenir un jeton de compte Microsoft pour l’utilisateur actuel
Dans le code de votre application, obtenez un jeton MSA (Microsoft Account) pour l’utilisateur connecté actuel. Vous devez transmettre ce jeton dans l’en-tête Authorization de demande de l’API des offres ciblées du Microsoft Store. Ce jeton est utilisé par le Windows Store pour récupérer les offres ciblées disponibles pour l’utilisateur actuel.
Pour obtenir le jeton MSA, utilisez la classe WebAuthenticationCoreManager pour demander un jeton à l’aide de l’étendue devcenter_implicit.basic,wl.basic. L'exemple suivant illustre la procédure à suivre pour réaliser cette opération. Cet exemple est un extrait de l’exemple complet et nécessite l’utilisation d’instructions fournies dans l’exemple complet.
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;
}
}
Pour plus d’informations sur l’obtention de jetons MSA, consultez le gestionnaire de comptes web.
Obtenir les offres ciblées pour l’utilisateur actuel
Une fois que vous avez un jeton MSA pour l’utilisateur actuel, appelez la méthode GET de l’URI https://manage.devcenter.microsoft.com/v2.0/my/storeoffers/user pour obtenir les offres ciblées disponibles pour l’utilisateur actuel. Pour plus d’informations sur cette méthode REST, consultez Obtenir des offres ciblées.
Cette méthode retourne les ID de produit des modules complémentaires associés aux offres ciblées disponibles pour l’utilisateur actuel. Avec ces informations, vous pouvez proposer une ou plusieurs offres ciblées en tant qu’achat in-app à l’utilisateur.
L’exemple suivant montre comment obtenir les offres ciblées pour l’utilisateur actuel. Cet exemple est un extrait de l’exemple complet. Elle nécessite la bibliothèque Json.NET de Newtonsoft et des classes supplémentaires et des instructions using fournies dans l’exemple complet.
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;
}
Exemple de code complet
L’exemple de code suivant illustre les tâches suivantes :
- Obtenez un jeton MSA pour l’utilisateur actuel.
- Obtenez toutes les offres ciblées pour l’utilisateur actuel à l’aide de la méthode Obtenir les offres ciblées.
- Achetez le module complémentaire associé à une offre ciblée.
Cet exemple nécessite la bibliothèque Json.NET de Newtonsoft. L’exemple utilise cette bibliothèque pour sérialiser et désérialiser des données au format JSON.
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; }
}
}