Veicular campanhas publicitárias usando os serviços da StoreRun ad campaigns using Store services

Use a API de promoções de Microsoft Store para gerenciar programaticamente campanhas publicitárias promocionais para aplicativos que estão registrados em sua conta do centro de parceiros da sua organização.Use the Microsoft Store promotions API to programmatically manage promotional ad campaigns for apps that are registered to your or your organization's Partner Center account. Essa API permite que você crie, atualize e monitore suas campanhas e outros ativos relacionados, como direcionamento e criativos.This API enables you to create, update and monitor your campaigns and other related assets such as targeting and creatives. Essa API é especialmente útil para os desenvolvedores que criam grandes volumes de campanhas e que desejam fazer isso sem usar o Partner Center.This API is especially useful for developers who create large volumes of campaigns, and who want to do so without using Partner Center. Essa API usa o Active Directory do Azure (Azure AD) para autenticar as chamadas do seu aplicativo ou serviço.This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

As etapas a seguir descrevem o processo completo:The following steps describe the end-to-end process:

  1. Certifique-se de que você tenha concluído todos os pré-requisitos.Make sure that you have completed all the prerequisites.
  2. Antes de chamar um método na API de promoções da Microsoft Store obtenha um token de acesso do Azure AD.Before you call a method in the Microsoft Store promotions API, obtain an Azure AD access token. 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.After you obtain a token, you have 60 minutes to use this token in calls to the Microsoft Store promotions API before the token expires. Depois que o token expirar, será possível gerar um novo.After the token expires, you can generate a new token.
  3. Chame a API de promoções da Microsoft Store.Call the Microsoft Store promotions API.

Como alternativa, você pode criar e gerenciar campanhas do AD usando o Partner Center e todas as campanhas do AD que você cria programaticamente por meio da API de promoções de Microsoft Store também podem ser acessadas no Partner Center.You can alternatively create and manage ad campaigns using Partner Center, and any ad campaigns that you create programmatically via the Microsoft Store promotions API can also be accessed in Partner Center. Para obter mais informações sobre como gerenciar campanhas do AD no Partner Center, consulte criar uma campanha do AD para seu aplicativo.For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

Observação

Qualquer desenvolvedor com uma conta do Partner Center pode usar a API de promoções de Microsoft Store para gerenciar campanhas do AD para seus aplicativos.Any developer with a Partner Center account can use the Microsoft Store promotions API to manage ad campaigns for their apps. Agências de mídia também podem solicitar acesso a essa API para executar campanhas publicitárias em nome dos seus anunciantes.Media agencies can also request access to this API to run ad campaigns on behalf of their advertisers. 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.If you are a media agency who wants to know more about this API or request access to it, send your request to storepromotionsapi@microsoft.com.

Etapa 1: Concluir os pré-requisitos para usar a API de promoções da Microsoft StoreStep 1: Complete prerequisites for using the Microsoft Store promotions API

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.Before you start writing code to call the Microsoft Store promotions API, make sure that you have completed the following prerequisites.

  • Antes de poder criar e iniciar com êxito uma campanha do AD usando essa API, você deve primeiro criar uma campanha paga do AD usando a página campanhas do AD no Partner Centere adicionar pelo menos um instrumento de pagamento nesta página.Before you can successfully create and start an ad campaign using this API, you must first create one paid ad campaign using the Ad campaigns page in Partner Center, and you must add at least one payment instrument on this page. Depois que você fizer isso, é possível criar linhas de entrega faturáveis para campanhas publicitárias usando essa API.After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. As linhas de entrega para campanhas do AD que você cria usando essa API cobrarão automaticamente o instrumento de pagamento padrão escolhido na página campanhas do AD no Partner Center.Delivery lines for ad campaigns you create using this API will automatically bill the default payment instrument chosen on the Ad campaigns page in 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.You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. Se você já usa Microsoft 365 ou outros serviços corporativos da Microsoft, você já tem o diretório do Azure AD.If you already use Microsoft 365 or other business services from Microsoft, you already have Azure AD directory. Caso contrário, você pode criar um novo Azure AD no Partner Center sem custo adicional.Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • Você deve associar um aplicativo do Azure AD à sua conta do Partner Center, recuperar a ID do locatário e a ID do cliente para o aplicativo e gerar uma chave.You must associate an Azure AD application with your Partner Center account, retrieve the tenant ID and client ID for the application and generate a key. O aplicativo do Azure AD representa o aplicativo ou serviço do qual você quer chamar a API de promoções da Microsoft Store.The Azure AD application represents the app or service from which you want to call the Microsoft Store promotions API. 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.You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    Observação

    Você só precisa executar essa tarefa uma vez.You only need to perform this task one time. 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.After you have the tenant ID, client ID and key, you can reuse them any time you need to create a new Azure AD access token.

