Guía de integración de OpenRTB 2.3 de Vungle

Esta es la versión 2.1.0 (agosto de 2017) de la Guía de integración de OpenRTB 2.3 de Vungle. En este artículo se especifican los detalles para la integración con Vungle Exchange por medio de OpenRTB 2.3.

Contenido

1. Solicitud y respuesta

1.1 Entidad

Todas las entidades de esta sección son un subconjunto de la especificación OpenRTB 2.3.1; en caso de que falten campos o requisitos, use los requisitos predeterminados para la especificación en sí misma.

1.2 Extensión

Para entregar mejor un anuncio, Vungle Exchange proporciona información más allá del protocolo estándar de OpenRTB. Estas extensiones no se superponen con, sino que complementan, la implementación de OpenRTB existente. Las extensiones son divididas en objetos individuales de la forma más adecuada.

Todos los campos de extensión son encapsulados en un objeto JSON por un campo de extensión de primer nivel denominado 'vungle' debajo del objeto OpenRTB 'ext'. Para simplificar, en la documentación de las siguientes secciones de este documento se ha omitido el campo 'vungle'. A continuación hay un ejemplo de un objeto JSON de OpenRTB que contiene extensiones de Vungle:

{
...
"ext": {
"vungle": {
// Campos de extensión individual en varias filas a continuación.
}
}
}

Por ejemplo, un objeto de solicitud de puja de alto nivel puede parecerse al siguiente:

{
"id": "572c3535ab0af400011a721a",
"imp": [{<impression object>}],
"app": {<application object>},
"device": {<device object>},
"user": {<user object>},
"at": 2,
"tmax": 2000,
"cur": ["USD"],
"bcat": ["IAB7-3"],
"badv": ["google.com"],
"ext": {
"vungle": {
"badvid": ["2f00ca35ab0abe4df11da700c"]
}
}
}

1.3 Versionamiento

Con el tiempo, algunos campos se vuelven obsoletos, por lo tanto, para asegurar la máxima compatibilidad, Vungle Exchange respetará todos los campos "obsoletos" mencionados en la especificación OpenRTB 2.3 de Vungle más reciente. La eliminación de todos los campos "obsoletos" se programa para la próxima actualización de la especificación, en cuyo punto Vungle Exchange queda liberado de la responsabilidad de mantener los campos obsoletos.

Todos los campos eliminados aún permanecerán en la especificación con una etiqueta de "eliminado" para indicar que el campo ya no es admitido. Utilizamos la etiqueta de "eliminado" para aplicar una especificación semántica: cada campo, una vez definido, permanece único en el ámbito para el que fue definido durante la vigencia de la especificación. Esto significa que si el campo 'id' se vuelve obsoleto y luego se elimina de una especificación determinada, nunca volverá a utilizarse en una futura revisión con un significado diferente.

1.3.1 Versionamiento semántico

El versionamiento de la especificación también seguirá las pautas de Semver 2.0.0, a saber:

  • Una actualización importante de la versión puede romper la compatibilidad con versiones anteriores; por ejemplo, un campo que es "obsoleto" en la versión X es "eliminado" en la versión X+1.
  • Una actualización secundaria de la versión no debería romper la compatibilidad con versiones anteriores; entre los ejemplos se incluye un campo que está en uso que se marca como "obsoleto"; o un campo que se marca como no obligatorio y obsoleto.
  • Una actualización de la versión parcheada no debe romper la compatibilidad con versiones anteriores; por ejemplo, corregir un error tipográfico en la descripción de la especificación.

1. Solicitud

2.1 Campos obligatorios y opcionales

Notas sobre la columna Obligatorio en las próximas secciones:

  • Sí: con el consumo descendente de este campo siempre se puede esperar un valor no vacío, con un formato correcto basado en el tipo especificado.
  • No: con el consumo descendente no se debe esperar la existencia de este campo o la validez del valor. La validación del valor por parte del consumidor es obligatoria, pero no es necesaria para el tipo.
  • Predeterminado: todos los campos que no se mencionan en OpenRTB 2.3.1 son no obligatorios por defecto.

2.2 Protocolo de negociación

