Condividi tramite

Eseguire campagne pubblicitarie utilizzando i servizi dello Store

  • Articolo

Utilizzare l'API Promozioni di Microsoft Store per gestire a livello di codice le campagne pubblicitarie promozionali per le app registrate nell'account del Centro per i partner dell'utente o dell'organizzazione. Questa API consente di creare, aggiornare e monitorare le campagne e altri asset correlati, ad esempio targeting e creatività. Questa API è particolarmente utile per gli sviluppatori che creano grandi volumi di campagne e che vogliono farlo senza usare il Centro per i partner. Questa API usa Azure Active Directory (Azure AD) per autenticare le chiamate dall'app o dal servizio.

I seguenti passaggi descrivono il processo end-to-end:

  1. Assicurarsi di aver completato tutti i prerequisiti.
  2. Prima di chiamare un metodo nell'API Promozioni di Microsoft Store, ottenere un token di accesso di Azure AD. Dopo averlo ottenuto, l'utente ha 60 minuti per utilizzare il token nelle chiamate all'API Promozioni di Microsoft Store prima della scadenza del token. Dopo la scadenza del token, è possibile generarne uno nuovo.
  3. Chiamare l'API Promozioni di Microsoft Store.

In alternativa, è possibile creare e gestire campagne pubblicitarie utilizzando il Centro per i partner; in questo modo, si potrà accedere a tutte le campagne pubblicitarie create a livello di codice con l'API Promozioni di Microsoft Store anche dal Centro per i partner. Per ulteriori informazioni sulla gestione delle campagne pubblicitarie nel Centro per i partner, vedere Crea una campagna pubblicitaria per la tua app.

Nota

Qualsiasi sviluppatore che sia dotato di un account del Centro per i partner può utilizzare l'API Promozioni di Microsoft Store per gestire le campagne pubblicitarie per le proprie app. Anche le agenzie di comunicazione possono richiedere l'accesso a questa API per eseguire campagne pubblicitarie per conto dei propri inserzionisti. Le agenzie di comunicazione che desiderano saperne di più su questa API o richiederne l'accesso devono inviare la richiesta a storepromotionsapi@microsoft.com.

Passaggio 1: completare i prerequisiti per l'uso dell'API Promozioni di Microsoft Store

Prima di iniziare a scrivere il codice per chiamare l'API Promozioni di Microsoft Store, verificare di aver completato i prerequisiti seguenti.

  • Prima di poter creare e lanciare una campagna pubblicitaria utilizzando questa API, è necessario innanzitutto creare una campagna pubblicitaria a pagamento con la pagina Campagne pubblicitarie nel Centro per i partner ed è necessario aggiungere su questa pagina almeno uno strumento di pagamento. Dopo aver eseguito questa operazione, sarai in grado di creare correttamente linee di consegna fatturabili per campagne pubblicitarie utilizzando questa API. Le righe consegna per le campagne pubblicitarie create utilizzando questa API fattureranno automaticamente lo strumento di pagamento predefinito scelto nella pagina di Ad campaigns nel Partner Center.

  • L'utente o l'organizzazione deve disporre di una directory di Azure AD e dell'autorizzazione come amministratore aziendale per la directory. Se si usa già Microsoft 365 o altri servizi aziendali Microsoft, si dispone già di una directory di Azure AD. Altrimenti puoi creare un nuovo Azure AD nel Centro per i partner senza costi aggiuntivi.

  • È necessario associare un'applicazione Azure AD all'account del Centro per i partner, recuperare l'ID tenant e l'ID client per l'applicazione e generare una chiave. L'applicazione Azure AD rappresenta l'app o il servizio da cui si vuole chiamare l'API Promozioni di Microsoft Store. Per ottenere un token di accesso di Azure AD da passare all'API, sono necessari l'ID tenant, l'ID client e la chiave.

    Nota

    È sufficiente eseguire questa attività una sola volta. Quando si dispone di ID tenant, ID client e chiave, è possibile riutilizzarli ogni volta che è necessario creare un nuovo token di accesso Azure AD.

Per associare un'applicazione Azure AD al tuo account del Centro per i partner e recuperare i valori richiesti:

  1. Nel Centro per i partner, associare l'account del Centro per i partner dell'organizzazione alla directory di Azure AD dell'organizzazione.

  2. Quindi, dalla pagina Utenti nella sezione Impostazioni account del Centro per i partner, aggiungere l'applicazione Azure AD che rappresenta l'app o il servizio che verrà usato gestire le campagne promozionali per l'account del Centro per i partner. Assicurarsi di assegnare a questa applicazione il ruolo di Manager. Se l'applicazione non esiste ancora nella directory di Azure AD, è possibile creare una nuova applicazione Azure AD nel Centro per i partner.

  3. Tornare alla pagina Utenti, fare clic sul nome dell'applicazione Azure AD per passare alle impostazioni e copiare i valori di ID tenant e ID client.

  4. Fare clic su Aggiungi nuova chiave. Nella schermata seguente, copiare il valore della chiave. Non sarà più possibile accedere a queste informazioni dopo aver lasciato la pagina. Per altre informazioni, vedi Gestire le chiavi per un'applicazione Azure AD.

