Guía de configuración de la API de la línea de pedido de negocio seleccionada

La configuración de una implementación de API de una línea de línea de negocio seleccionada para apuntar a un trato requiere la configuración de una serie de propiedades diferentes en diferentes objetos de API. Esta guía explicará el proceso de creación y configuración de una línea de negocio seleccionada utilizando nuestra API.

Información general

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

La configuración de una línea de negocio seleccionada generalmente implica realizar solicitudes a los siguientes puntos de conexión del servicio de API para acceder o crear los objetos de API correspondientes:

Punto de conexión de API Objeto de API Referencia detallada
https://api.appnexus.com/advertiser Anunciante Servicio de anunciantes
https://api.appnexus.com/insertion-order orden de inserción Servicio de órdenes de inserción
https://api.appnexus.com/deal oferta Servicio de oferta
https://api.appnexus.com/profile perfil Servicio de perfiles
https://api.appnexus.com/line-item línea de pedido (ALI) Partida - Servicio ALI

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 de API a menudo tienen dependencias de otros objetos de API y hay un orden que debe seguir al crear o acceder a objetos cuando crea una línea de línea de negocio seleccionada. 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 una línea de negocio seleccionada.

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 prácticas recomendadas específicas de la configuración de una línea de pedido de negocio seleccionada:

  • Establezca el state campo de la línea de pedido de negocio seleccionada 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.
  • No segmente ofertas seleccionadas dentro de una línea de pedido de oferta seleccionada. Esta configuración no se admite y puede causar problemas de entrega.

Procedimiento de instalación

Advertencia