Vungle Exchange admite la comunicación mediante HTTP/2 por medio del protocolo de negociación; de lo contrario, la opción predeterminada es HTTP/1.1.

2.3 Encabezados de las solicitudes

Cada solicitud de puja tendrá los siguientes encabezados HTTP personalizados según se especifica en el protocolo de OpenRTB:

X-OpenRTB-Version: 2.3

Además de los encabezados HTTP personalizados, Vungle Exchange también vincula los siguientes encabezados estándar:

Content-Type: application/json; charset=utf-8
Accept: application/json 

Por último, Vungle Exchange vincula un encabezado personalizado para indicar la revisión de la especificación de OpenRTB de Vungle:

X-Vungle-OpenRTB-Version: 2

2.4 Objeto BidRequest

Campo Tipo Obligatorio Descripción
id string

ID de solicitud de puja generado por Vungle Exchange; por ejemplo, '570b0eb14e67c98f761a0ca0'.

imp

matriz de objeto

Consulte el Objeto de impresión.
app objeto Consulte el Objeto de aplicación.
device objeto Consulte el Objeto de dispositivo.
at entero

Tipo de subasta, por ejemplo, '2' para la subasta de segundo precio. Vungle Exchange solo ejecuta subastas de segundo precio, así que este valor siempre es '2'.

tmax entero

Tiempo máximo en milisegundos para enviar una respuesta de puja completa; este valor siempre es '250'.

cur matriz de cadena no

Lista de las divisas permitidas para la subasta en ISO-4217-alpha; por ejemplo, ["USD", "CNY", "EUR"]. Actualmente solo admitimos "USD".

bcat matriz de cadena no Consulte la sección 5.1. OpenRTB 2.3.1.
regs objeto no Consulte la sección 3.2.16. OpenRTB 2.3.1.
test entero no

Aunque la subasta se encuentre en modo de prueba (1), o en modo en vivo (0); las subastas de prueba no se facturan.

2.4.1 Objeto de impresión

Campo Tipo Obligatorio Descripción
id string ID de impresión generado por Vungle Exchange; por ejemplo, '3a06eb14e67c98f761add01'.
displaymanager string Gestor de pantalla de la oferta; Vungle usa este campo para especificar la tecnología de SDK que se utiliza, debido a que distinguimos entre las plataformas móviles de SDK; por ejemplo, 'Vungle' for iOS, 'VungleDroid' for Android, and 'VungleWindows' para Windows, seguido de la versión del SDK en el siguiente campo.
displaymanagerserver string Versión del gestor de pantalla de la oferta; Vungle la usa para especificar la versión del SDK; por ejemplo, '3.3.1'.
bidfloor float Precio de puja mínimo para que una puja sea elegible, por ejemplo, '8.72'.
bidfloorcur string Las divisas para la impresión en ISO-4217-alpha; por ejemplo, 'USD'.
video objeto no Consulte el Objeto de video.
tagid string no ID de referencia de ubicación correspondiente a la impresión dada, por ejemplo, 'placement_name_1af44fda'.
instl entero no Ya sea que la impresión represente pantalla completa/intersticial (1), o no (0). Actualmente, Vungle Exchange solo admite pantalla completa/intersticial (1).
secure entero no Bandera para indicar si la impresión requiere recursos creativos y marcado de URL HTTPS seguros, donde 0 = no seguro y 1 = seguro.
ext objeto no Vungle siempre requiere recursos y marcado seguros (1).

2.4.2 Objeto de video

Campo Tipo Obligatorio Descripción
mimes matriz de cadena Tipos de contenido MIME admitidos. Vungle Exchange solo admite ["video/mp4"].
h entero Altura del video.
w entero Ancho del video.
minduration entero no Cantidad mínima de segundos durante la cual el video se debe reproducir.
maxduration entero no Cantidad máxima de segundos durante la cual el video se puede reproducir.
delivery matriz de entero no Lista admitida de métodos de entrega de video: (progresivo o streaming). Consulte la sección 5.13. OpenRTB 2.3.1.
minbitrate entero no Tasa de puja mínima en kbps. Vungle Exchange actualmente solo admite 250.
maxbitrate entero no Tasa de puja máxima en kbps, por ejemplo 500.
protocols matriz de entero no Consulte la sección 5.8. OpenRTB 2.3.1; por ejemplo, [2, 5].
boxingallowed entero no Ya sea que se permita el encajonamiento del video (1) o no (0). El valor para esto siempre es '1'.
playbackmethod matriz de entero no Consulte la sección 5.9. OpenRTB 2.3.1.
startdelay entero no Consulte la sección 5.10. OpenRTB 2.3.1. El valor para esto siempre es '0'.

