Veicular campanhas publicitárias usando os serviços da Store

Use a API de promoções da Microsoft Store para gerenciar programaticamente campanhas publicitárias promocionais para aplicativos registrados na conta do Partner Center da sua organização. Essa API permite que você crie, atualize e monitore suas campanhas e outros ativos relacionados, como direcionamento e criativos. Essa API é especialmente útil para desenvolvedores que criam grandes volumes de campanhas e que desejam fazê-lo sem usar o Partner Center. Essa API usa o Active Directory do Azure (Azure AD) para autenticar as chamadas do seu aplicativo ou serviço.

As etapas a seguir descrevem o processo completo:

1. Certifique-se de que você tenha concluído todos os pré-requisitos.
2. Antes de chamar um método na API de promoções da Microsoft Store obtenha um token de acesso do Azure AD. Depois de obter um token, você terá 60 minutos para usá-lo em chamadas à API de promoções da Microsoft Store antes que ele expire. Depois que o token expirar, será possível gerar um novo.
3. Chame a API de promoções da Microsoft Store.

Como alternativa, você pode criar e gerenciar campanhas publicitárias usando o Partner Center e todas as campanhas publicitárias criadas programaticamente por meio da API de promoções da Microsoft Store também podem ser acessadas no Partner Center. Para obter mais informações sobre como gerenciar campanhas publicitárias no Partner Center, consulte Criar uma campanha publicitária para seu aplicativo.

Observação

Qualquer desenvolvedor com uma conta do Partner Center pode usar a API de promoções da Microsoft Store para gerenciar campanhas publicitárias para seus aplicativos. Agências de mídia também podem solicitar acesso a essa API para executar campanhas publicitárias em nome dos seus anunciantes. Se você for uma agência de mídia que deseja saber mais sobre essa API ou solicitar acesso à ela, envie sua solicitação para storepromotionsapi@microsoft.com.

Etapa 1: Concluir os pré-requisitos para usar a API de promoções da Microsoft Store

Antes de começar a escrever o código para chamar a API de promoções da Microsoft Store, certifique-se de que você concluiu os pré-requisitos a seguir.

• Antes de criar e iniciar uma campanha publicitária com êxito usando essa API, você deve primeiro criar uma campanha publicitária paga usando a página campanhas publicitárias no Partner Center e adicionar pelo menos um meio de pagamento nesta página. Depois que você fizer isso, é possível criar linhas de entrega faturáveis para campanhas publicitárias usando essa API. As linhas de entrega para campanhas publicitárias criadas usando essa API cobrarão automaticamente o instrumento de pagamento padrão escolhido na página Campanhas publicitárias no Partner Center.

• Você (ou sua organização) deve ter um diretório do Azure AD e você deve ter permissão de Administrador global para o diretório. Se já usa o Microsoft 365 ou outros serviços comerciais da Microsoft, você já tem o diretório do Azure AD. Caso contrário, você pode criar uma nova Azure AD no Partner Center sem custo adicional.

• Você deve associar um aplicativo Azure AD à sua conta do Partner Center, recuperar a ID do locatário e a ID do cliente do aplicativo e gerar uma chave. O aplicativo do Azure AD representa o aplicativo ou serviço do qual você quer chamar a API de promoções da Microsoft Store. Você precisa da ID do locatário, da ID do cliente e da chave para obter um token de acesso do Azure AD que é passado para a API.

  Observação

  Você só precisa executar essa tarefa uma vez. Depois de obter a ID do locatário, a ID do cliente e a chave, você poderá reutilizá-las sempre que precisar criar um novo token de acesso do Azure AD.

Para associar um aplicativo Azure AD à sua conta do Partner Center e recuperar os valores necessários:

1. No Partner Center, associe a conta do Partner Center da sua organização ao diretório do Azure AD da sua organização.

2. Em seguida, na página Usuários na seção Configurações de conta do Partner Center, adicione o aplicativo Azure AD que representa o aplicativo ou serviço que você usará para gerenciar campanhas de promoção para sua conta do Partner Center. Lembre-se de atribuir esse aplicativo à função de Gerenciador. Se o aplicativo ainda não existir no diretório do Azure AD, crie um novo aplicativo do Azure AD no Partner Center.

3. Retorne à página Usuários, clique no nome do seu aplicativo do Azure AD para acessar as configurações do aplicativo e copie os valores de ID do Locatário e ID do Cliente.

4. Clique em Adicionar nova chave. Na tela a seguir, copie o valor da Chave. Você não poderá acessar essas informações novamente depois de sair da página. Para saber mais, veja Gerenciar chaves de um aplicativo do Azure AD.

Etapa 2: Obtenção de um token de acesso do Azure AD

