Compartir a través de

Yield Analytics API

Información general

La API y los servicios de Yield Analytics se exponen a través de una interfaz basada en REST. Está diseñado para que el desarrollo de funcionalidad personalizada sea cómodo para los desarrolladores experimentados con plataformas de desarrollo orientadas a servicios, AJAX, REST y Web 2.0. Los desarrolladores deben estar familiarizados con los paradigmas de aplicación basados en web, como AJAX, XML, JSON y el protocolo HTTP(S) antes de intentar el desarrollo con la API y los servicios de Yield Analytics.

Tipos de contenido

La API REST de Yield Analytics es accesible actualmente a través de dos tipos de contenido MIME de respuesta:

  • XML: mediante Content-type: application/xml
  • JSON: mediante Content-type: application/json

Seleccionar el tipo de contenido deseado es una opción que el desarrollador de la API debe tomar caso por caso. La funcionalidad de API es simétrica entre los tipos de contenido. Los desarrolladores de API pueden especificar el tipo de contenido deseado en los parámetros del método HTTP GET o POST o a través de su biblioteca cliente AJAX o HTTP.

Códigos de estado y comprobación de errores

Los desarrolladores de API deben comprobar los códigos de respuesta HTTP devueltos desde la API REST del servicio para detectar los errores propagados por las llamadas API. Las llamadas correctas al servicio generarán 200 códigos de respuesta de intervalo. Las respuestas HTTP de intervalo 400 y 500 denotan errores. Es probable que los códigos de respuesta y el texto específicos cambien durante el desarrollo beta de la API; sin embargo, los intervalos no.

Seguridad

La API de servicio expone los datos de la aplicación de forma segura. El uso de la funcionalidad de API está restringido a los usuarios autenticados y se expone a través de protocolos de transporte seguros. El acceso a la API debe tener lugar en el contexto siguiente:

Autenticación

Para obtener más información sobre la autenticación, consulte Yield Analytics API : Proceso de autenticación.

Confidencialidad

La confidencialidad se mantiene mediante la comunicación basada en capa de socket seguro para interactuar con yield analytics API. Los desarrolladores de API deben preferir el uso de HTTPS en lugar de una comunicación HTTP insegura siempre que sea posible. Consulte la biblioteca cliente HTTP sobre cómo habilitar HTTP a través de SSL al desarrollar fuera de un contexto de explorador web.

Servicios de API

Filtrado de datos

Funciones de alias

Filtrado de consumo

Para las llamadas API que aceptan un filtro de consumo como una variable de ruta de acceso o un objeto de solicitud, el cálculo de disponibilidad se puede controlar aún más. Disponibilidad = capacidad: consumo. Agregar un filtro de consumo a una solicitud de disponibilidad controla qué consumo se resta de la capacidad para proporcionar la disponibilidad. Todas las líneas de pedido que coincidan con un filtro de consumo tendrán su consumo restado de la capacidad al calcular la disponibilidad.

  • Cuando se proporcionan varios pares clave-valor con la misma clave y un operador = (EQUAL) como en CONSUMPTION_TYPE anterior, los valores se combinan mediante una regla OR. Por ejemplo, CONSUMPTION_TYPE puede ser DIRECT o CONTAINED

  • Cuando se proporcionan varios pares clave-valor con la misma clave y un operador != (NOT_EQUAL) (por ejemplo, EXTERNAL_ID!=223415; EXTERNAL_ID!=223416), los valores se combinan mediante una regla AND.

  • Cuando se proporcionan varios pares clave-valor con operadores diferentes (por ejemplo, PRIORITY>=5; PRIORITY<=10), los valores se combinan mediante una regla AND.

  • Los pares con claves de función diferentes se combinan mediante una regla AND.

Para ver todos los valores de clave de función posibles disponibles para una instalación de Analytics determinada (puede diferir según el cliente), puede enviar una consulta REST al motor de consulta y devolverá una lista de todas las claves de función. Este es el formato de la consulta REST para enumerar las claves de función:

Modelo de datos

Diagrama del modelo de objetos de Yield Analytics.

Objetos clave

Order

Un pedido es un contenedor de elementos de línea y se ha creado en un sistema de administración de pedidos (OMS) o directamente en el servidor de anuncios y, a continuación, se introduce en Yield Analytics cada noche durante el paso de importación del pedido durante el procesamiento. Un pedido en la parte de venta directa y garantizada del sector de la publicidad en línea se refiere a un pedido de inserción mutuamente acordado que incorpora términos específicos, bajo los cuales los editores entregarán anuncios (líneas de pedido) en sitios en beneficio de la agencia o anunciante.