2.4.3 Objeto de aplicación

Campo Tipo Obligatorio Descripción
id string ID específico de Exchange. Para Vungle, esta es la ID de la tienda de aplicaciones; por ejemplo, '3709293'.
Quizás esta ID no signifique nada para la DSP, pero puede ser utilizada por la DSP para comparar y reconciliar los conflictos de generación de informes.
bundle string La ID de mercado única, es un identificador de la aplicación específico de la plataforma que debe ser único para la aplicación e independiente de Vungle Exchange.
- En Android, debe ser el nombre de un paquete (por ejemplo, 'com.supercell.hayday').
- En iOS, es una ID numérica.
publisher objeto Consulte el Objeto del editor.
name string no Nombre de la aplicación; por ejemplo, 'Hay Day'.
storeurl string no URL de la tienda de aplicaciones; por ejemplo, 'https://itunes.apple.com/us/app/hay-day/id506627515?mt=8#'.
cat matriz de cadena no Consulte la sección 5.1. OpenRTB 2.3.1.
privacypolicy entero no Ya sea que la aplicación tiene una política de privacidad (1), o no (0). Vungle Exchange solo admite '1' para este campo.
paid entero no Ya sea que la aplicación sea paga (1) o no (0).
keywords string no Lista separada por comas de las etiquetas para la aplicación del editor.
ext objeto no DESCRIPCIÓN

2.4.4 Extensión de la aplicación

Campo Tipo Obligatorio Descripción
altid string no Una ID específica de Vungle Exchange secundaria que identifica de manera única la aplicación del editor; por ejemplo, '3a06eb14e67c98f761add01'.
sdk objeto no Consulte el Objeto de la extensión del SDK.
wtags matriz de cadena no Lista blanca de etiquetas de la aplicación del editor.
btags matriz de cadena no Lista negra de etiquetas de la aplicación del editor.
bundleid string no Nombre del paquete o identificador del paquete de la aplicación.
tags matriz de cadena no Obsoleto; use palabras clave.

2.4.5 Extensión del SDK

Campo Tipo Obligatorio Descripción
name string Una cadena que identifica una familia de SDK del agente de SDK instalado en la aplicación host. Por ejemplo, 'VungleDroid', 'Vungle', or 'VungleWindows'.
ver string Cadena que describe la versión del agente de SDK instalado en la aplicación host.
plugin string no Nombre del plugin del SDK con el que se genera el agente de SDK; por ejemplo, 'native', 'unity'.
pluginver string no Versión del plugin del SDK con el que se genera el agente de SDK; por ejemplo, '1.0'.

2.4.6 Objeto del editor

Campo Tipo Obligatorio Descripción
id string ID del editor generado por Vungle Exchange, por ejemplo, '570ffeb14e67998f761a791c'.
name string no Nombre del editor; por ejemplo, 'Supercell Oy'.
cat matriz de cadena no Consulte la sección 5.1. OpenRTB 2.3.1.

2.4.7 Objeto de dispositivo

