Compartir a través de

Guía de configuración de la API de artículo de línea de oferta curada

  • Artículo

La configuración de una implementación de API de un elemento de línea de oferta curada para dirigirse a una oferta requiere configurar una serie de propiedades diferentes en diferentes objetos de API. En esta guía se explica el proceso de creación y configuración de un elemento de línea de oferta seleccionado mediante nuestra API.

Información general

Los acuerdos mantenidos representan un acuerdo negociado entre un comprador y un conservador que combina los activos propietarios de un conservador con el suministro de Xandr Marketplace. Estos recursos propietarios pueden incluir datos de audiencia, acceso de inventario preferido, tarifas especialmente negociadas, talento de optimización, estrategia de inversión y otras características que mejoran la oferta de oferta y crean una oferta única. Los conservadores de ofertas tienen su propio puesto de miembro en la Plataforma Xandr, que usan para empaquetar el suministro y sus propios activos en identificadores de acuerdos seleccionados para los compradores. Cualquier DSP integrado en el intercambio Xandr puede comprar ofertas seleccionadas.

La configuración de un elemento de línea de oferta curada suele implicar la realización de solicitudes a los siguientes puntos de conexión de servicio de API para acceder a los objetos de API correspondientes o crear ellos:

Punto de conexión de API Api (objeto) Referencia detallada
https://api.appnexus.com/advertiser anunciante Servicio de anunciantes
https://api.appnexus.com/insertion-order orden de inserción Servicio de pedido de inserción
https://api.appnexus.com/deal trato Deal Service
https://api.appnexus.com/profile perfil Servicio de perfil
https://api.appnexus.com/line-item elemento de línea (ALI) Elemento de línea: servicio ALI

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

Requisitos previos

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

Orden de las operaciones

Los objetos de API suelen tener dependencias en otros objetos de API y hay un orden que debe seguir al crear o acceder a objetos al crear un elemento de línea de oferta seleccionado. 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 las operaciones necesarias para crear un elemento de línea de oferta seleccionado.

Procedimientos recomendados

Para obtener una lista general de los procedimientos recomendados que se deben seguir al trabajar con la API, consulte Procedimientos recomendados de API. A continuación se muestran algunos procedimientos recomendados que son específicos de una configuración de línea de oferta seleccionada:

  • Establezca el state campo del elemento de línea de oferta seleccionado en hasta que "inactive" el elemento de línea esté totalmente configurado y listo para las pruebas.
  • Tenga en cuenta el identificador de los objetos que cree. Los identificadores de objetos creados 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 pasos siguientes le guiarán a través del proceso de configuración de un elemento de línea de oferta seleccionado con configuraciones típicas:

Paso 1: Obtención de un token de autorización

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

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

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

  2. Realice una POST solicitud al punto de /auth conexión con este archivo JSON en el cuerpo de la solicitud (consulte Servicio de autenticación para obtener más informació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 la 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: Creación o acceso a un anunciante

Tendrá que crear o acceder a un anunciante desde el que crear un artículo de línea de oferta seleccionado. Ha configurado anunciantes para artículos de línea de oferta seleccionados de la misma manera que lo haría para los artículos de línea aumentadas.

Si aún no tiene un anunciante que usar, cree un anunciante haciendo lo siguiente (consulte Servicio de anunciantes para obtener más información):

  1. Cree un JSON de anunciante:

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

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

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

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

  4. Anote el id. del anunciante en el cuerpo de la respuesta para que pueda usarlo al crear el elemento de línea de oferta seleccionado en Paso 6: Crear un elemento de línea de oferta seleccionado.

Campos JSON para anunciante (campos opcionales necesarios y útiles)

Campo Tipo Obligatorio u opcional Descripción
name string Obligatorio Nombre del anunciante
timezone enumeración Opcional La zona horaria del anunciante. Consulte Zonas horarias de API para obtener más información y valores aceptados.
use_insertion_orders booleano Obligatorio Este campo debe establecerse true en para crear elementos de línea de oferta seleccionados.

Paso 3: Creación o acceso a un pedido de inserción

Tendrá que crear o acceder a un pedido de inserción para crear un elemento de línea de oferta seleccionado. Los elementos de línea de oferta seleccionados requieren un orden de inserción sin problemas (vea los campos obligatorios a continuación).

Si aún no tiene un orden de inserción que usar, cree un pedido de inserción haciendo lo siguiente (consulte Servicio de pedidos de inserción para obtener más información):

  1. Cree un json de orden de inserción:

    JSON de ejemplo: sin fecha de finalización, sin presupuesto

    $ cat insertion-order-noenddate.json
{
    "insertion-order": {
        "name": "Curated Deal Line Item Example IO",
        "budget_intervals": [{
            "start_date": "2019-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,
            "lifetime_pacing": false
        }],
        "budget_type": "impression"
    }
}

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

    Solicitud de ejemplo: sin fecha de finalización, sin presupuesto

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

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

  4. Anote el identificador del pedido de inserción en el cuerpo de la respuesta para que pueda usarlo al crear el elemento de línea de oferta seleccionado en paso 6: creación de un elemento de línea de oferta seleccionado.

Campos JSON para el orden de inserción sin problemas

Campo Tipo Obligatorio u opcional Descripción
budget_intervals matriz de objetos Obligatorio Para que un orden de inserción creado a través de la API sea sin problemas, debe usar el budget_intervals campo .
name string Obligatorio Nombre del anunciante

Paso 4: Crear una oferta

Tendrá que crear la oferta que desea asociar con el elemento de línea de oferta seleccionado.

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

  1. Creación de un JSON de oferta:

    $ cat deal.json
{
    "deal": {
        "name": "Curated Deal",
        "buyer": {
            "id": 2379
        },
        "type": {
            "id": 5,
            "name": "Curated"
        },
        "version": 2
    }
}

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

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

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

  4. Anote el identificador de la oferta en el cuerpo de la respuesta para que pueda usarlo al crear el elemento de línea de la oferta en paso 6: Creación de un elemento de línea de oferta seleccionado.

Campos JSON para la oferta

Campo Tipo Obligatorio u opcional Descripción
auction_type objeto Opcional El tipo de subasta de la oferta (Estándar/Fijo/Mercado). Este valor debe coincidir con lo establecido en el elemento de línea de oferta seleccionado (a través de revenue_typerevenue_value/min_revenue_value/).
buyer string Obligatorio El identificador de miembro comprador de la oferta. Este campo no se puede cambiar después de la creación.
name string Obligatorio Nombre de la oferta.
Nota: El comprador verá este nombre.
type objeto Obligatorio Tipo de oferta. Este campo debe establecerse en "5" para las ofertas seleccionadas.
version Entero Obligatorio Este campo debe establecerse "2" en para asociar la oferta a un elemento de línea de oferta seleccionado.

Campos JSON opcionales útiles

Campos JSON para las creatividades permitidas
Marca (consulte Servicio de marca)
Campo Tipo Descripción
brand_restrict booleano - True: la oferta solo está restringida a las marcas enumeradas
- False: se permite que otras marcas sirvan
brands matriz de objetos Matriz de marcas aptas
id Entero Campo dentro de brands: identificador de la marca que es apta para la oferta
name string Campo dentro de brands: nombre de la marca que es apta para la oferta
override booleano Campo dentro de brands: establézcalo true en para permitir que una marca específica sirva para una oferta, incluso si el perfil de calidad del anuncio lo hubiera bloqueado.

Ejemplo de marca

"brand_restrict": true,
            "brands": [
                {
                    "id": 2,
                    "name": "1800Flowers",
                    "override": true
                },
                {
                    "id": 4,
                    "name": "Acura",
                    "override": false
                }
            ]
Tipo de medio (consulte Servicio de subtipos multimedia y Servicio de tipos de medios)
Campo Tipo Descripción
allowed_media_subtypes matriz de objetos Subtipos multimedia permitidos para la oferta.
id Entero Campo dentro de allowed_media_subtypes: el identificador del subtipo multimedia permitido para la oferta
allowed_media_types matriz de objetos Los tipos de medios permitidos para la oferta
id Entero Campo dentro de allowed_media_types: el identificador del tipo de medio permitido para la oferta

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"
                 }
             ]

Paso 5: Creación de un perfil de línea de negocio seleccionado

A continuación, cree un perfil de elemento de línea de oferta seleccionado para usarlo en la selección con el elemento de línea de oferta seleccionado. Asegúrese de anotar el identificador de este perfil para su uso posterior. Consulte Servicio de perfiles para obtener más información.

Nota:

Puede dirigirse a publicadores, ubicaciones y categorías de vendedores con un elemento de línea de oferta seleccionado mediante las siguientes matrices:

  • platform_publisher_targets
  • platform_placement_targets
  • platform_content_category_targets.