Al hacer referencia a un pedido en Yield Analytics, hace referencia al nombre del pedido asociado a una línea de pedido o grupo de líneas de pedido.

Pedido de elemento de línea

Una línea de pedido es un anuncio o ubicación que tiene un conjunto específico de fechas de vuelo y una creatividad asociada y se compra como parte de un pedido de inserción. A veces también se conocen como elementos de línea, estas líneas de pedido tendrán metadatos asociados a ellos, lo que ayuda a describir acuerdos contractuales para la entrega, como el CPM (tasa), así como contratos de entrega de anuncios, como la segmentación y la cantidad de impresiones programadas.

Producto

Piense en un producto como lo que un editor vendería realmente a los anunciantes. Cada producto tiene un nombre único y se puede considerar como un puntero a un destino. ¡Pero ten cuidado! Existe una tendencia a conflatar los productos y la segmentación. Se trata de un nombre erróneo, ya que varios productos se pueden asociar a un destino. Además de estar asociados a destinos, los productos tienen metadatos adicionales asociados, como el nombre y, posiblemente, la tasa y el grupo de productos. Para reiterar: los destinos son únicos; muchos productos pueden estar asociados a un único destino.

Los clientes pueden desactivar los productos, pero no eliminarlos. Si no hay ningún producto activo asociado a un destino, Yield Analytics no procesa en el destino, pero conserva su historial.

Hay cuatro tipos de productos en Yield Analytics:

  • Tarjeta de tarifa: representa los productos del catálogo desde el que el equipo de ventas del publicador vende

  • Informes: cualquier inventario que quiera analizar en Yield Analytics. Este es el tipo de producto más importante, ya que son la clase de producto sobre la que el cliente tiene más control y los que se usan para acumular datos históricos. Esta última pieza, que son la base de los datos históricos, suele ser uno de los conceptos más difíciles de entender para los clientes durante la implementación, ya que requiere que piensen en todos los productos en los que finalmente necesitarán recopilar datos. La previsión se puede realizar sin informar de productos, sin embargo, los informes históricos (como cabría esperar) no pueden.

  • Personalizado: productos que se corresponden con líneas de pedido. Cada vez que Yield Analytics importa líneas de pedido, crea productos de línea de pedido personalizados que solo existen durante el período de vida de la línea de pedido. Yield Analytics mantiene por completo estos productos (creados, mantenidos, inactivados). A menudo, cuando los clientes quieren realizar una limpieza de productos, intentarán quitar productos personalizados y nuestro equipo de servicios debe volver a formarse.

  • Estacional: se usa para definir el inventario que está influenciado por un modelo estacional específico. Yield Analytics permite aplicar modelos estacionales a áreas de inventario cuando hay fluctuaciones empresariales estacionales conocidas en el volumen de impresiones de un editor (por ejemplo, un editor deportivo como ESPN podría ver un enorme aumento una vez al año a finales de enero que corresponde a la Superbowl).

Target

Un destino representa un grupo único de inventario descrito por una combinación de pares atributo-valor, que identifica de forma única el grupo de inventario. Esta combinación única y descriptiva es a lo que nos referimos como una expresión de destino. Los objetivos pueden definirse en cualquier nivel de granularidad ("deportes", "entretenimiento", "300x250", "Chicago", etc.). "Deportes" y "entretenimiento" probablemente corresponderían a una sección del sitio web de un editor o a una etiqueta usada para clasificar el inventario en el back-end (para las ventas de anuncios). '300x250' correspondería al tamaño de una etiqueta de anuncio. Es probable que "Chicago" haga referencia a la dirección IP del usuario.

Con los destinos anteriores, una expresión de destino de ejemplo podría ser:

  • adunit in ('sports')

En la expresión de destino anterior, "adunit" es el atributo de destino y "sports" es el valor del atributo.

Una expresión de destino más compleja podría ser:

  • adunit in ('sports', 'entertainment') y size in ('300x250') o placement in ('business') and size in ('300x250','300x600','1x1') y pos in ('top')

Términos clave

Allocation

