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

Utilisez l’API de promotions du Microsoft Store pour gérer par programmation les campagnes publicitaires promotionnelles pour les applications inscrites dans votre compte espace partenaires ou votre organization. Cette API vous permet de créer, de mettre à jour et de 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 en provenance 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. Une fois que vous avez obtenu un jeton, vous disposez de 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 nouveau.
3. Appelez l’API des 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 programme via l’API de 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.

Notes

Tout développeur disposant d’un compte espace partenaires peut utiliser l’API de promotions du Microsoft Store pour gérer les campagnes publicitaires pour ses applications. Les agences de médias peuvent également demander l’accès à cette API pour exécuter des campagnes publicitaires au nom de leurs annonceurs. Si vous êtes une agence de médias qui souhaite en savoir plus sur cette API ou demander l’accès à celle-ci, envoyez votre demande à storepromotionsapi@microsoft.com.

Étape 1 : Remplir les conditions préalables à 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, assurez-vous 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. Après cela, vous serez en mesure de créer des lignes de distribution facturables pour les campagnes publicitaires à l’aide de cette API. Les lignes de livraison pour les 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 de 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 nouvel 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.

  Notes

  Vous n’avez besoin d’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 de 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, voir 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 de 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 arrivé à expiration, vous pouvez l’actualiser pour pouvoir continuer à l’utiliser dans d’autres appels à l’API.

Pour obtenir le jeton d’accès, suivez les instructions présentées dans l’article 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 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és à partir de l’Espace partenaires dans 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 arrivé à expiration, vous pouvez l’actualiser en suivant les instructions fournies ici.

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

Une fois que vous disposez d’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 Authorization 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 d’objets supplémentaires qui représentent les lignes de distribution, les profils de ciblage et les créations de la campagne publicitaire. L’API inclut différents ensembles de méthodes qui sont 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 remise et de profil de ciblage.

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

Object	Description
Campagnes	Cet objet représente la campagne publicitaire et se trouve en haut de la hiérarchie du modèle objet pour les campagnes publicitaires. Cet objet identifie le type de campagne que vous exécutez (payante, maison ou communauté), l’objectif de la campagne, les lignes de livraison de la campagne et d’autres détails. Chaque campagne ne peut être associée qu’à une seule application. Pour plus d’informations sur les méthodes associées à cet objet, consultez Gérer les campagnes publicitaires. Note Après avoir créé une campagne publicitaire, vous pouvez récupérer des données de performances pour la campagne à l’aide de la méthode Obtenir les données de performances de la campagne publicitaire dans l’API d’analyse du Microsoft Store.
Lignes de livraison	Chaque campagne a une ou plusieurs lignes de livraison qui sont utilisées pour acheter l’inventaire et diffuser vos annonces. Pour chaque ligne de livraison, vous pouvez définir le ciblage, définir le prix de votre offre et décider du montant que vous souhaitez dépenser en définissant un budget et en liant les créations que vous souhaitez utiliser. Pour plus d’informations sur les méthodes associées à cet objet, consultez Gérer les lignes de distribution pour les campagnes publicitaires.
Ciblage des profils	Chaque ligne de livraison a un profil de ciblage qui spécifie les utilisateurs, les zones géographiques et les types d’inventaire que vous souhaitez cibler. Les profils de ciblage peuvent être créés en tant que modèle et partagés entre les lignes de livraison. Pour plus d’informations sur les méthodes associées à cet objet, consultez Gérer les profils de ciblage pour les campagnes publicitaires.
Créatifs	Chaque ligne de livraison a une ou plusieurs créations qui représentent les annonces affichées aux clients dans le cadre de la campagne. Un créatif peut être associé à une ou plusieurs lignes de livraison, même entre les campagnes publicitaires, à condition qu’il représente toujours la même application. Pour plus d’informations sur les méthodes associées à cet objet, consultez Gérer les créations pour les campagnes publicitaires.

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

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 livraison 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