Microsoft Monetize ad server para la oferta garantizada mediante programación

La configuración de una implementación de API para una oferta de programación garantizada (PG) a través de Microsoft Monetize Ad Server requiere configurar una serie de propiedades diferentes en diferentes objetos de API. Esta guía explicará el proceso de creación y configuración de una oferta de PG utilizando nuestra API.

Información general

Las ofertas PG son una característica poderosa que permite a los clientes de redes y editores brindar un mejor soporte a sus compradores al proporcionar herramientas de compra preempaquetadas y fáciles de usar para ofertas de precio fijo.

La configuración de una oferta de PG implica realizar solicitudes a los siguientes puntos finales de servicio de API para acceder o crear los objetos de API correspondientes:

Esta guía usa ejemplos de cURL para todas las solicitudes. Puede usar otras herramientas de solicitud de API (por ejemplo, Postman), pero luego tendrá que ajustar los ejemplos en consecuencia.

Requisitos previos

Antes de comenzar esta configuración, asegúrese de leer la API de Introducción. Proporciona información sobre entornos de prueba, restricciones de uso, semántica de API (ejecución de comandos, filtrado, ordenación, etc.) y prácticas recomendadas.

Orden de las operaciones

Los objetos API a menudo tienen dependencias sobre otros objetos API y hay un orden que debe seguir al crear o acceder a objetos cuando crea una oferta PG. Por ejemplo, debe proporcionar los identificadores de los siguientes objetos de API: advertiser, insertion-order, dealy profile. Para obtener los identificadores de estos objetos, deberá crearlos o ya tener acceso a ellos. Los pasos de esta guía siguen el orden típico de operaciones necesarias para crear una oferta de PG.

Procedimientos recomendados

Para obtener una lista general de las mejores prácticas a seguir al trabajar con la API, consulte Mejores prácticas de API. Las siguientes son algunas de las mejores prácticas específicas de la configuración de una línea de pedido de trato:

• Establezca el state campo de la línea de pedido del negocio hasta que "inactive" la línea de pedido esté completamente configurada y lista para la prueba.
• Anote el identificador de los objetos que cree. Los identificadores de los objetos que cree se devuelven en el cuerpo de respuesta de las solicitudes. A menudo, necesitará estos identificadores más adelante, por lo que copiarlos cuando se devuelvan puede reducir el número de solicitudes adicionales GET que tiene que realizar para obtenerlos.

Procedimiento de instalación

Los siguientes pasos lo guiarán a través del proceso de configuración de una línea de negocio con configuraciones típicas:

• Paso 1: Obtener un token de autorización
• Paso 2: Crear un anunciante o acceder a él
• Paso 3: Crear una orden de inserción o acceder a ella para PG
• Paso 4: Crear una oferta de PG
• Paso 5: Crear un perfil de línea de pedido de oferta PG
• Paso 6: Crear una línea de pedido de oferta PG

Paso 1: Obtener un token de autorización

En primer lugar, deberá obtener un token de autorización. A continuación, debe incluir este token de autorización en todas las solicitudes posteriores. Para obtener más información, consulte Servicio de autenticación. Para obtener un token de autorización, haga lo siguiente:

1. Cree un archivo JSON que contenga su nombre de usuario y contraseña.

   {
       "auth": {
           "username" : "USERNAME",
           "password" : "PASSWORD"
       }
   }
   

2. Realice una POST solicitud al /auth punto de conexión con este archivo JSON en el cuerpo de la solicitud. Para obtener más información, consulte Servicio de autenticación. En la solicitud cURL siguiente, el token de autorización devuelto se almacena en el archivo "cookies".

   curl -c cookies -X POST -d @authentication.json 'https://api.appnexus.com/auth'
   