Para associar um aplicativo do Azure AD à sua conta do Partner Center e recuperar os valores necessários:To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. No Partner Center, associe a conta do Partner Center da sua organização ao diretório do Azure AD da sua organização.In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. Em seguida, na página usuários na seção configurações de conta do Partner Center, adicione o aplicativo do Azure ad que representa o aplicativo ou serviço que você usará para gerenciar campanhas de promoção para sua conta do Partner Center.Next, from the Users page in the Account settings section of Partner Center, add the Azure AD application that represents the app or service that you will use to manage promotion campaigns for your Partner Center account. Lembre-se de atribuir esse aplicativo à função de Gerenciador.Make sure you assign this application the Manager role. Se o aplicativo ainda não existir no diretório do Azure AD, crie um novo aplicativo do Azure AD no Partner Center.If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in 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.Return to the Users page, click the name of your Azure AD application to go to the application settings, and copy down the Tenant ID and Client ID values.

  4. Clique em Adicionar nova chave.Click Add new key. Na tela a seguir, copie o valor da Chave.On the following screen, copy down the Key value. Você não poderá acessar essas informações novamente depois de sair da página.You won't be able to access this info again after you leave this page. Para saber mais, veja Gerenciar chaves de um aplicativo do Azure AD.For more information, see Manage keys for an Azure AD application.

Etapa 2: Obtenção de um token de acesso do Azure ADStep 2: Obtain an Azure AD access token

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.Before you call any of the methods in the Microsoft Store promotions API, you must first obtain an Azure AD access token that you pass to the Authorization header of each method in the API. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar.After you obtain an access token, you have 60 minutes to use it before it expires. Depois que o token expirar, você poderá atualizar o token para que você possa continuar a usá-lo em outras chamadas à API.After the token expires, you can refresh the token so you can continue to use it in further calls to the 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.To obtain the access token, follow the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. Aqui está um exemplo de solicitação.Here is a sample request.

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 da * _ ID de locatário* no URI de postagem e os parâmetros de * _ ID do cliente* e * _ segredo do cliente* , 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.For the tenant_id value in the POST URI and the client_id and client_secret parameters, specify the tenant ID, client ID and the key for your application that you retrieved from Partner Center in the previous section. Para o parâmetro resource, especifique https://manage.devcenter.microsoft.com.For the resource parameter, you must specify https://manage.devcenter.microsoft.com.

Depois que seu token de acesso expirar, você poderá atualizá-lo seguindo as instruções descritas aqui.After your access token expires, you can refresh it by following the instructions here.

Etapa 3: Chamar a API de promoções da Microsoft StoreStep 3: Call the Microsoft Store promotions API

Depois que tiver um token de acesso do Azure AD, você estará pronto para chamar a API de promoções da Microsoft Store.After you have an Azure AD access token, you are ready to call the Microsoft Store promotions API. Você deve passar o token de acesso no cabeçalho Autorização de cada método.You must pass the access token to the Authorization header of each method.

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.In the context of the Microsoft Store promotions API, an ad campaign consists of a campaign object that contains high-level information about the campaign, and additional objects that represent the delivery lines, targeting profiles, and creatives for the ad campaign. A API inclui diferentes conjuntos de métodos que são agrupados por esses tipos de objetos.The API includes different sets of methods that are grouped by these object types. Para criar uma campanha, você normalmente chama um método POST diferente para cada um desses objetos.To create a campaign, you typically call a different POST method for each of these objects. 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.The API also provides GET methods you can use to retrieve any object and PUT methods you can use to edit campaign, delivery line, and targeting profile objects.

