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

Use a API de promoções da Microsoft Store para gerir programaticamente campanhas publicitárias promocionais para aplicações registadas na sua conta ou na conta da sua organização no Partner Center. Essa API permite que você crie, atualize e monitore suas campanhas e outros ativos relacionados, como segmentação 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 Azure Ative Directory (Azure AD) para autenticar as chamadas do seu aplicativo ou serviço.

As etapas a seguir descrevem o processo de ponta a ponta:

1. Certifique-se de ter preenchido 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ê tem 60 minutos para usá-lo em chamadas para a API de promoções da Microsoft Store antes que o token expire. Depois que o token expirar, você poderá gerar um novo token.
3. Ligue para 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.

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

Antes de começar a escrever código para chamar a API de promoções da Microsoft Store, certifique-se de ter concluído os seguintes pré-requisitos.

• Antes de poder criar e iniciar com êxito uma campanha publicitária utilizando esta API, deve primeiro criar uma campanha publicitária paga usando a página Campanhas Publicitárias no Partner Centere adicionar nesta página pelo menos um instrumento de pagamento. Depois de fazer isso, você poderá criar com êxito linhas de entrega faturáveis para campanhas publicitárias usando essa API. As linhas de entrega para as campanhas publicitárias que criar utilizando esta API cobrarão automaticamente o instrumento de pagamento padrão escolhido na página de campanhas publicitárias no Partner Center.

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

• 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. O aplicativo Azure AD representa o aplicativo ou serviço do qual você deseja 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 você passa para a API.

  Observação

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

Para associar um aplicativo do 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 secção Definições da Conta do Partner Center, adicione a aplicação Azure AD que representa a app ou serviço que utilizará para gerir campanhas promocionais para a sua conta no Partner Center. Certifique-se de atribuir a função Manager a este aplicativo. Se o aplicativo ainda não existir no diretório do Azure AD, você poderá criar um novo aplicativo do Azure AD no Partner Center.

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

4. Clique Adicionar nova chave. No ecrã seguinte, anote o valor da chave . Você não poderá acessar essas informações novamente depois de sair desta página. Para obter mais informações, consulte Gerenciar chaves para um aplicativo do Azure AD.

Etapa 2: Obter um token de acesso do Azure AD

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

Para obter o token de acesso, siga as instruções em Service to Service Calls Using Client Credentials para enviar um HTTP POST para o endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Aqui está um pedido de amostra.

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 o ID do locatário, o ID do cliente e a chave do aplicativo que você recuperou do Partner Center na seção anterior. Para o parâmetro de recurso , deve-se especificar https://manage.devcenter.microsoft.com.

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

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

Depois de ter 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 Authorization de cada método.

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

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

O diagrama a seguir ilustra a relação entre campanhas, linhas de entrega, perfis de segmentação 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, clientSecrete appID aos valores apropriados para o seu cenário. Este exemplo requer o pacote Json.NET da Newtonsoft de 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 para campanhas publicitárias
• Gerenciar perfis de segmentação para campanhas publicitárias
• Gerenciar criativos para campanhas publicitárias
• Obter dados de desempenho da campanha publicitária