3. Compruebe el cuerpo de respuesta de la solicitud (consulte Ejemplo de respuesta a continuación). Si la solicitud se realizó correctamente, obtendrá un "status" de "OK" y el campo "token" se rellenará con el valor del token de autenticación.
   Ejemplo de respuesta

   {
      "response" : {
         "token" : "authn:225692:2d787d1838283:lax1",
         "status" : "OK"      
      }
   }
   

Paso 2: Crear un anunciante o acceder a él

Tendrá que crear o acceder a un anunciante desde el que crear una línea de pedido de trato. Para las líneas de pedido de ofertas, los anunciantes se configuran de la misma manera que las líneas de pedido aumentadas.

Si aún no tienes un anunciante que usar, crea un anunciante mediante los siguientes pasos (para obtener más información, consulta Servicio de anunciantes):

1. Crear un JSON de anunciante:

   $ cat advertiser.json
   {
       "advertiser": {
           "name": "Deal Line Item Example Advertiser",
           "timezone": "US/Pacific"
       }
   }
   

2. Realice una POST solicitud al https://api.appnexus.com/advertiser punto de conexión con este JSON de anunciante y un member_idarchivo .

   curl -b cookies -c cookies -X POST -d @advertiser.json 'https://api.appnexus.com/advertiser?member_id=2378'
   

3. Compruebe el cuerpo de respuesta de la solicitud. Si la solicitud se realizó correctamente, obtendrá un "status" de "OK" y verá las actualizaciones realizadas.

4. Anota el id. del anunciante en el cuerpo de la respuesta para que puedas usarlo al crear la línea de negocio en el paso 6: Crear una línea de negocio de oferta.

Campos JSON para anunciantes (campos opcionales obligatorios y útiles)

Paso 3: Crear una orden de inserción de PG o acceder a ella

Tendrás que crear una orden de inserción o acceder a ella para crear una oferta de PG. Las líneas de negocio requieren una orden de inserción fluida (consulta los campos obligatorios a continuación).

Si aún no tienes una orden de inserción para usar, crea una orden de inserción mediante los siguientes pasos (para obtener más información, consulta Servicio de órdenes de inserción):

1. Crear un JSON de la orden de inserción (a continuación se muestran dos ejemplos):

   Ejemplo de JSON: Sin fecha de finalización, presupuesto ilimitado

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "PG Deal Example IO",
                   "state": "active",
           "budget_intervals": [{
               "start_date": "2022-10-10 00:00:00",
               "end_date": null,
               "daily_budget": null,
               "daily_budget_imps": null,
               "enable_pacing": true,
               "lifetime_budget": null,
               "lifetime_budget_imps": null
           }],
           "budget_type": "impression"
       }
   }
   

2. Realice una POST solicitud al https://api.appnexus.com/insertion-order punto de conexión con este JSON de orden de inserción y un advertiser_id archivo y member_id.

   Solicitud de ejemplo: Sin fecha de finalización, presupuesto ilimitado

   curl -b cookies -c cookies -X POST -d @insertion-order-noenddate.json 'https://api.appnexus.com/insertion-order?advertiser_id=2605036&member_id=2378'
   

3. Compruebe el cuerpo de respuesta de la solicitud. Si la solicitud se realizó correctamente, obtendrá un "status" de "OK" y verá las actualizaciones realizadas.

4. Anota el ID de la orden de inserción en el cuerpo de la respuesta para que puedas usarlo al crear la línea de pedido de PG en el paso 6: Crear una línea de línea de trato.

Campos JSON para un orden de inserción sin interrupciones (campos opcionales obligatorios y útiles)

Paso 4: Crear una oferta de PG

Tendrás que crear la oferta que quieras asociar con la línea de pedido de oferta de PG.

Para crear una oferta, haga lo siguiente (para obtener más información, consulte Servicio de ofertas):

1. Crear una oferta JSON:

   $ cat deal.json
   {
       "deal": {
           "name": "Deal Line Item Example Deal",
           "buyer": {
               "id": 2379
           },
           "version": 2
       }
   }
   