Campo Tipo Obligatorio Descripción
ua string Cadena del agente del usuario del navegador del dispositivo; por ejemplo, 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'.
ip string No es obligatorio cuando el campo ipv6 está presente. Esta es la dirección IP de la impresión; por ejemplo, '212.14.27.104'.
ipv6 string No es obligatorio cuando el campo ip está presente. La dirección IPv6 de la impresión; por ejemplo, '3ffe:1900:4545:3:200:f8ff:fe21:67cf'.
h entero Altura de la pantalla del dispositivo en píxeles.
w entero Ancho de la pantalla del dispositivo en píxeles.
connectiontype string Consulte la sección 5.18. OpenRTB 2.3.1.
ifa string ID aprobado para el uso del anunciante en texto no cifrado; por ejemplo, 'e4fe9bdecaa047b6908dffba3fa184f2'.
geo objeto no Consulte el Objeto de geográfico.
make string no Marca del dispositivo.
model string no Modelo del dispositivo.
os string no SO del dispositivo; por ejemplo, 'iOS', 'Android'. Valor de enumeración de:
- 'iOS'
- 'Android'
- 'Windows'
osv string no Versión del SO del dispositivo; por ejemplo, '9.1', '8.0'.
dnt entero no Ya sea que el dispositivo especifique "No realizar el seguimiento" (1) o no (0).
lmt entero no Ya sea que el dispositivo especifique "Limitar seguimiento de anuncios" (1) o no (0).
devicetype string no Consulte la sección 5.17. OpenRTB 2.3.1.
language string no Idioma del dispositivo en ISO-639-1-alpha-2; por ejemplo, 'en'.
carrier string no Proveedor o ISP; por ejemplo, 'VERIZON'.
ext objeto no Consulte el objeto extensión del dispositivo.

2.4.8 Extensión del dispositivo

Campo Tipo Obligatorio Descripción
tz string no Configuración de la zona horaria del dispositivo con el formato del nombre de la zona en la base de datos de la zona horaria IANA; por ejemplo, 'America/Los_Angeles'.
vungleua string no Obsoleto: Utilice Application.ext.vungle.sdk
sdcard entero no Ya sea que el almacenamiento en tarjeta SD esté disponible para dispositivos Android (1) o no (0).
volume float no Valor entre 0 y 1 que denota el volumen del porcentaje del dispositivo.
muted entero no 0 = falso 1 = verdadero; enumeración necesaria.
idfv string no

ID para proveedor en dispositivos iOS; una cadena alfanumérica que identifica de manera única un dispositivo para el proveedor de la aplicación; por ejemplo, '00000000-0001-4d3a-8f98-233623cd8d12'.

El mismo dispositivo puede contener diferentes valores de IDFV según si la aplicación en la solicitud de puja pertenece a un proveedor diferente.

marketplace string no

El mercado de aplicaciones instalado en el dispositivo. Posibles valores son:

  • 'google'
  • 'apple'
  • 'amazon'
is_sideload_enabled entero no Indicador booleano que indica si el dispositivo permite instalaciones de aplicaciones desde fuentes "desconocidas". Si '1' (verdadero), entonces se permiten las aplicaciones desde mercados desconocidos. Si '0' (falso), no se permiten.

2.4.9 Objeto geográfico

Campo Tipo Obligatorio Descripción
country string Código de país en ISO-3166-1-alpha-3; por ejemplo, 'USA'.
lat float no Latitud del dispositivo; por ejemplo, '[-90, 90]'.
long float no Longitud del dispositivo; por ejemplo, '[-180, 180]'.
type entero no Consulte la sección 5.16. OpenRTB 2.3.1.
region string no Código de región en ISO-3166-2; código estatal de 2 letras si es de EE. UU.; por ejemplo, 'CA'.
city string no Nombre de la ciudad con formato libre.
zip string no Código postal.
utcoffset entero no Hora local como el número+/- de minutos de UTC.

2.4.10 Objeto de regulaciones

Campo Tipo Obligatorio Descripción
coppa entero no Bandera que indica si esta solicitud está sujeta a las regulaciones COPPA establecidas por la FTC de EE. UU., donde 0 = no y 1 = sí.
ext objeto no Marcador de posición para las extensiones específicas de Vungle Exchange para OpenRTB.

2.4.11 Objeto PMP

Campo Tipo Obligatorio Descripción
private_auction entero no Indicador de elegibilidad para la subasta para los asientos nombrados en el objeto Ofertas directas, donde 0 = todas las pujas están aceptadas, 1 = las pujas están restringidas a las ofertas especificadas y los términos de estas.
deal matriz de objeto no Objetos del Matriz de oferta (Sección 3.2.18) que transmite las ofertas específicas que se aplican a esta impresión.
ext objeto no Marcador de posición para las extensiones específicas de Vungle Exchange para OpenRTB.

3. Respuesta

3.1 Campos obligatorios y opcionales

