Compartir a través de

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úrate de crear al menos una campaña publicitaria de pago en el Centro de partners y de agregar al menos un instrumento de pago para la campaña publicitaria en el Centro de partners. 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.

  • Obtenga un token de acceso a Azure AD para utilizarlo en el encabezado de solicitud de estos métodos. 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 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 ver los parámetros de consulta admitidos.
Encabezado Tipo Descripción
Autorización 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 Escribir Descripción
skip int Número de filas que se omiten en la consulta. Use este parámetro para paginar a través de 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 van a devolver en la solicitud.
campaignSetSortColumn string 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 siguientes cadenas:

  • id
  • createdDateTime

El valor predeterminado es createdDateTime.
isDescending Booleano Ordena los objetos Campaign en el cuerpo de la respuesta en orden descendente o ascendente.
storeProductId string 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.
label string Utilice este valor para devolver solo las campañas publicitarias que incluyen 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 desee 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>

Respuesta

Estos métodos devuelven un cuerpo de respuesta JSON con uno o varios objetos Campaign , según el 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"
            }
        ]
    }
}

Campaign (objeto)

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 Description Solo lectura Valor predeterminado Obligatorio para POST
identificador integer Identificador de la campaña publicitaria. Sí No
name string Nombre de la campaña publicitaria. No Sí
configuredStatus string Uno de los siguientes valores que especifica el estado de la campaña publicitaria especificada por el desarrollador:
  • Activas
  • Inactivo
 No Activo Sí
effectiveStatus string Uno de los siguientes valores que especifica el estado efectivo de la campaña publicitaria en función de la validación del sistema:
  • Activas
  • Inactivo
  • Procesando
 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
  • Con error
 Sí No
storeProductId string El identificador de la Tienda de 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í
etiquetas 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 cadena Uno de los siguientes valores que especifica el tipo de campaña:
  • Pagada
  • Casa
  • Community
 Sí Sí
objetivo string Uno de los siguientes valores que especifica el objetivo de la campaña:
  • DriveInstall
  • DriveReengagement
  • DriveInAppPurchase
 No DriveInstall Sí
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 string Fecha y hora en que se creó la campaña publicitaria, en formato ISO 8601. Sí No