2. Realice una POST solicitud al https://api.appnexus.com/deal punto de conexión con este JSON de oferta y un member_idarchivo .

   curl -b cookies -c cookies -X POST -d @deal.json 'https://api.appnexus.com/deal?member_id=2378'
   

3. Compruebe el cuerpo de respuesta de la solicitud. Si la solicitud se realizó correctamente, obtendrá un "status" de "OK" y verá las actualizaciones realizadas.

4. Anota el ID del trato en el cuerpo de la respuesta para que puedas usarlo cuando crees el elemento de línea de negocio en el Paso 6: Crear un elemento de línea de trato.

Campos JSON para oferta

Campos JSON opcionales útiles

Campos JSON para creatividades permitidas

Marca (consulte Servicio de marca)

Ejemplo de marca

"brand_restrict": true,
            "brands": [
                {
                    "id": 2,
                    "name": "1800Flowers",
                    "override": true
                },
                {
                    "id": 4,
                    "name": "Acura",
                    "override": false
                }
            ] 

Idioma (consulte Servicio lingüístico)

Ejemplo de lenguaje

"language_restrict": true,
            "languages": [
                {
                    "id": 1,
                    "name": "English",
                    "override": false
                },
                {
                    "id": 2,
                    "name": "Chinese",
                    "override": true
                }
            ]

Nivel de confianza

Ejemplo de nivel de confianza

"audit_status_option": "max_trust" 

Categoría creativa

Ejemplo de categoría creativa

"categories": [
                 {
                     "id": 1,
                     "name": "Airlines",
                     "override": false
                 },
                 {
                     "id": 2,
                     "name": "Apparel",
                     "override": true
                 }
             ],
             "category_restrict": true

Recursos creativos específicos

Ejemplo de creatividades específicas

"creatives": [
                {
                    "id": 161501729,
                    "status": "banned"
                },
                {
                    "id": 161501882,
                    "status": "approved"
                }
            ]

Tipo de medio (consulte Servicio de subtipo de medios y Servicio de tipo de medios)

Ejemplo de tipo de medio

"allowed_media_subtypes": [
                 {
                     "id": 2,
                     "last_modified": "2015-09-17 19:19:21",
                     "media_type": {
                         "id": 2,
                         "media_type_group_id": 2,
                         "name": "Pop",
                         "uses_sizes": "sometimes"
                     },
                     "name": "Popup",
                     "native_assets": null,
                     "permitted_sizes": null
                 }
             ],
 "allowed_media_types": [
                 {
                     "id": 1,
                     "last_modified": "2012-03-16 21:36:10",
                     "media_type_group_id": 1,
                     "name": "Banner",
                     "uses_sizes": "always"
                 },
                 {
                     "id": 4,
                     "last_modified": "2016-08-22 16:23:12",
                     "media_type_group_id": 1,
                     "name": "Video",
                     "uses_sizes": "never"
                 }
             ]

Atributos técnicos (consulte Servicio de atributos técnicos)

Ejemplo de atributos técnicos

"technical_attribute_restrict": false,
             "technical_attributes": [
                 {
                     "id": 1,
                     "name": "Image",
                     "override": true
                 }
             ]

Campos JSON para la protección de datos de ofertas (consulte Servicio de perfiles de visibilidad)

Id. de usuario e id. de dispositivo

Ejemplo de Proteger el Id. de usuario y el Id. de dispositivo

Paso 1: Crear un perfil de visibilidad

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_device_id_default": false,
        "expose_user_id_default": false,
        "name": "Deal Visibility Profile"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Paso 2: Asocie el perfil de visibilidad a la oferta y habilite la protección de datos

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

Dirección IP

Ejemplo de dirección IP protegida

Paso 1: Crear un perfil de visibilidad

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_ip_default": false,
        "ip_exposure_default": "truncated",
        "name": "Deal Visibility Profile - Hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Paso 2: Asocie el perfil de visibilidad a la oferta y habilite la protección de datos

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

URL

