Ejecutar campañas publicitarias mediante los servicios de la Tienda
Usa la 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 utiliza Azure Active Directory (Azure AD) para autenticar las llamadas desde la aplicación o el servicio.
Los siguientes pasos describen el proceso de principio a fin:
- Asegúrese de que ha completado todos los requisitos previos.
- 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. Después de que el token expire, puede generar uno nuevo.
- Llame 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 en el Centro de partners y 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 campañas de anuncios del Centro de partners.
Usted (o su organización) tiene que tener un directorio de Azure AD y el permiso de Administrador global para el directorio. Si usa Microsoft 365 u otros servicios empresariales de Microsoft, ya tiene el directorio de Azure AD. De lo contrario, puede crear una nueva instancia de 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. Necesita el identificador de inquilino, el identificador de cliente y la clave para obtener un token de acceso de Azure AD para pasar 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 volver a usarlos cada vez que tenga que 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:
En el Centro de partners, asocie la cuenta del Centro de partners de la organización con el directorio de Azure AD de la organización.
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 usará para administrar las campañas de promoción de la cuenta del Centro de partners. Asegúrese de asignar a esta aplicación el rol Administrador. 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.
Vuelva a la página Usuarios, haga clic en el nombre de la aplicación de Azure AD para ir a la configuración de la aplicación y, a continuación, copie los valores de Identificador de inquilino e Identificador de cliente.
Haga clic en Agregar nueva clave. En la pantalla siguiente, copie el valor de Clave. Después de salir de esta página no podrá tener acceso de nuevo a esta información. Para más información, consulta Administrar claves para una aplicación de Azure AD.
Paso 2: Obtener 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. Una vez que haya obtenido un token de acceso, tiene 60 minutos para usarlo antes de que expire. Una vez que expire el token, puede actualizarlo para poder seguir utilizándolo en llamadas adicionales a la API.
Para obtener el token de acceso, siga las instrucciones de Llamadas entre servicios mediante las credenciales del cliente para enviar una solicitud HTTP POST 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 tenant_id en el URI POST y los parámetros client_id y client_secret, especifique el identificador de inquilino, el identificador de cliente y la clave de la aplicación que recuperó del Centro de partners en la sección anterior. Para el parámetro resource, tiene que especificar https://manage.devcenter.microsoft.com.
Una vez que expire el token de acceso, puede actualizarlo siguiendo las instrucciones que se indican 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 objetos adicionales que representan las líneas de entrega, perfiles de destino y creativos para la campaña publicitaria. La API incluye diferentes conjuntos de métodos agrupados por estos tipos de objetos. Para crear una campaña, normalmente 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étodo PUT que puede usar para editar los objetos de perfil de campaña, línea de entrega y destino.
Para obtener más información sobre estos objetos y sus métodos relacionados, vea la tabla siguiente.
| Object | 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, puedes recuperar los datos de rendimiento de la campaña 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 destino | 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.
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 las variables tenantId, clientId, clientSecret y 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;
}
}
}
Temas relacionados
- Administrar campañas publicitarias
- Administrar líneas de entrega para campañas publicitarias
- Administrar perfiles de destino para campañas publicitarias
- Administrar creativos para campañas publicitarias
- Obtén datos sobre el rendimiento de las campañas publicitarias