No se puede usar placement_targets, publisher_targetsni content_category_targets con un elemento de línea de oferta seleccionado. Consulte Servicio de perfiles para obtener más información.

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

  1. Cree un json de perfil de elemento de línea de oferta seleccionado:

    Ejemplo: Creación de perfiles con umbrales de tasa de finalización de velocidad de país y visualizació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"
                        }
                ],
                "platform_publisher_targets": [{
                        "action": "include",
                        "deleted": false,
                        "id": 1238721,
                        "name": "test_publisher"
                }],
                "platform_placement_targets": [{
                                "action": "include",
                                "deleted": false,
                                "id": 5126395
                        },
                        {
                                "action": "include",
                                "deleted": false,
                                "id": 5301719
                        }
                ],
                "platform_content_category_targets": [{
                        "action": "include",
                        "deleted": false,
                        "id": 19062,
                        "is_system": false,
                        "name": "1"
                }]
        }
}

    Ejemplo: Creación de perfiles sin segmentación

    > cat profile.json

{
    "profile": {
    }
}

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

    Ejemplo: Creación de perfiles con umbrales de tasa de finalización de velocidad de país y visualizació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 la respuesta de la solicitud. Si la solicitud se realizó correctamente, obtendrá un "status" de "OK" y verá las actualizaciones que realizó.

  4. Tenga en cuenta el identificador de perfil en el cuerpo de la respuesta para que pueda usarlo al crear el elemento de línea de oferta seleccionado en Paso 6: Crear un elemento de línea de oferta seleccionado.

Campos JSON opcionales para el perfil de elemento de línea de oferta

Hay muchos campos opcionales disponibles en el perfil de artículos de línea de oferta seleccionados para establecer como destino el elemento de línea de oferta seleccionado. Por ejemplo, puede dirigirse a propiedades asociadas con inventario, tipos de inventario, listas de permitidos, listas de bloqueos, tipos de dispositivos, etc. Consulte Profile Service para obtener más información sobre los campos disponibles.

Paso 6: Creación de un elemento de línea de oferta seleccionado

Por último, tendrá que crear el elemento de línea de oferta seleccionado para asociar el identificador de la oferta y el perfil de artículo de línea de oferta seleccionado que creó en Paso 5: Crear un perfil de línea de oferta seleccionado.

Para crear un elemento de línea de oferta seleccionado, haga lo siguiente (consulte Servicio de artículos de línea para obtener más información):

  1. Cree un elemento de línea de oferta seleccionado JSON (necesitará un identificador de anunciante, un identificador de pedido de inserción, un identificador de transacción y un identificador de perfil).

    JSON de ejemplo: elemento de línea de oferta curada sin presupuesto

    > cat curated_deal_line_item.json
{
        "line-item": {
                "ad_types": ["video"],
                "auction_event": {
                        "kpi_auction_type_id": 1,
                        "payment_auction_type_id": 1,
                        "revenue_auction_type_id": 1
                },
                "budget_intervals": [{
                        "start_date": "2019-10-11 12:00:00"
                }],
                "deals": [{
                        "id": 628539
                }],
                "insertion_orders": [{
                        "id": 1363850
                }],
                "line_item_subtype": "standard_curated",
                "name": "Curated Deal Line Item Example Line Item",
                "revenue_type": "vcpm",
                "revenue_value": null,
                "supply_strategies": {
                        "managed": false,
                        "deals": true,
                        "rtb": false
                },
                "profile_id": 113067333,
                "valuation": {
                        "min_revenue_value": 10
                }
        }
}

    JSON de ejemplo: presupuesto diario de ingresos de artículos de línea de oferta seleccionados

    > cat curated_deal_line_item_daily.json
{
        "line-item": {
                "ad_types": ["video"],
                "auction_event": {
                        "kpi_auction_type_id": 1,
                        "payment_auction_type_id": 1,
                        "revenue_auction_type_id": 1
                },
                "budget_intervals": [{
                        "daily_budget_imps": 270,
                        "end_date": "2019-10-18 23:59:59",
                        "start_date": "2019-10-11 12:00:00",
                        "timezone": "US/Pacific"
                }],
                "deals": [{
                        "id": 618159
                }],
                "insertion_orders": [{
                        "id": 1363850
                }],
                "line_item_subtype": "standard_curated",
                "name": "Curated Deal Line Item Example Line Item",
                "revenue_type": "vcpm",
                "revenue_value": null,
                "supply_strategies": {
                        "managed": true,
                        "deals": true,
                        "rtb": false
                },
                "profile_id": 113067333,
                "valuation": {
                        "min_revenue_value": 10
                }
        }
}

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

    Solicitud de ejemplo: elemento de línea de oferta curada sin presupuesto

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

    Solicitud de ejemplo: presupuesto diario de ingresos de artículos de línea de oferta seleccionados

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

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

  4. Anote el identificador de elemento de línea en el cuerpo de la respuesta para que pueda identificar este elemento de línea de oferta seleccionado más adelante para cambiar su state (active o inactive) o modificarlo.