Passaggio 2: ottenere un token di accesso di Azure AD

Prima di chiamare un metodo nell'API Promozioni di Microsoft Store, è necessario ottenere un token di accesso di Azure AD da passare all'intestazione Autorizzazione di ogni metodo nell'API. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza. Dopo la scadenza del token, è possibile aggiornarlo in modo da continuare a usarlo nelle successive chiamate all'API.

Per ottenere il token di accesso, seguire le istruzioni riportate in Chiamate da servizio a servizio mediante le credenziali client per inviare un HTTP POST all'endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Di seguito è riportata una richiesta di esempio.

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

Per il valore tenant_id in POST URI e per i parametri client_id e client_secret, specificare l'ID tenant, l'ID client e la chiave per l'applicazione recuperati dal Centro per i partner nella sezione precedente. Per il parametro resource è necessario specificare https://manage.devcenter.microsoft.com.

Una volta scaduto il token di accesso, puoi aggiornarlo seguendo le istruzioni qui.

Passaggio 3: chiamare l'API Promozioni di Microsoft Store

Una volta ottenuto un token di accesso di Azure AD, è possibile chiamare l'API Promozioni Microsoft Store. È necessario passare il token di accesso all'intestazione Autorizzazione di ciascun metodo.

Nel contesto dell'API Promozioni di Microsoft Store, una campagna pubblicitaria consiste in un oggetto campagna contenente informazioni generiche sulla campagna e in altri oggetti che rappresentano le righe consegna, i profili di targeting e le creatività della campagna pubblicitaria. L'API include diversi set di metodi che vengono raggruppati in base ai tipi di oggetto. Per creare una campagna, in genere si chiama un metodo POST diverso per ognuno degli oggetti. L'API fornisce anche metodi GET (che servono a recuperare qualsiasi oggetto) e metodi PUT che servono a modificare gli oggetti campagna, riga consegna e profilo di targeting.

Per altre informazioni su questi oggetti e sui metodi a loro correlati, vedere la tabella seguente.

Oggetto Descrizione
Campagne Questo oggetto rappresenta la campagna pubblicitaria ed è il più alto nella gerarchia del modello a oggetti per le campagne pubblicitarie. Questo oggetto identifica il tipo di campagna in esecuzione (a pagamento, casa o community), l'obiettivo della campagna, le righe consegna per la campagna e altri dettagli. Ogni campagna può essere associata a una sola app.

Per altre informazioni sui metodi correlati a questo oggetto, vedere Gestire campagne pubblicitarie.

Nota Una volta creata una campagna pubblicitaria, è possibile recuperare i dati relativi alle prestazioni della campagna utilizzando il metodo Ottenere i dati sulle prestazioni delle campagne pubblicitarie nella API di analisi di Microsoft Store.
Righe consegna Ogni campagna è dotata di una o più righe consegna, che vengono utilizzate per acquistare spazi pubblicitari e pubblicare gli annunci. Per ciascuna linea di consegna, puoi impostare il targeting, impostare il prezzo dell'offerta e decidere quanto vuoi spendere impostando un budget e collegandoti alle creatività che desideri utilizzare.

Per altre informazioni sui metodi correlati a questo oggetto, vedere Gestire le righe consegna per le campagne pubblicitarie.
Profili di targeting Ogni riga consegna è dotata di un profilo di targeting che specifica i tipi target di utenti, aree geografiche e spazi pubblicitari. Si può creare un modello dei profili di targeting e condividerlo tra le righe consegna.

Per altre informazioni sui metodi correlati a questo oggetto, vedere Gestire i profili di targeting per le campagne pubblicitarie.
Creatività Ogni riga consegna è dotata di una o più creatività, che rappresentano gli annunci che vengono mostrati ai clienti nell'ambito della campagna. Una creatività può essere associata a una o più linee di consegna, anche tra campagne pubblicitarie, a condizione che rappresenti sempre la stessa app.

Per altre informazioni sui metodi correlati a questo oggetto, vedere Gestire le creatività per le campagne pubblicitarie.

Il diagramma seguente illustra la relazione tra campagne, righe consegna, profili di destinazione e creatività.

Gerarchia delle campagne pubblicitarie

Esempio di codice

L'esempio di codice seguente illustra come ottenere un token di accesso di Azure AD e chiamare l'API Promozioni di Microsoft Store da un'app console C#. Per usare questo esempio di codice, assegnare le variabili tenantId, clientId, clientSecret, and appID ai valori appropriati per lo scenario. Questo esempio richiede che il pacchetto Json.NET di Newtonsoft deserializzi i dati JSON restituiti dall'API Promozioni di 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;
        }
    }
}