Ejemplo de protección de dominio

Paso 1: Crear un perfil de visibilidad

> cat visibility_profile.json
{
    "visibility-profile": {
        "name": "Deal Visibility Profile - Hidden",
        "url_exposure_default": "hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Paso 2: Asocie el perfil de visibilidad a la oferta y habilite la protección de datos

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

Agregar al segmento (ver Servicio de ofertas)

Impedir que se agregue a un segmento al hacer clic o ver ejemplo

> cat add_segment.json
{
    "deal": {
        "allow_creative_add_on_click": false,
        "allow_creative_add_on_view": false
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @add_segment.json 'https://api.appnexus.com/deal?id=123456'

Paso 5: Crear un perfil de línea de negocio

A continuación, cree un perfil de línea de negocio para utilizarlo en la segmentación con la línea de negocio negocio. Asegúrese de anotar el identificador de este perfil para usarlo más adelante. Para obtener más información, consulte Servicio de perfiles.

Para crear un perfil de línea de pedido de oferta PG, haga lo siguiente (para obtener más información, consulte Servicio de perfiles):

1. Crear un perfil de línea de pedido de oferta de PG JSON:

   Ejemplo: Creación de perfiles con países o regiones, límites de frecuencia/actualidad y umbrales de tasa de visualización/tasa de finalización

   $ cat profile.json
   
   {
       "profile": {
           "country_action": "include",
           "country_targets": [{
               "active": true,
               "code": "US",
               "id": 233,
               "name": "United States"
           }],
           "engagement_rate_targets": [{
                   "engagement_rate_pct": 25,
                   "engagement_rate_type": "video_completion"
               },
               {
                   "engagement_rate_pct": 50,
                   "engagement_rate_type": "predicted_iab_video_view_rate"
               }
           ],
           "max_day_imps": 10,
           "min_minutes_per_imp": 300
       }
   }
   

   Ejemplo: Creación de perfiles sin segmentación

   > cat profile.json
   
   {
       "profile": {
       }
   }
   

2. Realice una POST solicitud al https://api.appnexus.com/profile punto de conexión con este perfil de oferta JSON y un archivo .SRT adecuado advertiser_id

   Ejemplo: Creación de perfiles con países o regiones, límites de frecuencia/actualidad y umbrales de tasa de visualización/tasa de finalización

   > curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
   

   Ejemplo: Creación de perfiles sin segmentación

   > curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
   

3. Compruebe el cuerpo de respuesta de la solicitud. Si la solicitud se realizó correctamente, obtendrá un "status" de "OK" y verá las actualizaciones realizadas.

4. Anota el ID del perfil en el cuerpo de la respuesta para que puedas usarlo cuando crees la línea de pedido de PG en el Paso 6: Crear una línea de línea de oferta de PG.

Campos JSON opcionales para el perfil de la línea de pedido de la oferta

Hay muchos campos opcionales disponibles en el perfil de la línea de pedido del trato para segmentar con la línea de pedido del trato. Por ejemplo, puedes dirigirte a propiedades asociadas con el inventario, tipos de inventario, listas de permitidos, listas de bloqueados, tipos de dispositivos, etc. Para obtener más información sobre los campos disponibles, consulte el Servicio de perfiles.

Paso 6: Crear una línea de pedido de oferta de PG

Por último, tendrás que crear la línea de negocio para asociar el ID del negocio y el perfil de línea de negocio que creaste en el Paso 5: Crear un perfil de línea de línea de negocio PG.

Para crear una línea de pedido de oferta PG, haga lo siguiente (para obtener más información, consulte Servicio de línea de pedido):

1. Crea un JSON de una línea de pedido de negocio (necesitarás un identificador de anunciante existente, un identificador de orden de inserción, un identificador de oferta y un identificador de perfil).

   Ejemplo de JSON: Línea de pedido de oferta PG sin presupuesto

   > cat deal_line_item.json
   {
       "line-item": {
           "ad_types": ["banner"],
           "auction_event": {
               "kpi_auction_type_id": 1,
               "payment_auction_type_id": 1,
               "revenue_auction_type_id": 1
           },
           "bid_object_type": "deal",
           "budget_intervals": [{
               "start_date": "2022-08-11 12:00:00"
           }],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "cpm",
           "revenue_value": "5",
           "supply_strategies": {
               "managed": true,
                           "rtb": false,
                           "programmatic_guaranteed": false
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": null
           }
       }
   }
   

   Ejemplo JSON: Objeto gráfico de impresión de por vida de la línea de negocio de PG

   > cat deal_line_item_lifetime.json
   {
       "line-item": {
           "ad_types": ["banner"],
           "auction_event": {
               "kpi_auction_type_id": 1,
               "payment_auction_type_id": 1,
               "revenue_auction_type_id": 1
           },
           "bid_object_type": "deal",
           "budget_intervals": [
                   {
                       "end_date": "2022-10-18 23:59:59",
                       "lifetime_budget_imps": 2586,
                       "start_date": "2022-10-11 12:00:00",
                       "timezone": "US/Pacific"
                   }
               ],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "cpm",
           "revenue_value": "5",
           "supply_strategies": {
               "managed": true,
                           "rtb": false,
                           "programmatic_guaranteed": false
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": null
           }
       }
   }
   

2. Realice una POST solicitud al https://api.appnexus.com/line-item punto de conexión mediante este elemento de línea de negocio JSON y un advertiser_id archivo y .member_id

   Solicitud de ejemplo: Partida de oferta sin presupuesto

   > curl -b cookies -c cookies -X POST -d @deal_line_item.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

   Solicitud de ejemplo: Presupuesto de impresiones de por vida de la línea de pedido de oferta

   > curl -b cookies -c cookies -X POST -d @deal_line_item_lifetime.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

   Ejemplo de solicitud: Partida de negocio presupuesto de ingresos diarios

   > curl -b cookies -c cookies -X POST -d @deal_line_item_daily.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

3. Compruebe el cuerpo de respuesta de la solicitud. Si la solicitud se realizó correctamente, obtendrá un "status" de "OK" y verá las actualizaciones realizadas.

4. Anote el ID de la línea de pedido en el cuerpo de la respuesta para que pueda identificar esta línea de negocio más tarde para cambiar su state (active o inactive) o modificarla.

Campos JSON para el objeto de línea de negocio

budget_intervals ejemplo

"budget_intervals": [
{
"id": 18770835,
"object_id": 18601984,
"object_type": "campaign_group",
"start_date": "2022-08-08 00:00:00",
"end_date": "2022-08-17 23:59:59",
"timezone": "Europe/Paris",
"code": null,
"parent_interval_id": null,
"creatives": null,
"subflights": null,
"lifetime_budget": null,
"lifetime_budget_imps": 100,
"lifetime_pacing": false,
"enable_pacing": true,
"daily_budget_imps": null,
"lifetime_pacing_pct": 105,
"daily_budget": null,
"daily_budget_imps_opt": null,
"daily_budget_opt": null,
"underspend_rollover_state": false
}
]

auction_event ejemplo

"auction_event": {
"payment_auction_event_type_code": "impression",
"payment_auction_event_type": "impression",
"payment_auction_type_id": 1,
"revenue_auction_event_type_code": "impression",
"revenue_auction_event_type": "impression",
"revenue_auction_type_id": 1,
"kpi_auction_event_type_code": "impression",
"kpi_auction_event_type": "impression",
"kpi_auction_type_id": 1,
"kpi_value_type": null,
"kpi_value": null
}

Útiles campos JSON opcionales para la línea de pedido de oferta

Temas relacionados

• API de Introducción
• Procedimientos recomendados de API
• Semántica de API
• Servicio de oferta
• Servicio de línea de pedido (ALI)
• Servicio de perfiles