Notas sobre la columna Obligatorio en la sección Respuesta:

  • Sí: Vungle Exchange asume que un campo obligatorio siempre tendrá el formato que se especifica, no vacío, con el tipo especificado; los valores no válidos pueden tener como resultados la inhabilitación para la subasta.
  • Recomendado: Vungle Exchange utilizará el campo para ayudar en el proceso de la subasta si el valor del campo tiene el formato que se especifica; un campo vacíos o no válido no tiene un impacto negativo en la elegibilidad para la subasta.
  • No: Vungle Exchange no requiere que el campo exista.
  • Predeterminado: todos los campos que no se mencionan en OpenRTB 2.3.1 tienen un requisito predeterminado de 'No'. Además, todos los campos deben coincidir con el tipo especificado, o pueden afectar de manera negativa la elegibilidad de la subasta.

3.2 Encabezados de las respuestas

Los encabezados de las respuestas deben contener el encabezado "Tipo de contenido" con uno de los valores aceptados desde los encabezados de las solicitudes anteriores. Por ejemplo,

Content-Type: application/json 

3.3 Código de estado de la respuesta

Todas las repuestas deben ser 200 o 204. Cualquier otro código de respuesta HTTP puede afectar de manera negativa la elegibilidad para la subasta de DSP.

3.4 Señalización de la razón para que no haya puja

Se recomienda que las plataformas del lado de la demanda (DSP) envíen las razones para que no haya puja al decidir no pujar. Esta información puede ayudar a Vungle Exchange a detectar y corregir los posibles problemas de integración. La señalización para que no haya puja debe seguir la especificación de la sección 7.4 OpenRTB 2.3.1. Una señalización para que no haya puja bien formada con la razón para que no haya puja debe ser similar a esta:


{"id": "1234567890", "seatbid": [], "nbr": 2}

3.5 Objeto BidResponse

Campo Tipo Obligatorio Descripción
id string ID de BidRequest generado por Vungle Exchange; por ejemplo, '570ffeb14e67998f761a791c'. Debe coincidir con la id en el objeto BidRequest.
bidid string no Una ID de respuesta única generada por el licitador para ayudar con el registro/seguimiento.
cur string no Divisa de la puja utilizando códigos ISO-4217 alpha. Vungle Exchange actualmente solo admite USD y trata cualquier valor como USD.
seatbid matriz de objeto Matriz de objetos seatbid; 1+ obligatorio si se va a hacer una puja.
nbr entero no Una razón para no hacer una puja, según se enumera en 5.19 de la especificación OpenRTB 2.3.1.
ext objeto no  

3.5.1 Objeto SeatBid

Campo Tipo Obligatorio Descripción
seat string no ID del asiento del licitador en cuyo nombre se hace la puja. Consulte OpenRTB 2.3.1.
bid matriz de objeto Consulte el Objeto de puja. Debe existir al menos una puja.


3.5.2 Objeto de puja

Campo Tipo Obligatorio Descripción
id string ID de puja generada por las DSP individuales.
impid string ID de impresión con respecto a la impresión de la solicitud de puja por la que se está licitando. Debe coincidir con la ID en el objeto de Impresión de solicitud de puja.
price float Precio de puja expresado en unidad de CPM; por ejemplo, '10.30'.
nurl string no URL de aviso de ganador invocada por Vungle Exchange si la puja gana.
adm string Marcado de anuncio para presentar después de ganar la subasta. Consulte la sección Especificación de marcado de anuncio.
cid string recomendado ID de campaña con proxy de DSP.
crid string recomendado ID de la creación reemplazada por DSP.
adomain matriz de cadena recomendado Dominios del anunciante para la verificación de la lista de bloqueo; por ejemplo, ["supercell.com"].
bundle string recomendado La ID de mercado única, es un identificador de la aplicación específico de la plataforma que debe ser único para la aplicación e independiente de Vungle Exchange.
- En Android, debe ser el nombre de un paquete (por ejemplo, 'com.supercell.hayday').
- En iOS, es una ID numérica.
h entero recomendado Altura de la creación.
w entero recomendado Ancho de la creación.
cat matriz de cadena no Categorías de contenido IAB; consulte la sección 5.1. OpenRTB 2.3.1.
iurl string no URL de notificación perdida.
dealid string no Consulte el deal.id del objeto BidRequest si esta puja pertenece a una oferta directa de un mercado privado.
adid string no ID de un anuncio precargado que se va a presentar si gana la puja.
ext objeto no  