Antes de chamar qualquer um dos métodos na API de promoções da Microsoft Store, primeiro você deve obter um token de acesso do Azure AD que você passa para o cabeçalho Autorização de cada método na API. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá atualizar o token para que você possa continuar a usá-lo em outras chamadas à API.

Para obter o token de acesso, siga as instruções em Chamadas de serviço a serviço usando credenciais do cliente para enviar um HTTP POST para o ponto de extremidade https://login.microsoftonline.com/<tenant_id>/oauth2/token. Aqui está um exemplo de solicitação.

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

Para o valor tenant_id no URI POST e os parâmetros client_id e client_secret , especifique a ID do locatário, a ID do cliente e a chave do aplicativo que você recuperou do Partner Center na seção anterior. Para o parâmetro resource, especifique https://manage.devcenter.microsoft.com.

Depois que seu token de acesso expirar, você poderá atualizá-lo seguindo as instruções descritas aqui.

Etapa 3: Chamar a API de promoções da Microsoft Store

Depois que tiver um token de acesso do Azure AD, você estará pronto para chamar a API de promoções da Microsoft Store. Você deve passar o token de acesso no cabeçalho Autorização de cada método.

No contexto da API de promoções da Microsoft Store, uma campanha publicitária consiste em um objeto de campanha que contém informações de alto nível sobre a campanha e outros objetos que representam as linhas de entrega, perfis de direcionamento, e criativos para a campanha publicitária. A API inclui diferentes conjuntos de métodos que são agrupados por esses tipos de objetos. Para criar uma campanha, você normalmente chama um método POST diferente para cada um desses objetos. A API também fornece métodos GET, que você pode usar para recuperar qualquer objeto e métodos PUT, que você pode usar para editar a campanha, linha de entrega e objetos de perfil de direcionamento.

Para obter mais informações sobre esses objetos e seus métodos relacionados, consulte a tabela a seguir.

Objeto	Descrição
Campanhas	Esse objeto representa a campanha publicitária e fica na parte superior da hierarquia de modelos de objeto das campanhas publicitárias. Esse objeto identifica o tipo de campanha que você está executando (pago, doméstico ou comunidade), o objetivo de campanha, as linhas de entrega da campanha e outros detalhes. Cada campanha pode ser associada a apenas um aplicativo. Para obter mais informações sobre os métodos relacionados a esse objeto, consulte Gerenciar as campanhas publicitárias. Nota Depois de criar uma campanha publicitária, você pode recuperar dados de desempenho para a campanha usando o método Obter dados de desempenho da campanha publicitária na API de análise da Microsoft Store.
Linhas de entrega	Cada campanha tem uma ou mais linhas de entrega que são usadas para comprar inventário e fornecer seus anúncios. Para cada linha de entrega, você pode definir direcionamento, o preço da oferta e decidir quanto deseja gastar ao definir um orçamento e vincular aos criativos que deseja usar. Para obter mais informações sobre os métodos relacionados a esse objeto, consulte Gerenciar linhas de entrega de campanhas publicitárias.
Perfis de direcionamento	Cada linha de entrega tem um perfil de direcionamento que especifica os usuários, regiões geográficas e tipos de inventário que você deseja direcionar. Perfis de direcionamento podem ser criados como um modelo e compartilhados entre as linhas de entrega. Para obter mais informações sobre os métodos relacionados a esse objeto, consulte Gerenciar perfis de direcionamento de campanhas publicitárias.
Criativos	Cada linha de entrega tem um ou mais criativos que representam os anúncios que são mostrados para os clientes como parte da campanha. Um criativo pode ser associado a uma ou mais linhas de entrega, mesmo em campanhas publicitárias, considerando sempre representa o mesmo app. Para obter mais informações sobre os métodos relacionados a esse objeto, consulte Gerenciar criativos de campanhas publicitárias.

O diagrama a seguir ilustra a relação entre campanhas, linhas de entrega, perfis de direcionamento, e criativos.

Exemplo de código

O exemplo de código a seguir demonstra como obter um token de acesso do Azure AD e chamar a API de promoções da Microsoft Store de um aplicativo de console C#. Para usar este exemplo de código, atribua as variáveis tenantId, clientId, clientSecret e appID aos valores adequados ao seu cenário. Este exemplo exige o pacote Json.NET do Newtonsoft para desserializar os dados JSON retornados pela API de promoções da 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;
        }
    }
}

Tópicos relacionados

• Gerenciar campanhas publicitárias
• Gerenciar linhas de entrega de campanhas publicitárias
• Gerenciar perfis de direcionamento de campanhas publicitárias
• Gerenciar criativos de campanhas publicitárias
• Obter dados de desempenho da campanha publicitária