Al configurar una línea de pedido de oferta seleccionada, no debe establecer una prioridad. Si es necesario establecer una prioridad, establézcala en el valor predeterminado 5.

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

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 (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 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 (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 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 un anunciante o acceder a él a partir del cual crear una línea de pedido de oferta seleccionada. Puede configurar anunciantes para las líneas de pedido de ofertas seleccionadas de la misma manera que lo haría con las líneas de pedido aumentadas.

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

  1. Crear un JSON de anunciante:

    $ cat advertiser.json
{
    "advertiser": {
        "name": "Curated 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. Anote el identificador de anunciante en el cuerpo de la respuesta para que pueda usarlo al crear el elemento de línea de negocio curado en el paso 6: Crear un elemento de línea de negocio curado.

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

Campo Tipo Obligatorio u opcional Descripción
name string Obligatorio El nombre del anunciante
timezone enumeración Opcional La zona horaria del anunciante. Consulte Zonas horarias de API para obtener detalles y valores aceptados.
use_insertion_orders booleano Obligatorio Este campo debe establecerse para true crear líneas de pedido de negocio seleccionadas.

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

Tendrá que crear una orden de inserción o acceder a ella para crear una línea de línea de negocio seleccionada. Las líneas de negocio seleccionadas requieren una orden de inserción fluida (consulte los campos obligatorios a continuación).

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

  1. Crear una orden de inserción JSON:

    Ejemplo de JSON: 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 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, 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 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 orden de inserción en el cuerpo de la respuesta para que pueda usarlo al crear el elemento de línea de negocio curado en el Paso 6: Crear un elemento de línea de trato curado.

Campos JSON para orden de inserción directa

Campo Tipo Obligatorio u opcional Descripción
budget_intervals matriz de objetos Obligatorio Para que una orden de inserción creada a través de la API sea fluida, debes usar el budget_intervals campo.
name string Obligatorio El nombre del anunciante

Paso 4: Crear una oferta

Tendrá que crear el trato que desea asociar con el elemento de línea de negocio seleccionado.

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

  1. Crear una oferta JSON:

    $ cat deal.json
{
    "deal": {
        "name": "Curated Deal",
        "buyer": {
            "id": 2379
        },
        "type": {
            "id": 5,
            "name": "Curated"
        },
        "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 de la oferta en el cuerpo de la respuesta para que puedas utilizarlo cuando crees la línea de negocio en el paso 6: Crear una línea de línea de negocio seleccionada.

Campos JSON para oferta

Campo Tipo Obligatorio u opcional Descripción
auction_type objeto Opcional El tipo de subasta de la oferta (Standard/Fija/Mercado). Este valor debe coincidir con lo que se establece en el elemento de línea de negocio seleccionado (a través revenue_type//min_revenue_valuerevenue_valuede ).
buyer string Obligatorio Id. de miembro comprador de la oferta. Este campo no se puede cambiar después de la creación.
name string Obligatorio El nombre del trato.
Nota: El comprador verá este nombre.
type objeto Obligatorio El tipo de trato. Este campo debe establecerse en "5" para ofertas seleccionadas.
version Entero Obligatorio Este campo debe establecerse para "2" asociar el trato a un elemento de línea de negocio seleccionado.

Campos JSON opcionales útiles

Campos JSON para creatividades permitidas
Marca (consulte Servicio de marca)
Campo Tipo Descripción
brand_restrict booleano - True: La oferta está restringida solo a las marcas enumeradas
- False: Otras marcas pueden servir
brands matriz de objetos Variedad de marcas aptas
id Entero Campo dentro brandsde: ID de la marca que es apta para la oferta
name string Campo dentro brandsde: nombre de la marca que cumple los requisitos de la oferta
override booleano Campo dentro de brands: establecido para true permitir que una marca específica publique un acuerdo 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 subtipo de medios y Servicio de tipo de medios)
Campo Tipo Descripción
allowed_media_subtypes matriz de objetos Los subtipos de medios permitidos para el acuerdo.
id Entero Campo dentro allowed_media_subtypesde : El identificador del subtipo de medio permitido para la oferta
allowed_media_types matriz de objetos Los tipos de medios permitidos para el acuerdo
id Entero Campo dentro allowed_media_typesde : El ID 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: Crear un perfil de línea de negocio seleccionado

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

Nota:

Puedes segmentar los editores, emplazamientos y categorías de los vendedores con una línea de pedido de oferta seleccionada mediante las siguientes matrices:

  • platform_publisher_targets
  • platform_placement_targets
  • platform_content_category_targets.

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

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

  1. Crear un perfil de elemento de línea de negocio seleccionado JSON:

    Ejemplo: Creación de perfiles con países y umbrales de tasa de finalización de la tasa de 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 https://api.appnexus.com/profile punto de conexión con este JSON de perfil de oferta seleccionado y un advertiser_idarchivo .

    Ejemplo: Creación de perfiles con países y umbrales de tasa de finalización de la tasa de 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 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 perfil en el cuerpo de la respuesta para que pueda usarlo al crear el elemento de línea de negocio curado en el Paso 6: Crear un elemento de línea de negocio curado.

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

Hay muchos campos opcionales disponibles en el perfil de línea de línea de negocio seleccionado para la segmentación con el elemento de línea de negocio seleccionado. Por ejemplo, puedes dirigirte a propiedades asociadas con el inventario, tipos de inventario, listas de permitidos, listas de bloqueados, tipos de dispositivos, etc. Consulte el Servicio de perfiles para obtener más información sobre los campos disponibles.

Paso 6: Crear un elemento de línea de negocio seleccionado

Por último, tendrá que crear la línea de pedido de negocio seleccionada para asociar el ID de negocio y el perfil de línea de línea de negocio seleccionado que creó en el Paso 5: Crear un perfil de línea de línea de negocio seleccionado.

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

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

    Ejemplo de JSON: Línea de pedido de negocio seleccionada 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
                }
        }
}

    Ejemplo de JSON: Elemento de línea de negocio seleccionado presupuesto de ingresos diarios

    > 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. Haga una POST solicitud al https://api.appnexus.com/line-item punto de conexión utilizando este elemento de línea de negocio JSON y un advertiser_idarchivo .

    Ejemplo de solicitud: Línea de pedido de negocio seleccionada 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'

    Ejemplo de solicitud: Partida de negocio seleccionada Presupuesto de ingresos diarios

    > 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 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 pedido de negocio seleccionada más tarde para cambiar su state (active o inactive) o modificarla.

Campos JSON para una línea de pedido de oferta seleccionada

Campo Tipo Descripción
insertion_orders matriz Matriz que contiene el ID de la orden de inserción a la que desea asociar esta línea de pedido de negocio seleccionada
name string Nombre del elemento de línea de negocio seleccionado (Nota: el comprador no lo verá)
ad_types matriz El tipo de recurso creativo utilizado para esta línea de pedido de oferta seleccionada. Posibles valores:
- "banner"
- "video" (incluye también los tipos de audio)
- "native"
line_item_subtype enumeración El subtipo de línea de pedido. Para las líneas de negocio seleccionadas, el valor de este campo debe ser "standard_curated". Vea la nota para este campo.
profile_id integer ID de perfil asociado con el elemento de línea de negocio curado (consulte el Paso 5: Crear un perfil de elemento de línea de negocio curado)
budget_intervals matriz de objetos Siempre incluya un start_date. Salir end_datenull para una línea de pedido de oferta sin fecha de finalización.
deals matriz de objetos El id campo dentro de los tratos debe ser el ID del trato que creó en el Paso 4: Crear un trato.
supply_strategies objeto Un objeto que contiene varios campos booleanos que se utiliza para designar los orígenes de suministro de inventario a los que desea dirigirse.

Para una línea de negocio seleccionada, el managed campo debe establecerse en false (este valor se asigna cuando se "line_item_subtype" establece en "standard_curated")

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

Nota terminológica:
- rtb hace referencia a Agregación de inventario de Open Exchange
- deals hace referencia a las ofertas acumuladas

Ejemplos:

- Intercambio abierto:
"supply_strategies": {
"managed": false,
"rtb": true,
"deals": false
},
- Todas las ofertas:
"supply_strategies": {
"managed": false,
"rtb": false,
"deals": true
},
revenue_type enumeración cpmpara la oferta de precio fijo (CPM), vcpm para la oferta de precio Standard (CPM dinámico).
revenue_value double Si establece el revenue_type valor establecido en cpm (Fijo), establezca el precio fijo usando revenue_value. Si usas Standard, establece este valor en null.
valuation objeto Para las ofertas mantenidas, use los siguientes campos de objeto de valoración:
- min_revenue_value
- Si establece el revenue_type en vcpm (Standard), establezca el precio mínimo en min_revenue_value.
- Si estableces en revenue_typecpm (Fijo), establece el valor de min_revenue_value en .null

- min_margin_cpm - Establezca el valor del margen cuando min_margin_cpm use CPM como tipo de margen.

- min_margin_pct - Establezca el valor del margen cuando min_margin_pct utilice el 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 las propiedades del tipo de evento de subasta: Los campos , payment_auction_type_id, y revenue_auction_type_id los campos del objeto auction_event deben establecerse en 1.kpi_auction_type_id
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 pueden cambiar después de crear la línea de pedido.

Útiles campos JSON opcionales para una línea de negocio seleccionada
Campo Tipo Descripción
budget_intervals matriz de objetos Establece un presupuesto en la oferta usando campos que budget_intervals incluyen: daily_budget, , lifetime_budgetdaily_budget_imps, o lifetime_budget_imps. Use los campos sin diablillo si la línea de pedido del negocio seleccionada tiene un tipo de presupuesto de ingresos o los campos con _imp al final si el elemento de línea de negocio tiene una impresión de tipo de ingresos. Puedes tener un presupuesto diario o de por vida, no ambos. Un presupuesto de por vida que se encuentra en todos los vuelos termina dividiéndose en cada vuelo a través de la API. Recuerda que si tu oferta no tiene fecha de finalización, no puede tener un presupuesto.
state enumeración Estado del elemento de línea de negocio seleccionado. El valor predeterminado es active, así que establézcalo en inactive si no desea que la oferta se active de inmediato.
  • Last updated on