Proceso por el que Yield Analytics emula la lógica del servidor de anuncios para predecir cómo consumirán las líneas de pedido individuales en productos individuales para cada día en el intervalo de fechas de previsión.

  • Este proceso representa varias líneas de pedido que compiten por el mismo inventario.

  • Este proceso tiene en cuenta las superposiciones entre productos. Una sola línea de pedido puede consumir en muchos productos a la vez con una sola impresión. Dependiendo de la relación entre el destino de la línea de pedido y el destino del producto, el tipo de consumo de la línea de pedido con respecto al producto puede ser Indirecto, Directo o Contenido (vea a continuación).

Proceso de asignación

  • En un día determinado, para un nivel determinado (conjunto de prioridades), un conjunto de líneas de pedido pedirá una parte de sus impresiones.

  • La parte se define mediante el vuelo, el objetivo de línea de pedido (si se basa en objetivos), la cuota de voz (para las líneas CPD)

  • La cantidad de impresiones está limitada por lo que está disponible

  • La disponibilidad se reduce a medida que se trabaja a través de líneas de pedido

  • La disponibilidad se reduce aún más en un destino, ya que el consumo se toma de destinos superpuestos

  • El objetivo de Yield Analytics es mantener estos totales y las relaciones entre ellos (proceso iterativo)

Métricas en riesgo

Yield Analytics usa los resultados de asignación para generar varias métricas en riesgo que pueden ayudar a las operaciones de anuncios a comprender qué líneas de pedido garantizadas están en riesgo de infra-entrega para que puedan realizar las intervenciones adecuadas.

Métricas Fórmula Description
Ritmo Impresiones consumidas: impresiones programadas Medida del riesgo de una línea de pedido en entrega o entrega excesiva. Esta métrica incluye la entrega excesiva y la infra entrega, y se debe usar para medir ambas.
Ritmo (duración) Impresiones consumidas: impresiones programadas Esto es lo mismo que la métrica Pacing, salvo que esta métrica se agrega a lo largo de la duración de la línea de pedido y no está enlazada por el período de tiempo. Cuando se usa la métrica de duración, el filtro de período de tiempo solo se usa para filtrar para ordenar las líneas que se entregan en el período de tiempo seleccionado.
Porcentaje de consumo a programación (Eventos consumidos o eventos programados) x 100 Una medida de ritmo por programación. Para períodos de tiempo futuros, este número tiene en cuenta el consumo esperado en función de la previsión de asignación. Las líneas de pedido garantizadas con los tipos de precios CPM, CPD y CPC están sujetas a este cálculo. C:S% es independiente de eventos, lo que significa que las impresiones y los clics se usan indistintamente, determinados por el tipo de precios de la línea de pedido.
Porcentaje de consumo a programación (duración) (Eventos consumidos o eventos programados) x 100 Esto es lo mismo que la métrica Porcentaje de consumo a programación, salvo que esta métrica se agrega a lo largo de la duración de todas las líneas de pedido y no está enlazada por el período de tiempo. Cuando se usa la métrica de duración, el filtro de período de tiempo solo se usa para filtrar para ordenar las líneas que se entregan en el período de tiempo seleccionado.
Ingresos frente al objetivo Ingresos obtenidos: ingresos contratados Una medida de los ingresos que están en riesgo de infra-entrega. Esta métrica incluye la entrega por debajo de la entrega y la entrega excesiva, y se debe usar para medir ambos.
Ingresos frente al objetivo (duración) Ingresos obtenidos: ingresos contratados Esto es lo mismo que la métrica Ingresos por objetivo, salvo que esta métrica se agrega a lo largo de la duración de todas las líneas de pedido y no está enlazada por el período de tiempo. Cuando se usa la métrica de duración, el filtro de período de tiempo solo se usa para filtrar para ordenar las líneas que se entregan en el período de tiempo seleccionado.

Disponibilidad

Capacidad: consumo (garantizado)

  • La capacidad de un producto puede ser completamente consumida por una mezcla de líneas de pedido garantizadas y preferentes. El consumo por líneas de pedido preferentes se considera disponible.

  • El objetivo de un editor suele ser "vender" el consumo preferente con líneas de pedido garantizadas (venta directa), ya que estas líneas suelen tener una tasa más alta y no ponen en riesgo otra demanda garantizada.

Capacidad

El número máximo de impresiones que se pueden entregar en un producto determinado.

Consumo

Número de impresiones que se han entregado en el pasado o que se prevé que se entreguen en el futuro.

Tipo de consumo

