Exécuter des campagnes publicitaires à l’aide des services du Windows Store

** Utilisez l’API de promotions Microsoft Store pour gérer de manière programmatique les campagnes publicitaires des applications inscrites auprès de votre compte ou de celui de votre organisation dans le Centre de partenariat. Cette API vous permet de créer, mettre à jour et surveiller vos campagnes et d’autres ressources associées, telles que le ciblage et les créations. Cette API est particulièrement utile pour les développeurs qui créent de grands volumes de campagnes et qui souhaitent le faire sans utiliser l’Espace partenaires. Cette API utilise Azure Active Directory (Azure AD) pour authentifier les appels à partir de votre application ou service.

Les étapes suivantes décrivent le processus de bout en bout :

1. Vérifiez que vous avez rempli toutes les conditions préalables .
2. Avant d’appeler une méthode dans l’API de promotions du Microsoft Store, vous devez obtenir un jeton d’accès Azure AD. Après avoir obtenu un jeton, vous avez 60 minutes pour utiliser ce jeton dans les appels à l’API de promotions du Microsoft Store avant l’expiration du jeton. Une fois le jeton expiré, vous pouvez générer un nouveau jeton.
3. appeler l’API de promotions du Microsoft Store.

Vous pouvez également créer et gérer des campagnes publicitaires à l’aide de l’Espace partenaires, et toutes les campagnes publicitaires que vous créez par programmation via l’API promotions du Microsoft Store sont également accessibles dans l’Espace partenaires. Pour plus d’informations sur la gestion des campagnes publicitaires dans l’Espace partenaires, consultez Créer une campagne publicitaire pour votre application.

Étape 1 : Prérequis complets pour l’utilisation de l’API de promotions du Microsoft Store

Avant de commencer à écrire du code pour appeler l’API de promotions du Microsoft Store, vérifiez que vous avez rempli les conditions préalables suivantes.

• Avant de pouvoir créer et démarrer une campagne publicitaire à l’aide de cette API, vous devez d’abord créer une campagne publicitaire payante à l’aide de la page campagnes publicitaires dans l’Espace partenaires, et vous devez ajouter au moins un instrument de paiement sur cette page. Une fois cette opération effectuée, vous serez en mesure de créer des lignes de remise facturables pour les campagnes publicitaires à l’aide de cette API. Les lignes de remise pour les campagnes publicitaires que vous créez à l’aide de cette API facturent automatiquement l’instrument de paiement par défaut choisi sur la page campagnes publicitaires dans l’Espace partenaires.

• Vous (ou votre organisation) devez disposer d’un annuaire Azure AD et vous devez disposer d''autorisation d’administrateur général pour l’annuaire. Si vous utilisez déjà Microsoft 365 ou d’autres services professionnels de Microsoft, vous disposez déjà d’un annuaire Azure AD. Sinon, vous pouvez créer un Azure AD via l’espace Partenaires sans frais supplémentaires.

• Vous devez associer une application Azure AD à votre compte Espace partenaires, récupérer l’ID de locataire et l’ID client de l’application et générer une clé. L’application Azure AD représente l’application ou le service à partir duquel vous souhaitez appeler l’API de promotions du Microsoft Store. Vous avez besoin de l’ID de locataire, de l’ID client et de la clé pour obtenir un jeton d’accès Azure AD que vous transmettez à l’API.

  Remarque

  Vous n’avez besoin d’effectuer cette tâche qu’une seule fois. Une fois que vous avez l’ID de locataire, l’ID client et la clé, vous pouvez les réutiliser chaque fois que vous devez créer un jeton d’accès Azure AD.

Pour associer une application Azure AD à votre compte Espace partenaires et récupérer les valeurs requises :

1. Dans l’Espace Partenaires, associez votre compte Partner Center à l'Annuaire Azure AD de votre organisation.

2. Ensuite, à partir de la page Utilisateurs dans la section Paramètres du compte de l’Espace partenaires, ajoutez l’application Azure AD qui représente l’application ou le service que vous utiliserez pour gérer les campagnes de promotion pour votre compte Espace partenaires. Veillez à attribuer à cette application le rôle Manager. Si l’application n’existe pas encore dans votre annuaire Azure AD, vous pouvez créer une application Azure AD dans l’Espace partenaires.

3. Retournez sur la page Utilisateurs, cliquez sur le nom de votre application Azure AD pour accéder aux paramètres de l’application, puis copiez les valeurs de l'ID de locataire et de l'ID client .

4. Cliquez sur Ajouter une nouvelle clé. Sur l'écran suivant, recopiez la valeur de la clé . Vous ne pourrez plus accéder à ces informations après avoir quitté cette page. Pour plus d’informations, consultez Gérer les clés pour une application Azure AD.

Étape 2 : Obtenir un jeton d’accès Azure AD

Avant d’appeler l’une des méthodes de l’API de promotions du Microsoft Store, vous devez d’abord obtenir un jeton d’accès Azure AD que vous transmettez à l’en-tête Authorization de chaque méthode dans l’API. Une fois que vous avez récupéré le jeton d’accès, vous avez 60 minutes pour l’utiliser avant qu’il n’expire. Une fois le jeton expiré, vous pouvez actualiser le jeton pour continuer à l’utiliser dans d’autres appels à l’API.

