Administrar campañas publicitarias

  • Artículo

Usa estos métodos en la API de promociones de Microsoft Store para crear, editar y obtener campañas publicitarias promocionales para tu aplicación. Cada campaña que cree con este método solo se puede asociar a una aplicación.

Nota También puedes crear y administrar campañas publicitarias mediante el Centro de partners y se puede acceder a las campañas que creas mediante programación 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.

Cuando se usan estos métodos para crear o actualizar una campaña, normalmente también se llama a uno o varios de los métodos siguientes para administrar las líneas de entrega, los perfiles de destino y los creativos asociados a la campaña. Para obtener más información sobre la relación entre campañas, líneas de entrega, perfiles de destino y creativos, consulta Ejecutar campañas publicitarias con los servicios de Microsoft Store.

Requisitos previos

Para usar estos métodos, primero debe hacer lo siguiente:

  • Si aún no lo ha hecho, complete todos los requisitos previos para la API de promociones de Microsoft Store.

    Nota Como parte de los requisitos previos, asegúrese de crear al menos una campaña publicitaria de pago en el Centro de partners y que agregue al menos un instrumento de pago para la campaña publicitaria en el Centro de partners. Las líneas de entrega de campañas publicitarias que cree con esta API facturarán automáticamente el instrumento de pago predeterminado elegido en la página Campañas publicitarias del Centro de partners.

  • Obtenga un token de acceso de Azure AD para usarlo en el encabezado de solicitud para estos métodos. Una vez que haya obtenido un token de acceso, tiene 60 minutos para usarlo antes de que expire. Si el token expira, puedes obtener uno nuevo.

Solicitud

Estos métodos tienen los siguientes URI.

Tipo de método URI de solicitud Descripción
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign Crea una nueva campaña publicitaria.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} Edita la campaña publicitaria especificada por campaignId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} Obtiene la campaña publicitaria especificada por campaignId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign Consultas para campañas publicitarias. Consulte la sección Parámetros para conocer los parámetros de consulta admitidos.
Encabezado Tipo Descripción
Authorization string Necesario. Token de acceso de Azure AD con el formato Token de portador<>.
Tracking ID GUID Opcional. Identificador que realiza un seguimiento del flujo de llamadas.

 

Parámetros

El método GET para consultar campañas publicitarias admite los siguientes parámetros de consulta opcionales.

Nombre Tipo Descripción
skip int Número de filas que se omiten en la consulta. Usa este parámetro para consultar conjuntos de datos. Por ejemplo, fetch=10 y skip=0 recupera las primeras 10 filas de datos, top=10 y skip=10 recupera las siguientes 10 filas de datos, etc.
fetch int Número de filas de datos que se devuelven en la solicitud.
campaignSetSortColumn cadena Ordena los objetos Campaign en el cuerpo de la respuesta por el campo especificado. La sintaxis es CampaignSetSortColumn=field, donde el parámetro field puede ser una de las cadenas siguientes:

  • id
  • createdDateTime

El valor predeterminado es createdDateTime.
isDescending Boolean Ordena los objetos Campaign en el cuerpo de la respuesta en orden descendente o ascendente.
storeProductId cadena Usa este valor para devolver solo las campañas publicitarias asociadas a la aplicación con el identificador de la Tienda especificado. Un ejemplo de id. de la Tienda para un producto es 9nblggh42cfd.
etiqueta string Utilice este valor para devolver solo las campañas publicitarias que incluyan la etiqueta especificada en el objeto Campaign .

Cuerpo de la solicitud

Los métodos POST y PUT requieren un cuerpo de solicitud JSON con los campos obligatorios de un objeto Campaign y los campos adicionales que quiera establecer o cambiar.

Ejemplos de solicitud

En el ejemplo siguiente se muestra cómo llamar al método POST para crear una campaña publicitaria.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign",
    "storeProductId": "9nblggh42cfd",
    "configuredStatus": "Active",
    "objective": "DriveInstalls",
    "type": "Community"
}

En el ejemplo siguiente se muestra cómo llamar al método GET para recuperar una campaña publicitaria específica.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/31043481  HTTP/1.1
Authorization: Bearer <your access token>

En el ejemplo siguiente se muestra cómo llamar al método GET para consultar un conjunto de campañas publicitarias, ordenadas por la fecha de creación.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?storeProductId=9nblggh42cfd&fetch=100&skip=0&campaignSetSortColumn=createdDateTime HTTP/1.1
Authorization: Bearer <your access token>

Response

Estos métodos devuelven un cuerpo de respuesta JSON con uno o varios objetos Campaign , en función del método al que llamó. En el ejemplo siguiente se muestra un cuerpo de respuesta para el método GET para una campaña específica.

{
    "Data": {
        "id": 31043481,
        "name": "Contoso App Campaign",
        "createdDate": "2017-01-17T10:12:15Z",
        "storeProductId": "9nblggh42cfd",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "labels": [],
        "objective": "DriveInstalls",
        "type": "Paid",
        "lines": [
            {
                "id": 31043476,
                "name": "Contoso App Campaign - Paid Line"
            }
        ]
    }
}

Objeto de campañas

Los cuerpos de solicitud y respuesta de estos métodos contienen los campos siguientes. En esta tabla se muestran los campos que son de solo lectura (lo que significa que no se pueden cambiar en el método PUT) y qué campos son necesarios en el cuerpo de la solicitud para el método POST.

Campo Tipo Descripción Solo lectura Valor predeterminado Obligatorio para POST
id integer El identificador de la campaña de anuncios. Sí No
name string El nombre de la campaña de anuncios. No Sí
configuredStatus string Uno de los siguientes valores que especifica el estado de la campaña publicitaria especificada por el desarrollador:
  • Activo
  • Inactivo
 No Activo Sí
effectiveStatus cadena Uno de los siguientes valores que especifica el estado efectivo de la campaña publicitaria en función de la validación del sistema:
  • Activo
  • Inactivo
  • Procesamiento
 Sí No
effectiveStatusReasons array Uno o varios de los siguientes valores que especifican el motivo del estado efectivo de la campaña publicitaria:
  • AdCreativesInactive
  • BillingFailed
  • AdLinesInactive
  • ValidationFailed
  • Erróneo
 Sí No
storeProductId string El id. de la Tienda para la aplicación a la que está asociada esta campaña publicitaria. Un ejemplo de id. de la Tienda para un producto es 9nblggh42cfd. Sí Sí
labels array Una o varias cadenas que representan etiquetas personalizadas para la campaña. Estas etiquetas se usan para buscar y etiquetar campañas. No null No
type string Uno de los siguientes valores que especifica el tipo de campaña:
  • De pago
  • Casa
  • Comunidad
 Sí Sí
objetivo cadena Uno de los siguientes valores que especifica el objetivo de la campaña:
  • DriveInstall
  • DriveReengagement
  • DriveInAppPurchase
 No DriveInstall Yes
lines array Uno o varios objetos que identifican las líneas de entrega asociadas a la campaña publicitaria. Cada objeto de este campo consta de un campo id y name que especifica el identificador y el nombre de la línea de entrega. No No
createdDate cadena Fecha y hora en que se creó la campaña publicitaria, en formato ISO 8601. Sí No