Compartir a través de

Ejecutar campañas publicitarias mediante los servicios de la Tienda

Usa el API de promociones de Microsoft Store para administrar mediante programación campañas publicitarias promocionales para aplicaciones registradas en tu cuenta del Centro de partners de tu organización. Esta API le permite crear, actualizar y supervisar sus campañas y otros recursos relacionados, como el destino y los creativos. Esta API es especialmente útil para los desarrolladores que crean grandes volúmenes de campañas y que quieren hacerlo sin usar el Centro de partners. Esta API usa Azure Active Directory (Azure AD) para autenticar las llamadas desde la aplicación o el servicio.

En los pasos siguientes se describe el proceso de un extremo a otro:

  1. Asegúrate de haber completado todos los requisitos previos .
  2. Antes de llamar a un método en la API de promociones de Microsoft Store, obtenga un token de acceso de Azure AD. Después de obtener un token, tienes 60 minutos para usar este token en llamadas a la API de promociones de Microsoft Store antes de que expire el token. Una vez que expire el token, puede generar un nuevo token.
  3. Llamar a la API de promociones de Microsoft Store.

También puede crear y administrar campañas publicitarias mediante el Centro de partners y cualquier campaña publicitaria que cree mediante programación a través de la API de promociones de Microsoft Store también se puede acceder en el Centro de partners. Para obtener más información sobre cómo administrar campañas publicitarias en el Centro de partners, consulta Crear una campaña publicitaria para tu aplicación.

Nota:

Cualquier desarrollador con una cuenta del Centro de partners puede usar la API de promociones de Microsoft Store para administrar campañas publicitarias para sus aplicaciones. Las agencias de medios también pueden solicitar acceso a esta API para ejecutar campañas publicitarias en nombre de sus anunciantes. Si es una agencia de medios que quiere obtener más información sobre esta API o solicitar acceso a ella, envíe la solicitud a storepromotionsapi@microsoft.com.

Paso 1: Completar los requisitos previos para usar la API de promociones de Microsoft Store

Antes de empezar a escribir código para llamar a la API de promociones de Microsoft Store, asegúrese de que ha completado los siguientes requisitos previos.

  • Para poder crear e iniciar correctamente una campaña publicitaria con esta API, primero debe crear una campaña publicitaria de pago mediante la página campañas de anuncios de Ad en el Centro de partnersy debe agregar al menos un instrumento de pago en esta página. Después de hacerlo, podrá crear correctamente líneas de entrega facturables para campañas publicitarias mediante esta API. Las líneas de entrega de las campañas publicitarias que cree con esta API facturarán automáticamente el instrumento de pago predeterminado elegido en la página de campañas publicitarias en el Centro de Partners.

  • Usted (o su organización) debe tener un directorio de Azure AD y debe tener administrador global permiso para el directorio. Si ya usa Microsoft 365 u otros servicios empresariales de Microsoft, ya tiene el directorio de Azure AD. De lo contrario, puede crear un nuevo Azure AD en el Centro de partners sin cargo adicional.

  • Debe asociar una aplicación de Azure AD a su cuenta del Centro de partners, recuperar el identificador de inquilino y el identificador de cliente de la aplicación y generar una clave. La aplicación de Azure AD representa la aplicación o servicio desde la que quieres llamar a la API de promociones de Microsoft Store. Necesitas el ID de inquilino, el ID de cliente y la clave para obtener un token de acceso de Azure AD que se pasa a la API.

    Nota:

    Solo tiene que realizar esta tarea una vez. Una vez que tenga el identificador de inquilino, el identificador de cliente y la clave, puede reutilizarlos cada vez que necesite crear un nuevo token de acceso de Azure AD.

Para asociar una aplicación de Azure AD a su cuenta del Centro de partners y recuperar los valores necesarios:

  1. En el Centro de Partners, asegúrese de asociar la cuenta del Centro de Partners de su organización con el directorio de Azure AD de su organización.

  2. A continuación, en la página Usuarios de la sección Configuración de la cuenta del Centro de partners, agregue la aplicación de Azure AD que representa la aplicación o el servicio que utilizará para gestionar las campañas de promoción de su cuenta del Centro de partners. Asegúrese de asignar a esta aplicación el rol de Manager. Si la aplicación aún no existe en el directorio de Azure AD, puede crear una nueva aplicación de Azure AD en el Centro de partners.

  3. Vuelva a la página Usuarios, haga clic en el nombre de su aplicación de Azure AD para ir a la configuración de la aplicación, y copie los valores de ID de inquilino y ID de cliente .

  4. Haga clic en Agregar nueva clave. En la pantalla siguiente, copie el valor de la clave . No podrá acceder a esta información de nuevo después de salir de esta página. Para más información, consulte Administración de claves para una aplicación de Azure AD.

