Guía de configuración de la API del elemento de línea de negocio

La configuración de una implementación de API de una línea de negocio 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 utilizando nuestra API.

Información general

Las líneas de pedido de ofertas 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.

La configuración de una línea de negocio generalmente 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 de otros objetos API y hay un orden que debe seguir al crear o acceder a objetos cuando crea una línea de crédito. Por ejemplo, debe proporcionar los identificadores de los siguientes objetos de API:
- advertiser
- insertion-order
- deal
- 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 trato.

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
• Paso 4: Crear una oferta
• Paso 5: Crear un perfil de línea de negocio
• Paso 6: Crear un elemento de línea de negocio

Autenticación

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

Anunciante

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.

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

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": "Deal Line Item Example Advertiser",
           "timezone": "US/Pacific"
       }
   }
   

2. Haga una POST solicitud a la https://api.appnexus.com/advertiser endpoint con este anunciante JSON 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

Orden de inserción

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 pedido de trato. Las líneas de negocio requieren una orden de inserción fluida (consulta los campos obligatorios a continuación).

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

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 un JSON de la orden de inserción (a continuación se muestran dos ejemplos):

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

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "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"
       }
   }
   

   Ejemplo de JSON: pilotos, presupuestos de impresión

   $ cat insertion-order-flights.json
   {
       "insertion-order": {
           "name": "Deal Line Item Example IO",
           "budget_intervals": [
   
               {
                   "start_date": "2019-10-10 00:00:00",
                   "end_date": "2019-10-12 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 980,
                   "lifetime_pacing": false
               },
               {
                   "start_date": "2019-10-13 00:00:00",
                   "end_date": "2019-10-18 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 100,
                   "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.

   Ejemplo de solicitud: sin fecha de finalización, sin presupuesto

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

   Solicitud de ejemplo: pilotos, presupuestos de impresión

   $ curl -b cookies -c cookies -X POST -d @insertion-order-flights.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 el elemento de línea de negocio en el paso 6: Crear un elemento de línea de negocio.

Repartir

Paso 4: Crear una oferta

Tendrás que crear el trato que quieras asociar con el 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'

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": "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.

Perfil

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. Consulte Servicio de perfiles para obtener más información.

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. Consulte el Servicio de perfiles para obtener más información sobre los campos disponibles.

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

1. Crear un perfil de elemento de línea de negocio 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ís, límites de frecuencia reciente 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 de perfil en el cuerpo de la respuesta para que puedas usarlo al crear el elemento de línea de negocio en el Paso 6: Crear un elemento de línea de trato.

Línea de pedido

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

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 negocio de trato.

Campos JSON para el objeto de línea de negocio

Campos JSON opcionales útiles

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

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 sin presupuesto

   > cat 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
           },
           "bid_object_type": "deal",
           "budget_intervals": [{
               "start_date": "2019-10-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": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   Ejemplo JSON: Presupuesto de impresiones de por vida de la línea de pedido de oferta

   > cat deal_line_item_lifetime.json
   {
       "line-item": {
           "ad_types": ["video"],
           "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": "2019-10-18 23:59:59",
                       "lifetime_budget_imps": 2586,
                       "start_date": "2019-10-11 12:00:00",
                       "timezone": "US/Pacific"
                   },
                   {
                       "end_date": "2019-10-25 23:59:59",
                       "lifetime_budget_imps": 2414,
                       "start_date": "2019-10-19 00: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": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   Ejemplo de JSON: Presupuesto de ingresos diarios de elemento de línea de negocio

   > cat 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
           },
           "bid_object_type": "deal",
           "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_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

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.

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