Campos JSON para el elemento de línea de oferta seleccionado

Campo Tipo Descripción
insertion_orders matriz Matriz que contiene el identificador de pedido de inserción al que desea asociar este elemento de línea de oferta seleccionado
name string Nombre del artículo de línea de oferta seleccionado (Nota: el comprador no verá esto)
ad_types matriz Tipo de creatividad que se usa para este elemento de línea de oferta seleccionado. Posibles valores:
- "banner"
- "video" (también incluye tipos de audio)
- "native"
line_item_subtype enumeración Subtipo de elemento de línea. Para los artículos de línea de oferta seleccionados, el valor de este campo debe ser "standard_curated". Vea la nota de este campo.
profile_id integer Id. de perfil asociado al elemento de línea de oferta seleccionado (consulte Paso 5: Creación de un perfil de línea de oferta seleccionada)
budget_intervals matriz de objetos Incluya siempre un objeto start_date. Deje end_datenull un elemento de línea de oferta sin fecha de finalización.
deals matriz de objetos El id campo dentro de las ofertas debe ser el identificador de la oferta que creó en paso 4: Creación de una oferta.
supply_strategies objeto Objeto que contiene varios campos booleanos que se usan para designar los orígenes de suministro de inventario a los que desea dirigirse.

Para un elemento de línea de oferta seleccionado, el managed campo debe establecerse en false (este valor se asigna cuando se establece "standard_curated"en "line_item_subtype" )

Nota: Los rtb campos o deals deben establecerse true en (estos campos no se asignan cuando "line_item_subtype" se establece en "standard_curated"), por lo que deberá asignar estos valores en consecuencia.

Nota terminología:
- rtb hace referencia a la agregación de inventario de Exchange abierto
- deals hace referencia a las ofertas de acumulación
revenue_type enumeración cpm para la oferta vcpm de precio fijo (CPM), para la oferta de precio estándar (CPM dinámico).
revenue_value double Si establece en revenue_typecpm (Fijo), establezca el precio fijo mediante revenue_value. Si usa Standard, establezca este valor nullen .
valuation objeto Para las operaciones seleccionadas, utilice los siguientes campos de objeto de valoración:
- min_revenue_value
- Si establece en revenue_typevcpm (Estándar), establezca el precio mínimo en min_revenue_value.
- Si establece en revenue_typecpm (Fijo), establezca el valor de min_revenue_value en null.

- min_margin_cpm - Establezca el valor de margen en min_margin_cpm al usar CPM como tipo de margen.

- min_margin_pct - Establezca el valor de margen en min_margin_pct al usar porcentaje como tipo de margen.

Nota: Los min_margin_cpm campos y min_margin_pct no se pueden establecer al mismo tiempo. Si se establece uno, el otro debe ser null.
auction_event objeto Objeto para propiedades de tipo de evento de subasta: los kpi_auction_type_idcampos , payment_auction_type_idy revenue_auction_type_id del objeto auction_event deben establecerse 1en .
Nota para el line_item_subtype campo

Al establecer line_item_subtype el campo en "standard_curated" , se asignarán automáticamente los siguientes valores a estos campos relacionados.

"line_item_type": "standard_v2",
"bid_object_type": "deal",
"delivery_model_type": "standard",
"supply_strategies": {
"managed": false,
"programmatic_guaranteed": false
}

El line_item_subtype campo (y los campos o matrices asociados) no se puede cambiar después de crear el elemento de línea.

Campos JSON opcionales útiles para el elemento de línea de oferta seleccionado
Campo Tipo Descripción
budget_intervals matriz de objetos Establezca un presupuesto en la oferta mediante campos incluidos budget_intervals : daily_budget, daily_budget_imps, lifetime_budgeto lifetime_budget_imps. Use los campos sin imp si la línea de negocio seleccionada tiene el tipo de presupuesto de ingresos o los campos con _imp al final si la línea de la oferta tiene impresión de tipo de ingresos. Puede tener un presupuesto diario o de duración, no ambos. Un presupuesto de por vida que se encuentra entre vuelos termina dividiéndose en cada vuelo a través de la API. Recuerde que si la oferta no tiene fecha de finalización, no puede tener un presupuesto.
state enumeración Estado del elemento de línea de oferta seleccionado. El valor predeterminado es active, por lo que se establece en inactive si no desea que la oferta se produzca inmediatamente.