4. Ejemplos

4.1 Ejemplo de solicitud


{
    "id": "58ed309efa8936087efd1349",
    "imp": [{
        "id": "58ed309efa8936087efd134a",
        "video": {
            "mimes": ["video/mp4"],
            "minduration": 5,
            "maxduration": 30,
            "protocols": [2, 5],
            "w": 1080,
            "h": 1920,
            "startdelay": 0,
            "linearity": 1,
            "minbitrate": 250,
            "maxbitrate": 2500,
            "boxingallowed": 1,
            "playbackmethod": [1, 2, 3, 4],
            "delivery": [1, 2],
            "pos": 7
        },
        "displaymanager": "Vungle",
        "displaymanagerver": "3.3.5",
        "instl": 1,
        "bidfloor": 15,
        "bidfloorcur": "USD"
    }],
    "app": {
        "id": "56b8e577819502560b000033",
        "name": "test-pub-app-name",
        "bundle": "1045826890",
        "storeurl": "https://itunes.apple.com/us/app/id1234567?mt=8",
        "cat": [
            "IAB1"
        ],
        "privacypolicy": 1,
        "publisher": {
            "id": "test-pub-app-id",
            "name": "test-pub-app-name",
            "cat": [
                "IAB1"
            ]
        },
        "ext": {
            "vungle": {
                "altid": "5fff577819502560b000033",
                "btags": ["real money gambling", "social casino"],
                "wtags": ["targeted tag", "social"]
            }
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
        "geo": {
            "lat": 47.46,
            "lon": -122.16,
            "type": 1,
            "country": "USA",
            "region": "WA",
            "city": "San Francisco",
            "zip": "94103"
        },
        "dnt": 0,
        "lmt": 0,
        "ip": "192.168.1.1",
        "devicetype": 1,
        "make": "Samsung",
        "model": "SM-J200G",
        "connectiontype": 2,
        "os": "iOS",
        "osv": "8.0",
        "w": 1080,
        "h": 1920,
        "js": 1,
        "language": "en",
        "ifa": "test-ifa",
        "ext": {
            "vungle": {
                "isSdCardAvailable": 1,
                "vungleua": "VungleDroid/3.3.5",
                "tz": "Europe/Kaliningrad",
                "sdcard": 1,
                "volume": 0.13333334,
                "muted": 1
            }
        }
    },
    "bcat": ["IAB7-3", "IAB7-5", "IAB7-28", "IAB7-29", "IAB7-30", "IAB7-39", "IAB7-41", "IAB7-42"],
    "at": 2,
    "cur": ["USD"],
    "tmax": 250
}

4.2 Respuesta de ejemplo


{
  "id": "58ed309efa8936087efd1349",
  "bidid": "5508",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "7735",
      "bid": [
        {
          "id": "5508",
          "impid": "58ed309efa8936087efd134a",
          "price": 50,
          "nurl": "http://bidder.com/won?price=${AUCTION_PRICE}",
          "adm": "http://bidder.com/vast?id=${AUCTION_ID}",
          "cid": "554d550b418461cc3700014d",
          "crid": "57767c29a63510e75f000073"
        }
      ]
    }
  ]
}

5. Especificación de marcado de anuncio

Vungle Exchange admite principalmente tres tipos de marcados: VAST, MRAID y Marcado de anuncios propiedad de Vungle. Si bien cada uno tiene su especificación de alto nivel, para ser considerado un marcado válido para razones de rendimiento, también debe cumplir con los siguientes requisitos adicionales.

5.1 VAST

La siguiente etiqueta debe aparecer en los primeros 100 bytes del campo 'adm', o la carga de la respuesta 'nurl':

<VAST version="2.0">

5.2 Sustitución de macro

Vungle Exchange admite una sustitución de macro para el precio de la subasta en el campo nurl del objeto de puja en la respuesta de la puja. Por ejemplo:


"nurl": "http://bidder.com/won?price=${AUCTION_PRICE}"
¿Tiene más preguntas? Enviar una solicitud

Comentarios