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

Utilisez l’API de promotions du Microsoft Store pour gérer par programmation les campagnes publicitaires promotionnelles pour les applications inscrites auprès de votre compte Espace partenaires de votre organisation ou de votre organisation. 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, obtenez 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 arrivé à expiration, vous pouvez en générer un autre.
3. Appelez 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 des campagnes publicitaires que vous créez à l’aide de cette API facturent automatiquement l’instrument de paiement par défaut choisi dans la page Campagnes publicitaires dans l’Espace partenaires.

• Vous (ou votre organisation) devez disposer d’un annuaire Azure AD et de l’autorisation Administrateur général sur 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 annuaire Azure AD dans 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. Il vous faut l’ID tenant, l’ID client et la clé pour obtenir un jeton d’accès Azure AD à transmettre à l’API.

  Remarque

  Vous ne devez effectuer cette tâche qu’une seule fois. Une fois que vous les avez, vous pouvez réutiliser l’ID tenant, l’ID client et la clé 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 le compte Espace partenaires de votre organisation à l’annuaire Azure AD de votre organisation.

2. Ensuite, dans la page Utilisateurs de 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 Gestionnaire. 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. Revenez à la page Utilisateurs, cliquez sur le nom de votre application Azure AD pour accéder à ses paramètres, puis copiez les valeurs ID tenant et ID client.

4. Cliquez sur Ajouter une nouvelle clé. Sur l’écran suivant, copiez la valeur Clé. Vous ne pourrez plus accéder à cette information une fois que vous aurez 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 passez à l’en-tête d’autorisation 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. Après l'expiration du jeton, vous pouvez le rafraîchir afin de pouvoir continuer à l'utiliser lors d'autres appels à l'API.

Pour obtenir le jeton d’accès, suivez les instructions de la section Appels de service à 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 le POST URI et les paramètres client_id et client_secret, spécifiez l’ID du locataire, l’ID de client et la clé de votre application que vous avez récupérée dans l’Espace partenaires à la section précédente. Pour le paramètre resource, vous devez spécifier https://manage.devcenter.microsoft.com.

Une fois votre jeton d’accès expiré, vous pouvez l’actualiser en suivant les instructions fournies 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 transmettre le jeton d’accès à l’en-tête d’autorisation de chaque méthode.

Dans le contexte de l’API de promotions du Microsoft Store, une campagne publicitaire se compose d’un objet de campagne qui contient des informations générales sur la campagne et des objets supplémentaires qui représentent les lignes de livraison, les profils de ciblage et les créatifs de 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 les variables tenantId, clientId, clientSecret et 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 les données relatives aux performances de la campagne publicitaire