Pour obtenir le jeton d’accès, suivez les instructions de Service aux appels de service à l’aide des informations d’identification du client pour envoyer une requête HTTP POST au point de terminaison https://login.microsoftonline.com/<tenant_id>/oauth2/token. Voici un exemple de requête.

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://manage.devcenter.microsoft.com

Pour la valeur tenant_id dans l’URI POST et les paramètres client_id et client_secret, spécifiez l’ID de locataire, l’ID client et la clé de votre application que vous avez récupérées à partir de l’Espace partenaires dans la section précédente. Pour le paramètre de ressource , vous devez spécifier .

Une fois votre jeton d’accès expiré, vous pouvez l’actualiser en suivant les instructions ici.

Étape 3 : Appeler l’API de promotions du Microsoft Store

Une fois que vous avez un jeton d’accès Azure AD, vous êtes prêt à appeler l’API de promotions du Microsoft Store. Vous devez passer le jeton d’accès à l’en-tête Autorisation de chaque méthode.

Dans le contexte de l’API de promotions du Microsoft Store, une campagne publicitaire se compose d’un objet campagne qui contient des informations de haut niveau sur la campagne, et d’autres objets qui représentent les lignes de distribution , les profils cibles et les créatifs pour la campagne publicitaire. L’API inclut différents ensembles de méthodes regroupés par ces types d’objets. Pour créer une campagne, vous appelez généralement une méthode POST différente pour chacun de ces objets. L’API fournit également des méthodes GET que vous pouvez utiliser pour récupérer tous les objets et méthodes PUT que vous pouvez utiliser pour modifier les objets de campagne, de ligne de distribution et de ciblage d’objets de profil.

Pour plus d’informations sur ces objets et leurs méthodes associées, consultez le tableau suivant.

Le diagramme suivant illustre la relation entre les campagnes, les lignes de livraison, les profils de ciblage et les créatifs.

Exemple de code

L’exemple de code suivant montre comment obtenir un jeton d’accès Azure AD et appeler l’API de promotions du Microsoft Store à partir d’une application console C#. Pour utiliser cet exemple de code, affectez lestenantId , clientId, clientSecretet variables appID aux valeurs appropriées pour votre scénario. Cet exemple nécessite le package Json.NET de Newtonsoft pour désérialiser les données JSON retournées par l’API de promotions du Microsoft Store.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace TestPromotionsAPI
{
    class Program
    {
        static void Main(string[] args)
        {
            string tenantId = "<your tenant ID>";
            string clientId = "<your client ID>";
            string clientSecret = "<your secret>";

            string scope = "https://manage.devcenter.microsoft.com";

            // Retrieve an Azure AD access token
            string accessToken = GetClientCredentialAccessToken(
                    tenantId,
                    clientId,
                    clientSecret,
                    scope).Result;

            int pageSize = 100;
            int startPageIndex = 0;

            // This is your app's Store ID. This ID is available on
            // the App identity page of the Dev Center dashboard.
            string appID = "<your app's Store ID>";


            // Call the Windows Store promotions API
            CallPromotionsAPI(accessToken, appID, pageSize, startPageIndex);

            Console.Read();
        }

        private static void CallPromotionsAPI(string accessToken, string appID, int fetch, int skip)
        {
            string requestURI;

            // Get ad campaigns.
            requestURI = string.Format(
                "https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?applicationId={0}&fetch={1}&skip={2}&campaignSetSortColumn=createdDateTime",
                appID, fetch, skip);

            HttpRequestMessage requestMessage = new HttpRequestMessage(HttpMethod.Get, requestURI);
            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

            WebRequestHandler handler = new WebRequestHandler();
            HttpClient httpClient = new HttpClient(handler);

            HttpResponseMessage response = httpClient.SendAsync(requestMessage).Result;

            Console.WriteLine(response);
            Console.WriteLine(response.Content.ReadAsStringAsync().Result);

            response.Dispose();
        }

        public static async Task<string> GetClientCredentialAccessToken(string tenantId, string clientId, string clientSecret, string scope)
        {
            string tokenEndpointFormat = "https://login.microsoftonline.com/{0}/oauth2/token";
            string tokenEndpoint = string.Format(tokenEndpointFormat, tenantId);

            dynamic result;
            using (HttpClient client = new HttpClient())
            {
                string tokenUrl = tokenEndpoint;
                using (
                    HttpRequestMessage request = new HttpRequestMessage(
                        HttpMethod.Post,
                        tokenUrl))
                {
                    string content =
                        string.Format(
                            "grant_type=client_credentials&client_id={0}&client_secret={1}&resource={2}",
                            clientId,
                            clientSecret,
                            scope);

                    request.Content = new StringContent(content, Encoding.UTF8, "application/x-www-form-urlencoded");

                    using (HttpResponseMessage response = await client.SendAsync(request))
                    {
                        string responseContent = await response.Content.ReadAsStringAsync();
                        result = JsonConvert.DeserializeObject(responseContent);
                    }
                }
            }

            return result.access_token;
        }
    }
}

Rubriques connexes

• Gérer les campagnes publicitaires
• Gérer les lignes de distribution pour les campagnes publicitaires
• Gérer les profils de ciblage pour les campagnes publicitaires
• Gérer les créations pour les campagnes publicitaires
• Obtenir des données de performances de campagne publicitaire