Así es como Yield Analytics clasifica cómo una línea de pedido determinada consume en un producto determinado y es una función de la relación entre el destino de la línea de pedido y el destino del producto.

  • Directo: la línea de pedido y el producto comparten el mismo destino

  • Contenido: la línea de pedido debe entregarse dentro del producto. El destino de la línea de pedido es un elemento secundario del destino del producto.

  • Indirecto: la línea de pedido puede entregarse dentro o fuera del producto. El destino de la línea de pedido es un elemento primario o un elemento relacionado del destino del producto.

Método piloto

Indica la forma ideal de la distribución de impresiones en el intervalo de fechas de la línea de pedido (también conocido como ritmo)

Los métodos de vuelo comunes son:

  • uniformemente

  • front loaded

  • lo más rápido posible

Clase de inventario

Atributo de cada línea de pedido de Yield Analytics, derivada del tipo de contrato de la línea de pedido. Hay tres valores de clase de inventario:

Clase de inventario Description
Garantizado Los publicadores han garantizado a los anunciantes que entreguen un volumen específico de impresiones para líneas basadas en objetivos o una parte específica de voz (SOV) para las líneas de costo por día. SOV hace referencia a la proporción de impresiones que una línea de pedido determinada consume de un producto determinado.
- Tipos de contrato de APAS: garantizado exclusivo, garantizado Standard
- Tipos de contrato de DFP: patrocinio, Standard
- Tipos de contrato de OAS: Dinámico, Dinámico Mensual, Exclusivo, Fijo, Abierto
Preferente Estas líneas de pedido se pueden adelantar por líneas de pedido garantizadas.
- Tipos de contrato de APAS: Impresiones, Porcentaje
- Tipos de contrato de DFP: AdMob, AdSense, Advertising Exchange, Bulk, Click Tracking, House, Network, Price Priority
- Tipos de contrato de OAS: House y cualquier tipo de contrato que incluya la palabra "Preemptible"
Unspecified Se corresponde con impresiones y impresiones no rellenadas que se entregan mediante líneas de pedido que no se han importado en Yield Analytics y, por tanto, son "desconocidas".

Prioridad

Determina qué línea de pedido será la primera en consumir capacidad (establecida en el servidor de anuncios).

C:S %

Una medida de ritmo por programación. Para períodos de tiempo futuros, este número tiene en cuenta el consumo esperado en función de la previsión de asignación. Las líneas de pedido garantizadas con los tipos de precios CPM, CPD y CPC están sujetas a este cálculo.

Ritmo

Medida del riesgo de una línea de pedido en entrega o entrega excesiva. Esta métrica incluye tanto en entrega como en entrega excesiva, y se debe usar para medir ambos.

Atributos dinámicos

Los atributos dinámicos permiten valores diferentes para que el mismo atributo de destino sea AND'ed juntos en una expresión de destino. La segmentación de Yield Analytics no permite usar la lógica AND entre dos valores que pertenecen al mismo atributo. Esto es problemático, porque hay casos en los que tiene sentido. Por ejemplo, la segmentación de palabras clave en la que desea dirigirse tanto a "baloncesto" como a "béisbol". Por ejemplo, si la expresión deseada es la siguiente:

  • kw in ('basketball') y kw in ('baseball')

No se permitirá y tendrá que usar la dinamización. La dinamización permite dirigirse a ambos en una sola expresión mediante la creación de un nuevo atributo con el atributo original y el valor concatenados juntos. Por ejemplo:

  • kw_basketball en ('true') y kw_baseball en ('true')

Los atributos dinámicos también se pueden excluir. Por ejemplo, supongamos que en DFP tiene adunit 1, que los contiene como elementos secundarios: adunit 2_a, adunit 2_b, adunit 2_c. Si quisiera dirigirse a todo menos 2_b de la unidad de adunit, usaría la expresión siguiente:

  • adunit in ('adunit 1') y adunit exclude !in ('adunit 2_b')

DFP también tiene un atributo denominado adunit_only, que permite seleccionar solo la unidad de adunit especificada y no cualquiera de sus elementos secundarios. Sin embargo, dado que esto no es universal para todos los servidores de anuncios, podemos usar la sintaxis en la expresión anterior.

Líneas de orden zombi

Línea de pedido en estado Pendiente con una fecha de inicio en el pasado. La línea de pedido no se entrega en realidad, pero Yield Analytics la asigna en el futuro porque está en estado Pendiente. Las líneas de pedido pendientes y anteriores a su fecha de inicio se conocen como líneas de pedido "zombis" porque reservan el inventario en Yield Analytics que nunca consumirán, suponiendo que su estado no cambie.

  • Last updated on