Condividi tramite

Eseguire campagne pubblicitarie con i servizi dello Store

  • Articolo

Usa l'API promozioni di Microsoft Store per gestire programmaticamente le campagne pubblicitarie promozionali per le app registrate nel tuo account del Partner Center 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 passaggi seguenti descrivono il processo end-to-end:

  1. Assicurarsi di aver completato tutti i prerequisiti .
  2. Prima di chiamare un metodo nell'API delle promozioni di Microsoft Store, ottieni un token di accesso di Azure AD. Dopo aver ottenuto un token, hai 60 minuti per usare questo token nelle chiamate all'API per promozioni di Microsoft Store prima della scadenza del token. Dopo la scadenza del token, è possibile generare un nuovo token.
  3. Chiamare l'API delle promozioni di Microsoft Store.

In alternativa, puoi creare e gestire campagne pubblicitarie usando il Centro per i partner e tutte le campagne pubblicitarie create a livello di codice tramite l'API delle promozioni di Microsoft Store possono essere accessibili anche nel Centro per i partner. Per altre informazioni sulla gestione delle campagne pubblicitarie nel Centro per i partner, vedi Creare una campagna pubblicitaria per la tua app.

Nota

Qualsiasi sviluppatore con un account del Centro per i partner può usare l'API promozioni di Microsoft Store per gestire le campagne pubblicitarie per le proprie app. Le agenzie multimediali possono anche richiedere l'accesso a questa API per eseguire campagne pubblicitarie per conto dei propri inserzionisti. Se si è un'agenzia multimediale che vuole saperne di più su questa API o richiedere l'accesso, inviare la richiesta a storepromotionsapi@microsoft.com.

Passaggio 1: Completare i prerequisiti per l'uso dell'API per promozioni di Microsoft Store

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

  • Prima di poter creare e avviare correttamente una campagna pubblicitaria usando questa API, devi prima creare una campagna pubblicitaria a pagamento usando la pagina Campagne pubblicitarie nel Centro per i partnere devi aggiungere almeno uno strumento di pagamento in questa pagina. Dopo aver eseguito questa operazione, sarà possibile creare correttamente righe di recapito fatturabili per le campagne pubblicitarie usando questa API. Le righe di recapito delle campagne pubblicitarie create con questa API addebiteranno automaticamente lo strumento di pagamento predefinito scelto nella pagina Campagne pubblicitarie del Partner Center.

  • L'utente (o l'organizzazione) deve avere una directory di Azure AD ed è necessario disporre dell'autorizzazione amministratore globale per la directory. Se si usa già Microsoft 365 o altri servizi aziendali di Microsoft, si dispone già della directory di Azure AD. In caso contrario, è possibile creare una nuova istanza di 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 per promozioni di Microsoft Store. Sono necessari l'ID tenant, l'ID client e la chiave per ottenere un token di accesso di Azure AD passato all'API.

    Nota

    È sufficiente eseguire questa attività una sola volta. Dopo aver ottenuto l'ID tenant, l'ID client e la chiave, è possibile riutilizzarli ogni volta che è necessario creare un nuovo token di accesso di Azure AD.

Per associare un'applicazione Azure AD all'account del Centro per i partner e recuperare i valori necessari:

  1. In Partner Center, associa l'account del Partner Center della tua organizzazione alla directory di Azure AD della tua organizzazione.

  2. Successivamente, nella sezione Impostazioni account del Centro per i partner, dalla pagina Utenti, aggiungere l'applicazione Azure AD che rappresenta l'app o il servizio che si utilizzerà per 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 accedere alle impostazioni dell'applicazione e annotare i valori di ID tenant e ID client.

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

Passaggio 2: Ottenere un token di accesso di Azure AD

Prima di chiamare uno dei metodi nell'API per promozioni di Microsoft Store, è necessario ottenere un token di accesso di Azure AD passato all'intestazione Authorization di ogni metodo nell'API. Dopo aver ottenuto un token di accesso, si hanno 60 minuti per usarlo prima della scadenza. Dopo la scadenza del token, è possibile aggiornare il token in modo da continuare a usarlo in altre chiamate all'API.

Per ottenere il token di accesso, seguire le istruzioni riportate in Service to Service Calls Using Client Credentials per inviare un HTTP POST all'endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Ecco 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 nell'URI POST e nei parametri client_id e client_secret, specificare l'ID tenant, l'ID client e la chiave per l'applicazione recuperata dal Centro per i partner nella sezione precedente. Per il parametro della risorsa, è necessario specificare https://manage.devcenter.microsoft.com.

Dopo la scadenza del token di accesso, è possibile aggiornarlo seguendo le istruzioni qui.

Passaggio 3: Chiamare l'API promozioni di Microsoft Store

Dopo aver ottenuto un token di accesso di Azure AD, è possibile chiamare l'API per le promozioni di Microsoft Store. È necessario passare il token di accesso all'header Autorizzazione di ogni metodo.

Nel contesto dell'API delle promozioni di Microsoft Store, una campagna pubblicitaria è costituita da un oggetto campagna che contiene informazioni di alto livello sulla campagna e oggetti aggiuntivi che rappresentano le righe di recapito , i profili di targeting e i materiali creativi per la campagna pubblicitaria. L'API include diversi set di metodi raggruppati in base a questi tipi di oggetto. Per creare una campagna, in genere chiami un metodo POST diverso per ognuno di questi oggetti. L'API fornisce anche metodi GET che è possibile usare per recuperare qualsiasi oggetto e metodi PUT che è possibile usare per modificare gli oggetti di campagna, linea di recapito e profilo di targeting.

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

Oggetto Descrizione
Campagne Questo oggetto rappresenta la campagna pubblicitaria e si trova nella parte superiore della gerarchia del modello a oggetti per le campagne pubblicitarie. Questo elemento identifica il tipo di campagna in corso (a pagamento, interna o community), l'obiettivo della campagna, le linee di consegna della campagna e altri dettagli. Ogni campagna può essere associata a una sola app.

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

Nota Dopo aver creato una campagna pubblicitaria, puoi recuperare i dati sulle prestazioni per la campagna usando il metodo "Get ad campaign performance data" (Ottieni dati sulle prestazioni della campagna pubblicitaria) nell'API di analisi del Microsoft Store .
Linee di consegna Ogni campagna ha una o più linee di consegna usate per acquistare l'inventario e recapitare gli annunci. Per ogni riga di consegna, è possibile impostare la targetizzazione, impostare un'offerta e decidere quanto spendere stabilendo un budget e collegando le creatività che desideri utilizzare.

Per ulteriori informazioni sui metodi correlati a questo oggetto, vedere Gestire le linee di consegna per le campagne pubblicitarie.
Profili di destinazione Ogni riga di recapito ha un profilo di destinazione che specifica gli utenti, le aree geografiche e i tipi di inventario che si desidera raggiungere. I profili di destinazione possono essere creati come modello e condivisi tra le linee di consegna.

Per altre informazioni sui metodi correlati a questo oggetto, vedere Gestire i profili di destinazione per le campagne pubblicitarie.
Creatività Ogni linea di consegna ha uno o più contenuti creativi che rappresentano gli annunci che vengono visualizzati ai clienti come parte della campagna. Una creatività può essere associata a una o più linee di consegna, anche tramite annunci, purché 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, linee di recapito, profili di destinazione e creativi.

gerarchia di 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 tenantId, clientId, clientSecrete variabili appID ai valori appropriati per lo scenario. Questo esempio richiede il pacchetto Json.NET di Newtonsoft per la deserializzazione dei dati JSON restituiti dall'API delle promozioni del 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;
        }
    }
}