Para obter mais informações sobre esses objetos e seus métodos relacionados, consulte a tabela a seguir.For more information about these objects and their related methods, see the following table.

ObjetoObject DescriçãoDescription
CampanhasCampaigns Esse objeto representa a campanha publicitária e fica na parte superior da hierarquia de modelos de objeto das campanhas publicitárias.This object represents the ad campaign, and it sits at the top of the object model hierarchy for ad campaigns. 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.This object identifies the type of campaign you are running (paid, house, or community), the campaign objective, the delivery lines for the campaign, and other details. Cada campanha pode ser associada a apenas um aplicativo.Each campaign can be associated with only one app.

Para obter mais informações sobre os métodos relacionados a esse objeto, consulte Gerenciar as campanhas publicitárias.For more information about the methods related to this object, see Manage ad campaigns.

Note   Observação   Depois de criar uma campanha do AD, você pode recuperar dados de desempenho para a campanha usando o método obter dados de desempenho da campanha do AD na API do Microsoft Store Analytics.Note  After you create an ad campaign, you can retrieve performance data for the campaign by using the Get ad campaign performance data method in the Microsoft Store analytics API.
Linhas de entregaDelivery lines Cada campanha tem uma ou mais linhas de entrega que são usadas para comprar inventário e fornecer seus anúncios.Every campaign has one or more delivery lines that are used to buy inventory and deliver your ads. 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.For each delivery line, you can set targeting, set your bid price, and decide how much you want to spend by setting a budget and linking to creatives you want to use.

Para obter mais informações sobre os métodos relacionados a esse objeto, consulte Gerenciar linhas de entrega de campanhas publicitárias.For more information about the methods related to this object, see Manage delivery lines for ad campaigns.
Perfis de direcionamentoTargeting profiles 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.Every delivery line has one targeting profile that specifies the users, geographies and inventory types that you want to target. Perfis de direcionamento podem ser criados como um modelo e compartilhados entre as linhas de entrega.Targeting profiles can be created as a template and shared across delivery lines.

Para obter mais informações sobre os métodos relacionados a esse objeto, consulte Gerenciar perfis de direcionamento de campanhas publicitárias.For more information about the methods related to this object, see Manage targeting profiles for ad campaigns.
CriativosCreatives 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.Every delivery line has one or more creatives that represent the ads that are shown to customers as part of the campaign. Um criativo pode ser associado a uma ou mais linhas de entrega, mesmo em campanhas publicitárias, considerando sempre representa o mesmo app.A creative may be associated with one or more delivery lines, even across ad campaigns, provided it always represents the same app.

Para obter mais informações sobre os métodos relacionados a esse objeto, consulte Gerenciar criativos de campanhas publicitárias.For more information about the methods related to this object, see Manage creatives for ad campaigns.

O diagrama a seguir ilustra a relação entre campanhas, linhas de entrega, perfis de direcionamento, e criativos.The following diagram illustrates the relationship between campaigns, delivery lines, targeting profiles, and creatives.

Hierarquia de campanha publicitária

Exemplo de códigoCode example

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#.The following code example demonstrates how to obtain an Azure AD access token and call the Microsoft Store promotions API from a C# console app. Para usar este exemplo de código, atribua as variáveis tenantId, clientId, clientSecret e appID aos valores adequados ao seu cenário.To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. Este exemplo exige o pacote Json.NET do Newtonsoft para desserializar os dados JSON retornados pela API de promoções da Microsoft Store.This example requires the Json.NET package from Newtonsoft to deserialize the JSON data returned by the Microsoft Store promotions API.

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;
        }
    }
}