Paso 2: Obtención de un token de acceso de Azure AD

Antes de llamar a cualquiera de los métodos de la API de promociones de Microsoft Store, primero debe obtener un token de acceso de Azure AD que pase al encabezado Authorization de cada método de la API. Después de obtener un token de acceso, tiene 60 minutos para usarlo antes de que expire. Una vez que expire el token, puede actualizar el token para poder seguir utilizándolo en llamadas adicionales a la API.

Para obtener el token de acceso, siga las instrucciones de Llamadas de servicio a servicio mediante credenciales de cliente para enviar un POST HTTP al punto de conexión https://login.microsoftonline.com/<tenant_id>/oauth2/token. Esta es una solicitud de ejemplo.

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 el valor de tenant_id en el URI POST y los parámetros client_id y client_secret, especifique el ID de inquilino, el ID de cliente y la clave de la aplicación que recuperó del Centro de Socios en la sección anterior. Para el parámetro del recurso , debe especificar .

Una vez que expire el token de acceso, puede actualizarlo siguiendo las instrucciones aquí.

Paso 3: Llamar a la API de promociones de Microsoft Store

Después de tener un token de acceso de Azure AD, está listo para llamar a la API de promociones de Microsoft Store. Debe pasar el token de acceso al encabezado, Authorization, de cada método.

En el contexto de la API de promociones de Microsoft Store, una campaña publicitaria consta de un objeto de campaña que contiene información de alto nivel sobre la campaña, y de objetos adicionales que representan las líneas de entrega , los perfiles de destino y los elementos creativos para la campaña publicitaria. La API incluye diferentes conjuntos de métodos agrupados por estos tipos de objetos. Normalmente, para crear una campaña, se llama a un método POST diferente para cada uno de estos objetos. La API también proporciona métodos GET que puede usar para recuperar cualquier objeto y métodos PUT que puede usar para editar objetos de campaña, de línea de entrega y de perfil de segmentación.

Para obtener más información sobre estos objetos y sus métodos relacionados, vea la tabla siguiente.

Objeto Descripción
Campañas Este objeto representa la campaña publicitaria y se encuentra en la parte superior de la jerarquía del modelo de objetos para las campañas publicitarias. Este objeto identifica el tipo de campaña que se está ejecutando (pagado, casa o comunidad), el objetivo de campaña, las líneas de entrega de la campaña y otros detalles. Cada campaña solo se puede asociar a una aplicación.

Para obtener más información sobre los métodos relacionados con este objeto, vea Administrar campañas publicitarias.

Nota Después de crear una campaña publicitaria, puede recuperar los datos de rendimiento de la campaña publicitaria mediante el método Obtener datos de rendimiento de campaña publicitaria en la API de análisis de Microsoft Store.
Líneas de entrega Cada campaña tiene una o más líneas de entrega que se usan para comprar inventario y entregar sus anuncios. Para cada línea de entrega, puedes establecer la segmentación, establecer el precio de la oferta y decidir cuánto quieres gastar estableciendo un presupuesto y vinculando a creativos que quieras usar.

Para obtener más información sobre los métodos relacionados con este objeto, vea Administrar líneas de entrega para campañas publicitarias.
Perfiles de segmentación Cada línea de entrega tiene un perfil de destino que especifica los usuarios, las zonas geográficas y los tipos de inventario a los que desea dirigirse. Los perfiles de destino se pueden crear como una plantilla y compartirse entre líneas de entrega.

Para obtener más información sobre los métodos relacionados con este objeto, vea Administrar perfiles de destino para campañas publicitarias.
Creativos Cada línea de entrega tiene uno o más creativos que representan los anuncios que se muestran a los clientes como parte de la campaña. Un creativo puede estar asociado a una o más líneas de entrega, incluso en campañas publicitarias, siempre que represente la misma aplicación.

Para obtener más información sobre los métodos relacionados con este objeto, vea Administrar creativos para campañas publicitarias.

En el diagrama siguiente se muestra la relación entre campañas, líneas de entrega, perfiles de destino y creativos.

Jerarquía de campañas publicitarias

Ejemplo de código

En el ejemplo de código siguiente se muestra cómo obtener un token de acceso de Azure AD y llamar a la API de promociones de Microsoft Store desde una aplicación de consola de C#. Para usar este ejemplo de código, asigne los tenantId, clientId, clientSecrety variables appID a los valores adecuados para su escenario. En este ejemplo se requiere el paquete de Json.NET de Newtonsoft para deserializar los datos JSON devueltos por la API de promociones de 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;
        }
    }
}